# Stream Reference

Our WebSocket API provides multiple data streams for various exchange data:

* L2 Order Book Data
* Trade Events
* Per Account Order Events

## Book Ticker

| Schema | Frequency | Description |
|----|----|----|
| `{symbol}@bookTicker` | Real-time | Real time updates to the best bid/ask price for an order book. |

<StreamTester streamName="btcusd@bookTicker" />

```json
{
  "u": 1751505576085,
  "E": 1751508438600117161,
  "s": "btcusd",
  "b": "45000.50",
  "B": "1.25000000",
  "a": "45001.00",
  "A": "0.75000000"
}
```

| Field | Type   | Description              |
|-------|--------|--------------------------|
| `u`   | number | Update ID                |
| `E`   | number | Event time (nanoseconds) |
| `s`   | string | Symbol                   |
| `b`   | string | Best bid price           |
| `B`   | string | Best bid quantity        |
| `a`   | string | Best ask price           |
| `A`   | string | Best ask quantity        |

---

## L2 Partial Depth Streams

| Schema | Frequency | Description |
|----|----|----|
| `{symbol}@depth5` | Periodic (1s) | Periodic snapshot of the top 5 levels once per second |
| `{symbol}@depth10` | Periodic (1s) | Top 10 levels |
| `{symbol}@depth20` | Periodic (1s) | Top 20 levels |
| `{symbol}@depth5@100ms` | Periodic (100ms) | Top 5 levels every 100 milliseconds |
| `{symbol}@depth10@100ms` | Periodic (100ms) | Top 10 levels |
| `{symbol}@depth20@100ms` | Periodic (100ms) | Top 20 levels |

<StreamTester streamName="btcusd@depth10@100ms" />

```json
{
  "lastUpdateId": 12345678,
  "bids": [
    ["45000.50", "1.25000000"],
    ["45000.25", "0.50000000"]
  ],
  "asks": [
    ["45001.00", "0.75000000"],
    ["45001.25", "2.00000000"]
  ]
}
```

| Field          | Type     | Description                  |
|----------------|----------|------------------------------|
| `lastUpdateId` | number   | Last update ID               |
| `bids`         | array    | Array of [price, quantity]   |
| `asks`         | array    | Array of [price, quantity]   |

---

## L2 Differential Depth Streams

| Schema | Frequency | Description |
|----|----|----|
| `{symbol}@depth` | Periodic (1s) | List of all changed price levels in the last second |
| `{symbol}@depth@100ms` | Periodic (100ms) | In the last 100 milliseconds |

<StreamTester streamName="btcusd@depth@100ms" />

:::tip[Initial Snapshot]
Use the [`snapshot` connection parameter](/websocket/introduction#snapshot-parameter) to receive an initial orderbook snapshot when subscribing. Connect with `wss://ws.gemini.com?snapshot=-1` for a full snapshot, or specify a positive number for top N levels.
:::

:::note
Quantity zero indicates price level removal.
:::

```json
{
  "e": "depthUpdate",
  "E": 1751508260659505382,
  "s": "btcusd",
  "U": 12345677,
  "u": 12345678,
  "b": [
    ["45000.50", "1.25000000"],
    ["45000.25", "0.00000000"]
  ],
  "a": [
    ["45001.00", "0.75000000"]
  ]
}
```

| Field | Type   | Description                        |
|-------|--------|------------------------------------|
| `e`   | string | Event type ("depthUpdate")         |
| `E`   | number | Event time (nanoseconds)           |
| `s`   | string | Symbol                             |
| `U`   | number | First update ID in this event      |
| `u`   | number | Last update ID in this event       |
| `b`   | array  | Bid updates [price, quantity]      |
| `a`   | array  | Ask updates [price, quantity]      |

---

## Trade Stream

| Schema | Frequency | Description |
|----|----|----|
| `{symbol}@trade` | Real-time | Real time trade executions |

<StreamTester streamName="btcusd@trade" />

```json
{
  "E": 1759873803503023900,
  "s": "btcusd",
  "t": 2840140956529623,
  "p": "120649.97000",
  "q": "0.0046190900",
  "m": true
}
```

| Field | Type    | Description             |
|-------|---------|-------------------------|
| `E`   | number  | Event time (nanoseconds) |
| `s`   | string  | Symbol                  |
| `t`   | number  | Trade ID                |
| `p`   | string  | Price                   |
| `q`   | string  | Quantity                |
| `m`   | boolean | Is buyer the maker      |

---

## Order Events

:::warning
Requires an authenticated session
:::

| Schema | Frequency | Description |
|----|----|----|
| `orders@account` | Real-time | Real time order activity for the account associated with the authenticated API key |
| `orders@session` | Real-time | Real time order activity for the authenticated API key |

```json
# Order Event - New
{
  "E":1759291847686856569,
  "s":"BTCUSD",
  "i":73797746498585286,
  "c":"my-order-1759291847503",
  "S":"BUY",
  "o":"LIMIT",
  "X":"NEW",
  "p":"1.00000",
  "q":"0.0000100000",
  "z":"0.0000100000",
  "T":1759291847686856569
}

# Order Event - Canceled
{
  "E":1759291847731455006,
  "s":"BTCUSD",
  "i":73797746498585286,
  "c":"my-order-1759291847503",
  "X":"CANCELED",
  "T":1759291847731455006
}
```

| Field | Type    | Description             |
|-------|---------|-------------------------|
| `E`   | number  | Event time (nanoseconds) |
| `s`   | string  | Symbol              |
| `i`   | number  | Order ID              |
| `c`   | string  | Client Order ID              |
| `S`   | string  | Side, `BUY / SELL`              |
| `o`   | string  | Type, `LIMIT / MARKET`              |
| `X`   | string  | Status, `NEW / OPEN / FILLED / PARTIALLY_FILLED / CANCELED / REJECTED / MODIFIED`              |
| `p`   | string  | Order price              |
| `P`   | string  | Stop price              |
| `q`   | string  | Original quantity              |
| `z`   | string  | Remaining quantity              |
| `Z`   | string  | Executed quantity. For `FILLED` / `PARTIALLY_FILLED` events, this is the quantity filled in the last execution. For `CANCELED` and other events, this is the cumulative quantity filled over the lifetime of the order. |
| `L`   | string  | Last execution price              |
| `t`   | number  | Trade ID              |
| `n`   | string  | Fee amount (only present in 'FILLED' events)              |
| `r`   | string  | Rejection reason              |
| `T`   | number  | Update time (nanoseconds) |
| `O`   | string  | Event outcome for event contracts, `YES / NO` |

:::note
Fields with empty or zero values may be omitted from the event.
:::

#### Rejection Reasons

When an order is `REJECTED`, the `r` field contains one of:

| Reason | Description |
|--------|-------------|
| `MarketNotOpen` | Market is closed or paused |
| `InsufficientFunds` | Account lacks sufficient balance |
| `InvalidPrice` | Price violates constraints |
| `LimitPriceOffTick` | Price does not align with tick size |
| `InvalidQuantity` | Quantity below minimum or off increment |
| `InvalidStopPrice` | Stop price violates constraints |
| `InvalidTotalSpend` | Total spend calculation error |
| `DuplicateOrder` | Duplicate client order ID |
| `InsufficientLiquidity` | Not enough liquidity at price |
| `UnknownInstrument` | Trading pair does not exist |

#### Cancellation Reasons

When an order is `CANCELED` by the system, the `r` field contains one of:

| Reason | Description |
|--------|-------------|
| `SelfCrossPrevented` | Self-trade prevention triggered |
| `FillOrKillWouldNotFill` | FOK order could not fill completely |
| `ImmediateOrCancelWouldPost` | IOC order would post to book |
| `MakerOrCancelWouldTake` | MOC order would take liquidity |
| `AuctionCancelled` | Auction-related cancellation |
| `ExceedsPriceLimits` | Price moved beyond limits |

---

## Balance Updates

:::warning
Requires an authenticated session
:::

| Schema | Frequency | Description |
|----|----|----|
| `balances@account` | Real-time | Real time balance updates for the account associated with the authenticated API key |
| `balances@account@1s` | Periodic (1s) | Periodic snapshot of all balances every second for the account associated with the authenticated API key |

The `balances@account` stream pushes updates in real time whenever a balance change occurs, and only includes the assets that changed. The `balances@account@1s` stream sends a complete snapshot of all account balances every second, regardless of whether they changed. On subscribe, `balances@account@1s` will immediately send the current balances if available.

```json
# Balance Update
{
  "e": "balanceUpdate",
  "E": 1768250434780,
  "u": 1768250421600,
  "B": [
    {
      "a": "USD",
      "f": "207.39",
      "c": "207.39"
    }
  ]
}
```

| Field | Type    | Description             |
|-------|---------|-------------------------|
| `e`   | string | Event type ("balanceUpdate")         |
| `E`   | number | Event time (nanoseconds)              |
| `u`   | number | Time of the last account update (nanoseconds) |
| `B`   | array  | Balance updates              |
| `a`   | string | Asset code              |
| `f`   | string | Available balance (amount available to trade)              |
| `c`   | string | Confirmed balance (total balance including pending)              |

---

## Contract Status

Prediction-market contract lifecycle events — status transitions (e.g. `Awaiting Approval` → `Approved` → `Active`) and strike-populated moments for Up/Down contracts.

| Schema | Frequency | Description |
|----|----|----|
| `contractStatus` | Real-time | Status changes and strike-price updates for prediction-market contracts |

```json
# Strike-based contract (e.g. HI78999D63)
{
  "e": "contractStatus",
  "E": 1776871540195,
  "s": "gemi-btc15m2604221545-hi78999d63",
  "k": "btc15m2604221545",
  "c": "HI78999D63",
  "i": 134794,
  "p": "78999.63",
  "o": "Awaiting Approval",
  "n": "Approved"
}

# Up/Down contract (no numeric strike — `p` omitted until populated)
{
  "e": "contractStatus",
  "E": 1776871295498,
  "s": "gemi-btc05m2604221630-up",
  "k": "btc05m2604221630",
  "c": "UP",
  "i": 134791,
  "o": "Awaiting Approval",
  "n": "Approved"
}
```

| Field | Type   | Description |
|-------|--------|-------------|
| `e`   | string | Event type (`contractStatus`) |
| `E`   | number | Event time (Unix milliseconds) |
| `s`   | string | Instrument symbol |
| `k`   | string | Event ticker |
| `c`   | string | Contract ticker (e.g. `HI78999D63`, `UP`, `DOWN`) |
| `i`   | number | Contract ID |
| `p`   | string | Strike price parsed from the contract ticker. Omitted for Up/Down contracts until the strike is set at activation |
| `o`   | string | Previous status |
| `n`   | string | New status |

:::note
For Up/Down contracts, `p` is omitted while the strike is unknown and included once it is set — subscribers can detect strike availability by the field's presence.
:::