Skip to main content
The CLOB API has three auth tiers. Each route picks exactly one.
TierUsed byRequired credentials
L0AnyoneNone
L1Logged-in web usersAuthorization: Bearer <privy-jwt>
L2Bots or usersPrivy JWT or fs-api-key + fs-api-secret headers
  • L0 — all GET /v1/markets/* routes. No auth.
  • L1 — API-key management (/v1/auth/api-keys*). Privy JWT only — you cannot manage keys with a key.
  • L2 — trading and private reads (/v1/orders*, /v1/fills, /v1/positions, /v1/auth/ws-token). Accepts a JWT or an API-key pair.

​
API keys

API keys are how bots authenticate. Each key is bound to the wallet that created it and carries a set of permissions.

​
Headers

Send both headers on every L2 request: 
fs-api-key: fs_key_abc123...
fs-api-secret: fs_secret_...

​
Lifecycle

All key-management routes require an L1 Privy JWT (not an API key).
1

Create a key

curl -X POST https://api.foresight.now/v1/auth/api-keys \
  -H "Authorization: Bearer $PRIVY_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "permissions": ["read", "trade"] }'

{ "key_id": "fs_key_abc123...", "secret": "fs_secret_..." }
The secret is returned only once. Store it immediately — it cannot be retrieved later, only rotated. The server keeps a bcrypt hash, never the plaintext.
2

List your keys

GET /v1/auth/api-keys returns key metadata (never secrets), including permissions and last_used_at.
3

Rotate a secret

POST /v1/auth/api-keys/{key_id}/regenerate issues a new secret. The old one stops working immediately.
4

Revoke a key

DELETE /v1/auth/api-keys/{key_id} soft-revokes the key. It stops working immediately.
If permissions is omitted on creation it defaults to ["read"].

​
Permissions

Permissions gate L2 routes. They are checked only for API keys — a Privy JWT user implicitly has all permissions.
PermissionUnlocks
readAll list/get endpoints: GET /v1/orders, /v1/fills, /v1/positions
tradePOST /v1/orders, POST /v1/orders/cancel, POST /v1/orders/{hash}/cancel-onchain

​
Wallet binding

A key can only trade for the wallet that created it. POST /v1/orders also checks that each order’s EIP-712 signer equals the authenticated wallet — a mismatch returns a WALLET_MISMATCH error inline for that order. You cannot place orders on behalf of another wallet.

​
WebSocket tokens

Private WebSocket channels require a short-lived token, not your API-key headers. 
curl -X POST https://api.foresight.now/v1/auth/ws-token \
  -H "fs-api-key: $FS_API_KEY" \
  -H "fs-api-secret: $FS_API_SECRET"

{ "token": "deadbeef...", "expires_in": 60 }
  • Single-use. The token is consumed by the first WS connection that uses it.
  • 60-second TTL. Re-issue one per connection / reconnect.
  • Pass it as a query param: wss://api.foresight.now/v1/ws?token=<token>.
WS tokens authenticate the WebSocket upgrade only. They do not authenticate REST calls — REST always uses a JWT or API-key headers.