Authentication

Proof	What it proves
JWT	The caller is an authenticated user
Wallet or agent signature	The user approved a trading action

Send JWTs with:

Authorization: Bearer <jwt>

When waitlist access is enabled, protected routes also check whether the user is allowed to trade or read gated data.

Access state

Use /v1/access/self to check the current identity and access level.

curl -s "{API_BASE_URL}/v1/access/self" \
  -H "Authorization: Bearer $JWT"

Users who are not allowed can submit an access request:

curl -s -X POST "{API_BASE_URL}/v1/access/request" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","note":"API integration"}'

Wallet identity

Routes that act on a wallet require the JWT to resolve to a wallet address. Email-only identities can use identity routes, but they cannot trade.

Wallet addresses are normalized to lowercase 0x format.

Direct signed orders

Some scalar trading routes accept a user-signed EIP-712 payload. The direct order envelope contract is SignedOrderRequest { order: ClientOrder, signature }:

{
  "order": {
    "asset": "NYCTMP1",
    "side": "buy",
    "size": "10.0000",
    "price": "575.00",
    "tif": "GTC",
    "nonce": 1710000000000,
    "timestamp": 1710000000000,
    "reduce_only": false
  },
  "signature": "0x..."
}

Use exact decimal strings. For scalar orders:

Field	Expected shape
asset	Scalar asset expected by the deployment
side	buy or sell
price	Encoded mark as a decimal string
size	Size string using the market precision
tif	Time in force, such as GTC, IOC, or ALO
reduce_only	true for closes and risk-reducing orders
timestamp	Millisecond timestamp within the server freshness window
nonce	Monotonically increasing value

Reused nonces are rejected.

Agent wallet flows

Agent flows split trading into prepare and submit steps:

1. Client calls a prepare endpoint.
2. API returns the canonical action, connection id, EIP-712 domain, and message.
3. The approved agent wallet signs the returned message.
4. Client calls the matching submit endpoint.

Scalar agent routes:

Step	Endpoint
Prepare order	POST /v1/orders/prepare
Submit order	POST /v1/orders/submit
Prepare leverage	POST /v1/leverage/prepare
Submit leverage	POST /v1/leverage/submit
Approve agent	POST /v1/agent/approve

Outcome routes use the same pattern:

Step	Endpoint
Prepare order	POST /v1/outcomes/orders/prepare
Submit order	POST /v1/outcomes/orders/submit
Prepare cancel	POST /v1/outcomes/cancel/prepare
Submit cancel	POST /v1/outcomes/cancel/submit

Check /v1/runtime-config before showing outcome flows. When outcomes are disabled, outcome routes are unavailable. When outcome writes are enabled, prepare routes require JWT authentication, RIPBET allowlist access, and an active approved agent wallet. If the API returns agent_not_approved, call POST /v1/agent/approve first, then retry.

Prepared outcome actions expire. If a submit fails because the prepared payload is stale, prepare a new action and sign the new message.

WebSocket auth

When waitlist access is enabled, WebSocket connections require the same JWT. Prefer Authorization: Bearer <jwt> on the upgrade request.

Use ?token=<jwt> only when the client platform cannot set headers. URL tokens must be short-lived, scoped to WebSocket use when possible, and redacted from access logs, metrics, traces, crash reports, and analytics.