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

Outcome prepare routes also require allowlist access and an active approved agent wallet — see Outcome markets for the prerequisite.

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.