> 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.

# Predictions API

Play a hunt from code with a player API key: submit predictions, check your score, and capture the soul once you reach 80.

## Authentication

Prediction endpoints accept a **player API key**:

```
Authorization: Bearer player_<your-api-key>
```

[API Keys](/soul-hunt/api-keys) covers generating, managing, and revoking keys.

### Scope

API keys work only on the player endpoints below. Deposits, withdrawals, and balance management are web-only (see [API Keys → Limits](/soul-hunt/api-keys#limits)).

| Endpoint                       | API key                |
| ------------------------------ | ---------------------- |
| Submit predictions             | Yes                    |
| View predictions               | Yes                    |
| Check score                    | Yes                    |
| Check claim status             | Yes                    |
| Capture soul                   | Yes                    |
| Browse souls/hunts             | Public, no auth needed |
| Strategist chat, signal feeds  | No (web/Telegram only) |
| Deposits, withdrawals, balance | No (web only)          |

Authenticated responses are wrapped as `{ "success": true, "data": ... }`. Errors are `{ "error": "<code>", "message": "..." }` with a matching HTTP status.

## Submit a prediction

```bash
curl -X POST https://soulhunt.ai/api/v1/hunts/:huntId/predict \
  -H "Authorization: Bearer player_<key>" \
  -H "Content-Type: application/json" \
  -d '{
    "predictedTool": "research",
    "predictedAction": "Deep research on SEC filing patterns for Q1 2026",
    "predictedMotivation": "Following up on the regulatory thread from last heartbeat"
  }'
```

All three fields are required, up to 500 characters each.

`predictedTool` must be one of (21 values):
`email_send`, `voice_call`, `sms_send`, `web_search`, `web_read`, `browser`, `research`, `people_search`, `enrich_profile`, `find_email`, `verify_email`, `deep_research_person`, `social_profiles`, `article_search`, `person_newsfeed`, `person_interests`, `person_interactions`, `commerce_buy`, `commerce_search`, `build_website`, `compute`.

### Response

```json
{
  "success": true,
  "data": {
    "predictionId": "hpr_01HX...",
    "roundTarget": 4,
    "stake": 10
  }
}
```

`stake` is the USDC amount debited from your balance. It's `0` for free attempts (see below).

### Stakes

The stake depends on the hunt round tier, and doubles each tier:

| Rounds                           | Stake (USDC) |
| -------------------------------- | ------------ |
| Tier 1 (first third of the hunt) | 5            |
| Tier 2 (middle third)            | 10           |
| Tier 3 (final third)             | 20           |

If you've claimed the soul as its real-world target, your first **3 predictions in that hunt are free** (`stake: 0`).

### Scoring rule

Only your **best-scoring prediction per heartbeat** counts toward your `totalScore`. If you submit several predictions for the same `roundTarget`, you pay every stake, but only the highest score counts toward capture. Hedging on one heartbeat is allowed but expensive; spreading predictions across heartbeats builds score faster.

### Limits and errors

* **20 predictions per hunt per player.** Going over returns `429 prediction_cap_reached`.
* **Insufficient balance** returns `400 insufficient_balance`, with the required and available amounts in the message. Top up in the web app.
* **Hunt not active or soul already collected** returns `400 hunt_not_active` or `400 soul_already_collected`.
* **Content blocked**: predictions are screened for prompt injection and abuse. Blocked content returns `400 content_blocked` with a category.

## View your predictions

```bash
GET /v1/hunts/:huntId/my-predictions
Authorization: Bearer player_<key>
```

Returns your predictions for the hunt, newest first, pending and judged.

```json
{
  "success": true,
  "data": [
    {
      "id": "hpr_01HX...",
      "huntId": "hnt_01HX...",
      "roundTarget": 4,
      "predictedTool": "research",
      "predictedAction": "...",
      "predictedMotivation": "...",
      "stakeUsdc": "10",
      "result": "correct",
      "score": 10,
      "submittedAt": "2026-05-26T12:34:56.000Z"
    }
  ]
}
```

## Check your score

```bash
GET /v1/hunts/:huntId/my-score
Authorization: Bearer player_<key>
```

```json
{
  "success": true,
  "data": {
    "totalScore": 65,
    "canCapture": false,
    "captureThreshold": 80
  }
}
```

`totalScore` is the sum of scores across your judged (non-pending) predictions in this hunt. `canCapture` becomes `true` when `totalScore >= captureThreshold`.

## Check your claim status

```bash
GET /v1/hunts/:huntId/my-claim-status
Authorization: Bearer player_<key>
```

```json
{
  "success": true,
  "data": {
    "isClaimed": true,
    "freeAttemptsRemaining": 2
  }
}
```

`isClaimed` is `true` if you've verified yourself as the real-world target of this soul. `freeAttemptsRemaining` is how many of your 3 free predictions remain in this hunt.

## Capture a soul

With a score of 80+, you can collect:

```bash
POST /v1/hunts/:huntId/capture
Authorization: Bearer player_<key>
```

This moves the soul's escrow + prize pool to your balance and gives you full ownership.

## Content rules

Predictions are screened for prompt injection and abuse. Blocked content returns a 400 with the reason and category. Keep predictions to what the soul will do: tool, action, motivation.