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

# API Keys

Player API keys let you submit predictions and check your score programmatically. They are for your own bots and scripts, not for third-party platforms acting on your behalf. A key can spend your balance on predictions. It cannot deposit, withdraw, or rotate itself.

## Generating a key

Creating a key requires a signed-in session and a prior deposit, and must be done in the web app. There is no API-only bootstrap.

1. Sign in at [soulhunt.ai](https://soulhunt.ai) with Privy.
2. Deposit USDC (card, on-chain, or Privy fund-wallet; any amount). With no deposit history and a zero balance, key generation fails with `403 deposit_required`.
3. Open your profile and generate an API key.
4. **Copy the key immediately.** It is shown once and never stored in plaintext; the server keeps only a SHA-256 hash.

### Key format

```
player_<64-hex-characters>
```

Send it as a bearer token:

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

### One key per player

Each player has at most one active key. Generating a new key revokes the previous one immediately, so you can't run two keys in parallel. If you lose a key, generate a new one and update your scripts.

## Revoking a key

Revoke from the profile UI, or call this endpoint while signed in with Privy:

```bash
DELETE /v1/players/me/api-key
```

A revoked key is rejected with `401 invalid_api_key`.

## Brute-force protection

Repeated invalid key attempts trigger a tiered lockout (up to 24 hours). Treat your key like a password: don't commit it to git or paste it into shared notebooks, and rotate it if you suspect exposure.

## Limits

An API key plays the game; moving money needs a Privy session:

| Operation                                 | Available via API key       |
| ----------------------------------------- | --------------------------- |
| Submit predictions                        | Yes                         |
| View own predictions, score, claim status | Yes                         |
| Capture a soul                            | Yes                         |
| Generate or revoke an API key             | **No** (Privy session only) |
| Deposit, withdraw, view balance           | **No** (Privy session only) |
| Strategist chat, signal feeds             | **No** (web/Telegram only)  |

A script can spend your existing balance on predictions but cannot top up your account, withdraw funds, or rotate its own credentials. Moving money requires signing in to the web app.

[Predictions API](/soul-hunt/predictions-api) lists the endpoints that accept the key.