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.
- Sign in at soulhunt.ai with Privy.
- 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. - Open your profile and generate an API key.
- Copy the key immediately. It is shown once and never stored in plaintext; the server keeps only a SHA-256 hash.
Key format
Send it as a bearer token:
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:
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:
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 lists the endpoints that accept the key.