> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocx.global/llms.txt
> Use this file to discover all available pages before exploring further.
# API overview
> Base URL, authentication, request and response shapes, rate limits, and versioning for the OCX API
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.
Market data, trading, account, and wallet operations over plain HTTPS JSON.
Server-Sent Events for live order books, marks, fills, and positions.
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.
No credentials. All market-data reads — markets, order books, stats,
candles, the options board, and public streams.
A signed-in session from Sign-In With Ethereum (SIWE). Required for placing
single orders and for your own account, wallet, and key management.
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](/get-started/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:
```bash Cookie theme={null}
# Browsers send the session cookie automatically after /auth/siwe.
curl -s -b cookies.txt "https://{API_BASE}/wallet/balance"
```
```bash Bearer theme={null}
# Programmatic clients can present the same token as a bearer header.
curl -s "https://{API_BASE}/wallet/balance" \
-H "Authorization: Bearer "
```
### API key
Provision an API key from a signed-in session (see
[API key management](/api-reference/rest#api-keys)), then send it on every
automated request:
```bash theme={null}
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.
```json theme={null}
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](/api-reference/websockets).
## 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.
```json theme={null}
{
"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](/api-reference/errors).
## 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:
| Header | Meaning |
| ----------------------- | -------------------------------------- |
| `X-RateLimit-Limit` | Requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests left in the window |
| `X-RateLimit-Reset` | When 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.