Authentication
The Spreadr API accepts two authentication methods. Pick the one that matches your use case.
API Key (recommended for bots)
For programmatic / headless access. Long-lived, scoped, optionally IP-restricted.
Pass the key in the X-API-Key header on every request:
curl https://api.spreadr.xyz/api/v1/trades \
-H "X-API-Key: sprdr_YOUR_API_KEY"Scopes
API keys are scoped at creation time and cannot be elevated later. Choose the minimum scope your bot needs.
| Scope | What it allows |
|---|---|
trades:read | List trades, get trade details, get trade events, subscribe to WS event streams |
trades:write | Create, amend, cancel trades |
account:read | View linked wallets, linked exchanges, maintenance status |
Getting a key
API keys are currently issued by the Spreadr team — reach out via the
support channels in the app footer to request one. Each key is scoped at
creation, optionally IP-restricted (requests from other IPs are rejected
with 403), and expires after at most 365 days. To revoke a key, contact
support — revocation is immediate.
Self-service key management will return to the app in a future release.
API keys cannot:
- Link or unlink wallets
- Add or remove exchange credentials
- Create other API keys
Those operations require the Privy JWT (see below).
Privy JWT (browser sessions)
Used by the web terminal. After signing in, the frontend includes the issued JWT on every request:
Authorization: Bearer <privy_jwt_token>The JWT carries your user_id and primary wallet_address, verified
server-side against Privy's JWKS public keys on every request.
Token refresh
Privy tokens are short-lived (~15 min). The web terminal refreshes silently via
getAccessToken(). If you're using the JWT programmatically, you'll need to
handle refresh yourself — but in practice, don't use JWT programmatically;
use an API key instead.
Privy-only endpoints
The following endpoints require Privy JWT and reject API-key auth:
| Method | Path | What it does |
|---|---|---|
POST | /api/v1/wallets/link | Link a wallet to your account |
DELETE | /api/v1/wallets/{address} | Unlink a wallet |
POST | /api/v1/credentials/{exchange} | Add exchange credentials |
DELETE | /api/v1/credentials/{exchange}/{wallet} | Remove exchange credentials |
These are restricted to JWT because they affect long-lived account state and should be performed under an interactive user session, not by automation.
Auth-verify endpoint
The web terminal calls POST /api/v1/auth/verify immediately after sign-in to
confirm the JWT and bootstrap the session. You generally don't need to call
this yourself — it's part of the frontend's startup flow.
Both auth methods scope every query by the authenticated user_id. No
user-facing endpoint accepts a user_id from request bodies or URL paths —
it's always extracted from the verified session.