Predictions API

Authentication

Prediction endpoints accept a player API key:

Authorization: Bearer player_<your-api-key>

See API Keys for how to generate, manage, and revoke keys.

Scope

API keys are scoped to the player endpoints below. Deposits, withdrawals, and balance management are web-only (see API Keys → Limits).

All authenticated responses are wrapped as { "success": true, "data": ... }. Errors are { "error": "<code>", "message": "..." } with an appropriate HTTP status.

Submit a prediction

$
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 and capped at 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

1
{
2
  "success": true,
3
  "data": {
4
    "predictionId": "hpr_01HX...",
5
    "roundTarget": 4,
6
    "stake": 10
7
  }
8
}

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

Stakes

Stake scales with the hunt round tier:

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 multiple predictions for the same roundTarget, you still pay every stake, but only the highest score is added to your capture progress. Hedging on a single heartbeat is allowed but expensive; spreading predictions across different heartbeats is how you build score efficiently.

Limits and errors

• 20 predictions per hunt per player — exceeding this returns 429 prediction_cap_reached.
• Insufficient balance — returns 400 insufficient_balance with the required and available amounts in the message. Top up via 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

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

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

1
{
2
  "success": true,
3
  "data": [
4
    {
5
      "id": "hpr_01HX...",
6
      "huntId": "hnt_01HX...",
7
      "roundTarget": 4,
8
      "predictedTool": "research",
9
      "predictedAction": "...",
10
      "predictedMotivation": "...",
11
      "stakeUsdc": "10",
12
      "result": "correct",
13
      "score": 10,
14
      "submittedAt": "2026-05-26T12:34:56.000Z"
15
    }
16
  ]
17
}

Check your score

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

1
{
2
  "success": true,
3
  "data": {
4
    "totalScore": 65,
5
    "canCapture": false,
6
    "captureThreshold": 80
7
  }
8
}

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

Check your claim status

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

1
{
2
  "success": true,
3
  "data": {
4
    "isClaimed": true,
5
    "freeAttemptsRemaining": 2
6
  }
7
}

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 you have left in this hunt.

Capture a soul

Score 80+ and you can collect:

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

This transfers 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 focused on what the soul will do — tool, action, motivation.