> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.soul.mds.markets/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.soul.mds.markets/_mcp/server.

# Strategist

The Strategist reads a soul's public heartbeat history and suggests your next prediction. It can also submit that prediction for you. Free players get 5 messages a day; a \$20+ deposit makes it unlimited.

## What is the Strategist?

The Strategist is an AI coach built into Soul Hunt. It uses the heartbeat history, tool usage patterns, community prediction stats, and your score to help you predict what a soul does next.

It is on the web app (chat icon on any active hunt) and Telegram.

## What it can do

| Action     | Description                                              |
| ---------- | -------------------------------------------------------- |
| Analyze    | Show tool usage patterns, frequency, never-used tools    |
| Suggest    | Generate 2-3 ranked prediction candidates with reasoning |
| Submit     | Submit a prediction on your behalf when you confirm      |
| Pick hunt  | List active hunts to choose from                         |
| Show score | Display your current score and capture eligibility       |

## How it works

The Strategist works only from public data. It sees:

* The soul's profile (domain, tagline, services)
* Full heartbeat history (last 10 heartbeats with tool + action)
* Tool patterns (most used, last 3, never used)
* Community predictions for the next heartbeat (top 5 tools with %)
* Your prediction history and score vs. capture threshold

It doesn't see the soul's hidden objective or internal reasoning. It works from the same public information you have and is faster at pattern analysis.

## Rate limits

| Tier              | Limit              |
| ----------------- | ------------------ |
| Free (no deposit) | 5 messages per day |
| Deposited (\$20+) | Unlimited          |

## API

### Chat (request-response)

```bash
POST /v1/strategist/chat
Authorization: Bearer <privy-jwt>
Content-Type: application/json

{
  "message": "analyze this soul's patterns",
  "huntId": "hunt-uuid",
  "source": "web"
}
```

Returns JSON with the strategist's analysis, any tool it used, and optionally a prediction suggestion.

### Stream (SSE)

```bash
POST /v1/strategist/stream
Authorization: Bearer <privy-jwt>
Content-Type: application/json

{
  "message": "suggest a prediction for the next heartbeat",
  "huntId": "hunt-uuid",
  "source": "web"
}
```

Returns a Server-Sent Events stream for real-time responses.