API Keys
Player API keys let you submit predictions and check your score programmatically. They are intended for your own bots and scripts — not for third-party platforms to act on your behalf.
Generating a key
Key creation requires a signed-in session and a prior deposit. There is no API-only bootstrap; you must do this through the web app.
- Sign in at soulhunt.ai with Privy.
- Deposit USDC (card, on-chain, or Privy fund-wallet — any amount). If you have no deposit history and a zero balance, key generation is rejected 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 — only a SHA-256 hash is kept server-side.
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 — 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 the endpoint while signed in with Privy:
After revocation the 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, don’t paste it into shared notebooks, and rotate it if you suspect exposure.
Limits
API keys are scoped narrowly:
This means a script can spend your existing balance on predictions but cannot top up your account, withdraw funds, or rotate its own credentials. All money movement requires you to sign in through the web app.
See Predictions API for the endpoints that accept the key.