> ## 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.

# Binary options API

> Market data, orders and your positions for the 15-minute Up/Down contracts

The binary options endpoints are served at `https://api.ocx.global/binary/*` (also `https://auth.ocx.global/binary/*`). **Public** endpoints need no credentials; **Session** endpoints use the same signed-in session as the rest of the API (cookie or `Authorization: Bearer`); see [Authentication](https://docs.ocx.global/get-started/authentication.md). Read [Binary options](https://docs.ocx.global/binary/overview.md) first for the contract rules.

> [!NOTE]
>
> Prices are whole **cents per share, 1–99**. Market data is quoted in **Up** cents: a Down price is `100 − Up price`. Quantities are whole shares. A window's id (`marketId`) looks like `SPX-15M-20261029-0930`: series, then the window's UTC start.

## Market data

Public.

### Board

`GET /binary/board?underlying=SPX` — one underlying's windows and its live reference. `underlying` is `SPX` (OCX500) or `NDX` (OCXTECH).

```json Response theme={null}
{ "underlying": "SPX", "name": "OCX500", "windowSec": 900, "cutoffSec": 15,
  "ref": { "price": "7763.375", "at": "2026-10-29T09:32:29.000Z", "sessionOpen": true },
  "markets": [
    { "id": "SPX-15M-20261029-0930", "seriesId": "SPX-15M", "underlying": "SPX", "refMarketId": "SPX-USDC-2026-09-18",
      "startAt": "2026-10-29T09:30:00.000Z", "cutoffAt": "2026-10-29T09:44:45.000Z", "expiryAt": "2026-10-29T09:45:00.000Z",
      "status": "open", "strike": "7764.125", "settlePrice": null, "outcome": null,
      "bestBid": 47, "bestAsk": 52, "lastPrice": 50, "volumeCents": 125000, "openInterest": 2500 } ] }
```

`markets` holds up to 15 windows in start order: recent ones, the live one, and the next ones already listed.

**ref** `object`

The live reference: `price`, the second it was sampled (`at`), and `sessionOpen` — `false` while the reference future is not trading, when no new windows are listed.

**markets\[]** `array`

**window**

**status** `string`

`listed` (not started; no orders) · `open` (trading until `cutoffAt`) · `closed` (cutoff passed, awaiting settlement) · `settled`.

**strike / settlePrice** `string | null`

The reference at the open and at the end. Null until fixed.

**outcome** `string | null`

`up` · `down` · `void`, once settled.

**bestBid / bestAsk / lastPrice** `number | null`

Top of the book and the last trade, in Up cents.

**volumeCents / openInterest** `number`

Traded value in cents; open interest in pairs (each pair is \$1.00 in escrow).

**refMarketId** `string`

The OCX future whose mid is the reference.

### Window, book and trades

`GET /binary/markets/{marketId}` → `{ market, book: { bids, asks }, trades }`. `book` levels are `{ price, size }` in Up cents, best first. `trades` are the last 50 prints, newest first: `{ price, quantity, takerSide, at }`, `takerSide` being `buy up`, `buy down`, `sell up` or `sell down`. An unknown id returns `404`.

### Reference series

`GET /binary/ref?underlying=SPX&from={epochMs}` → `{ points: [[epochMs, price], …] }`, one point a second from `from`, at most the last hour. Poll with `from` = the last point's time + 1 to extend a chart.

## Orders

Session. Limited to 300 order requests a minute per account.

### Place an order

`POST /binary/orders`

**marketId** `string` *required*

A window with `status: "open"`, before its cutoff.

**side** `string` *required*

`buy` | `sell`

**outcome** `string` *required*

`up` | `down`

**quantity** `number` *required*

Whole shares, 1 to 1,000,000.

**type** `string`

`limit` (default) | `market`

**price** `number`

Required for `limit`: cents, 1–99, **in the order's own outcome** (a Down limit is a Down price).

**slippage** `number`

Market orders: cents beyond the best price you accept, 0–20, default 2.

**clientOrderId** `string`

Idempotency key (up to 64 characters). A retry returns the original order; the same id with other terms is refused with `409`.

```bash cURL theme={null}
curl -s -X POST "https://api.ocx.global/binary/orders" \
  -H "Authorization: Bearer $OCX_TOKEN" -H "Content-Type: application/json" \
  -d '{ "marketId": "SPX-15M-20261029-0930", "side": "buy", "outcome": "up",
        "quantity": 20, "type": "limit", "price": 48 }'
```

```json Response theme={null}
{ "order": { "id": "…", "marketId": "SPX-15M-20261029-0930", "side": "buy", "outcome": "up", "price": 48,
             "quantity": 20, "filled": 20, "status": "filled", "createdAt": "2026-10-29T09:33:02.114Z" },
  "fills": [{ "price": 47, "quantity": 20 }],
  "walletBalance": "990.60" }
```

* A **buy** reserves `price × quantity` from your wallet when placed. Better fills return the difference at once.
* A **limit** order rests until it fills, you cancel it, or the cutoff.
* A **market** order fills against the book up to best ± `slippage` and cancels the rest; it is refused (`409`) when that side of the book is empty.
* A **sell** closes shares you hold and is refused (`400`) for more shares than you hold free.
* `fills` are in the order's outcome cents; `walletBalance` is your wallet after the order.

### Cancel

| Endpoint | Description |
| - | - |
| `POST /binary/orders/{id}/cancel` | Cancel one open order; its reserve or shares are released. Returns `{ order }`; `409` if it is no longer open. |
| `POST /binary/orders/cancel-all` | Body `{ "marketId"?: string }`: one window, or every window. Returns `{ cancelled }`. |

## Your account

`GET /binary/me` — Session.

```json Response theme={null}
{ "walletBalance": "990.60",
  "positions": [{ "marketId": "SPX-15M-20261029-0930", "underlying": "SPX", "startAt": "…", "expiryAt": "…", "status": "open",
                  "strike": "7764.125", "outcome": null, "up": 20, "down": 0, "upAvgCents": 47, "downAvgCents": null, "payoutCents": null }],
  "settled": [ … ], "openOrders": [ … ],
  "trades": [{ "marketId": "…", "side": "buy", "outcome": "up", "price": 47, "quantity": 20, "liquidity": "taker", "at": "…" }] }
```

`positions` are windows not yet settled; `settled` the last 50 settled windows with `payoutCents`. `openOrders` use the order shape above; `trades` are your last 50 fills, in each fill's outcome cents.

## Errors

The body is `{ "message" }`.

| Status | When |
| - | - |
| `400` | Invalid request; price or quantity out of range; not enough wallet balance; selling shares you do not hold; a buy that would leave an open loan uncovered. |
| `401` | No or invalid session. |
| `403` | A cookie request from another site. |
| `404` | Unknown window or underlying. |
| `409` | The window is not open (not started, or past its cutoff); no liquidity for a market order; order no longer open; `clientOrderId` reused with other terms. |
| `429` | More than 300 order requests a minute. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.