Authentication

The CLOB API has three auth tiers. Each route picks exactly one.

Tier	Used by	Required credentials
L0	Anyone	None
L1	Logged-in web users	`Authorization: Bearer <privy-jwt>`
L2	Bots or users	Privy 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).

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.

List your keys

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

Rotate a secret

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

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.

Permission	Unlocks
`read`	All list/get endpoints: `GET /v1/orders`, `/v1/fills`, `/v1/positions`
`trade`	`POST /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.

CLOB Trading API

CLOB API Reference

AMM Trade API (Legacy)

API keys

Headers

Lifecycle

Permissions

Wallet binding

WebSocket tokens

​API keys

​Headers

​Lifecycle

​Permissions

​Wallet binding

​WebSocket tokens

API keys

Headers

Lifecycle

Permissions

Wallet binding

WebSocket tokens