> For the complete documentation index, see [llms.txt](https://ocx.gitbook.io/ocx-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ocx.gitbook.io/ocx-doc/ocx/api/conventions.md).

# conventions

Common patterns used across the OCX API.

## Identifiers

| Identifier     | Format                    | Example                              |
| -------------- | ------------------------- | ------------------------------------ |
| User ID        | ULID                      | `01HW7ZK5P8J9X2M3T4V6Y8N0B1`         |
| Order ID       | ULID                      | `01HW7ZK5P8J9X2M3T4V6Y8N0B2`         |
| Market ID      | Human-readable symbol     | `BTC-PERP`, `BTC-2026-06-26-60000-C` |
| API Key ID     | `ocx_kid_` + 16 chars     | `ocx_kid_01HW7ZK5P8J9X2M3`           |
| API Key Secret | `ocx_sk_` + long random   | `ocx_sk_long_random_string`          |
| Wallet address | EIP-55 checksummed 0x-hex | `0xAbC0...89F0`                      |

Market ID formats:

| Pattern                               | Meaning                                                   |
| ------------------------------------- | --------------------------------------------------------- |
| `{BASE}-USDC-SPOT`                    | Spot pair, e.g., `BTC-USDC-SPOT`                          |
| `{BASE}-PERP`                         | Perpetual, e.g., `BTC-PERP`                               |
| `{BASE}-USDC-{YYYY-MM-DD}`            | Quarterly future with expiry, e.g., `BTC-USDC-2026-06-26` |
| `{BASE}-{YYYY-MM-DD}-{STRIKE}-{C\|P}` | Option, e.g., `BTC-2026-06-26-60000-C`                    |

## Numbers

All numeric fields are **strings** to avoid precision loss. Parse with a decimal library:

```ts
import Big from 'big.js';
const price = Big(order.price);
```

Never use `parseFloat()` on money-like fields.

## Times

* **Response timestamps** are ISO-8601 strings in UTC (`"2026-04-24T12:00:00.000Z"`).
* **Stream message timestamps** (`engineTs`, `sourceTs`) are **unix milliseconds** (number).
* Query parameters expecting a time (e.g., `from` / `to` on OHLC endpoints) are **unix seconds** (number).

## Pagination

Most list endpoints support `?limit=N` (default 100, max 200 where noted). Cursor-based pagination is added to endpoints as needed — check the specific endpoint for `cursor` / `nextCursor` fields.

## Errors

All non-2xx responses have a JSON body:

```json
{
  "error": "MarginError",
  "code": "INSUFFICIENT_MARGIN",
  "message": "Insufficient initial margin",
  "details": { "requiredIm": "100.00", "availableIm": "80.00" }
}
```

* `error` — the error family.
* `code` — a stable machine-readable code. Match on this in client logic.
* `message` — human-readable description.
* `details` — optional context (may be omitted).

See [Error Codes](file:///7302513/reference/error-codes.md) for the full list.

## Common HTTP status codes

| Status | Meaning                                                                |
| ------ | ---------------------------------------------------------------------- |
| 200    | Success                                                                |
| 400    | Malformed request (schema error, missing field)                        |
| 401    | Missing / invalid / expired credential                                 |
| 403    | Scope insufficient or IP not allowed                                   |
| 404    | Resource not found                                                     |
| 409    | Conflict (duplicate client order ID, market halted, etc.)              |
| 422    | Business-rule rejection (insufficient margin, post-only crosses, etc.) |
| 429    | Rate limited                                                           |
| 500    | Server error                                                           |
| 503    | Upstream degraded                                                      |

## Rate limits

Order-path endpoints are rate-limited per user. See [Rate Limits](file:///7302513/reference/rate-limits.md). Public read endpoints (market data, orderbook, OHLC) are not rate-limited.

## CORS

The API supports CORS for all `https://*.ocx.global` origins. Additional origins can be whitelisted for specific partner integrations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ocx.gitbook.io/ocx-doc/ocx/api/conventions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.