Skip to main content
The OCX API is a single HTTPS surface that fronts every venue — perpetuals, dated futures, options, and spot. All traffic flows through one gateway that authenticates you and routes to the matching engines, so you work against one base URL with one consistent request and response contract.

REST endpoints

Market data, trading, account, and wallet operations over plain HTTPS JSON.

Streaming

Server-Sent Events for live order books, marks, fills, and positions.

Errors & limits

Status codes, error shapes, and rate-limit headers.

​
Base URL

Every endpoint documented here is served through the public gateway. Send all requests to your OCX API host: 
https://{API_BASE}
All request and response bodies are JSON. Monetary and size values are returned as decimal strings (for example "68210.5", not 68210.5) to preserve precision — parse them with a decimal-safe type, never a native float.

​
Authentication

OCX has three access tiers. Each endpoint in this reference is tagged with the tier it requires.

Public

No credentials. All market-data reads — markets, order books, stats, candles, the options board, and public streams.

Session

A signed-in session from Sign-In With Ethereum (SIWE). Required for placing single orders and for your own account, wallet, and key management.

API key

An x-api-key header for programmatic access. Accepted on high-throughput trading endpoints (previews, bulk quoting, cancel-all, algo streams).

​
Session (SIWE)

Sign in with your wallet to open a session. The full flow is covered in Authentication; in short, request a nonce, sign an EIP-4361 message, and exchange it for a session. The session is a signed JWT valid for 7 days, delivered as an httpOnly cookie and accepted either way: 
# Browsers send the session cookie automatically after /auth/siwe.
curl -s -b cookies.txt "https://{API_BASE}/wallet/balance"

​
API key

Provision an API key from a signed-in session (see API key management), then send it on every automated request: 
curl -s "https://{API_BASE}/perps/orders/preview" \
  -H "x-api-key: ocx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "marketId": "BTC-PERP", "side": "buy", "type": "limit", "price": "68000", "quantity": "0.5" }'
Keys carry a scope: read (market data and account reads) or trade (adds order actions). A key can never create or revoke another key — key management is session-only.
Grant least privilege: give a monitoring bot a read key and an executing bot a trade key. You can pin a key to source IPs and set an expiry when you create it.

​
Response shape

Successful responses return the resource directly as a JSON object or array. There is no envelope wrapper on REST responses — the body is the data. 
GET /perps/market-stats?marketId=BTC-PERP

{
  "marketId": "BTC-PERP",
  "baseSymbol": "BTC",
  "quoteSymbol": "USDC",
  "markPrice": "68210.5",
  "change24hPct": "1.42",
  "volume24hUsd": "18422100",
  "openInterestUsd": "9231000",
  "funding1hPct": "0.0021"
}
Streaming endpoints instead return text/event-stream and wrap each message in a small envelope — see Streaming.

​
Error shape

Errors use standard HTTP status codes with a JSON body describing what went wrong. Handle the status code first, then read the message for detail. 
{
  "error": "INSUFFICIENT_MARGIN",
  "message": "Order requires 512.00 USDC margin; 210.00 available"
}
Common cases: 400 (bad request or insufficient bucket balance), 401 (not authenticated), 403 (wrong scope or forbidden), 404 (unknown resource), 422 (business rejection such as insufficient margin), and 429 (rate limited). The full catalog is in Errors & rate limits.

​
Rate limits

Requests are rate-limited per client. Authenticated and API-key traffic receives a higher budget than anonymous traffic. Every response carries standard headers so you can pace yourself:
HeaderMeaning
X-RateLimit-LimitRequests allowed in the current window
X-RateLimit-RemainingRequests left in the window
X-RateLimit-ResetWhen the window resets
Back off when X-RateLimit-Remaining reaches 0 rather than retrying blindly — a burst of retries against a 429 will keep you throttled. Public market-data reads are cheap; prefer the streaming endpoints over tight polling.

​
Idempotency

Order and quote endpoints accept a clientOrderId for idempotent client-side tracking, and quoting endpoints accept a quoteId to group or replace a market-maker’s quote set in one call. Use them so retries never double-submit.

​
Versioning

The API is served at a single stable base path. OCX evolves the surface additively — new fields and endpoints may appear without notice, so clients should ignore unknown JSON fields. Breaking changes are announced ahead of time. Operational values such as fees, margin requirements, and funding are surfaced through live responses (order preview and market-stats) rather than pinned as constants, so you always read the current schedule.