> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coinbase Derivatives: Predictions WebSocket Overview

The Coinbase Derivatives: Predictions WebSocket Market Data API streams tickers, public trades, order books, and instrument and event changes as JSON over a single WebSocket connection.

* [Authentication](/derivatives-predictions/websocket/authentication): Credentials, signature, and authorization on the first command.
* [Commands](/derivatives-predictions/websocket/commands): Subscribe, unsubscribe, list subscriptions, and update subscription.
* [Channels](/derivatives-predictions/websocket/channels): Ticker, trade, orderbook, instrument lifecycle, and event lifecycle.

## Connection

| Property | Value |
| :- | :- |
| Endpoint | `wss://` host listed on the [Coinbase Derivatives: Predictions Connectivity](/derivatives-predictions/connectivity) page, path `/ws/v1`. |
| Message format | JSON text frames. Each frame you send contains one command object. |
| Authentication | Credentials on the first command. See [Authentication](/derivatives-predictions/websocket/authentication). |
| Permission | `MARKET_DATA` |

Authentication lasts for the life of the connection. If the connection drops, reconnect, authenticate again, and resubscribe.

## Data frames

The ticker, trade, and orderbook channels send frames with this envelope:

| Field | Type | Description |
| :- | :- | :- |
| `type` | String | `ticker`, `trade`, `orderbook_snapshot`, or `orderbook_delta`. |
| `sid` | Integer | Subscription ID from the `subscribed` response. |
| `seq` | Integer | Sequence number per subscription. Starts at `1` and increases by `1` for each frame. |
| `msg` | Object | Payload. See each [channel](/derivatives-predictions/websocket/channels). |

Lifecycle frames carry `type`, `sid`, and `msg`, and do not carry `seq`.

* Key sets do not vary with the data. When a value is unknown, the key is present with JSON `null`.
* Prices are strings with 3 decimal places. Quantities are strings with 2 decimal places.
* Instrument and trade IDs are strings, to avoid precision loss in languages such as JavaScript.
* `msg.ticker` is always present and is `null` when the instrument has no ticker.

> [!NOTE]
>
> If your client cannot read frames fast enough, the server may drop frames. A dropped frame still consumes a `seq` value, so a gap in `seq` means you missed data. To recover, unsubscribe and subscribe again. If your client falls too far behind, the server may close the connection.

## Example session

You send an authenticated subscribe for one ticker. The credential keys are described in [Authentication](/derivatives-predictions/websocket/authentication#authentication).

```json theme={null}
{
  "id": 1,
  "cmd": "subscribe",
  "key": "fixed-api-key",
  "passphrase": "fixed-passphrase",
  "signature": "xGbr3oY2MKYu/HoFjzTX1i2jhltEx/jGFd//lF+49pw=",
  "time": "1717171717",
  "params": {
    "channels": ["ticker"],
    "ticker": "NFL-GAMEWINNER-26NOV28LARSF-LAR"
  }
}
```

The server accepts the subscription:

```json theme={null}
{
  "id": 1,
  "type": "subscribed",
  "msg": {
    "channel": "ticker",
    "sid": 1
  }
}
```

The server streams ticker frames, starting at `seq` `1`:

```json theme={null}
{
  "type": "ticker",
  "sid": 1,
  "seq": 1,
  "msg": {
    "ticker": "NFL-GAMEWINNER-26NOV28LARSF-LAR",
    "id": "598471892347",
    "last_price": "0.534",
    "yes_bid_price": "0.532",
    "yes_ask_price": "0.537",
    "yes_bid_size": "302.00",
    "yes_ask_size": "151.00",
    "last_trade_size": "25.00",
    "open_interest": "1500.00",
    "total_volume": "4500.00",
    "ts_ms": 1795812345678
  }
}
```

You unsubscribe:

```json theme={null}
{
  "id": 2,
  "cmd": "unsubscribe",
  "params": {
    "sid": 1
  }
}
```

The server confirms. `seq` is `1` because one data frame was sent on the subscription:

```json theme={null}
{
  "id": 2,
  "sid": 1,
  "seq": 1,
  "type": "unsubscribed"
}
```

## Errors

Error frames use this envelope:

| Field | Type | Description |
| :- | :- | :- |
| `id` | Integer | Your request `id`. `null` when the command `id` could not be read. |
| `type` | String | `error` |
| `msg.code` | Integer | Error code. See the table below. |
| `msg.msg` | String | Human-readable reason. |

Example error frame, for a subscribe whose ticker matches no instrument:

```json theme={null}
{
  "id": 7,
  "type": "error",
  "msg": {
    "code": 5,
    "msg": "Unknown instrument: NFL-GAMEWINNER-26NOV28LARSF-XYZ"
  }
}
```

| Code | Name | Description |
| :- | :- | :- |
| `1` | `INVALID_JSON` | The command is not valid JSON. The server closes the connection. |
| `2` | `UNKNOWN_COMMAND` | The command or `action` is not supported, or the operation is not allowed on the channel or subscription. |
| `3` | `UNKNOWN_CHANNEL` | The requested channel is not supported. |
| `4` | `MISSING_FIELD` | A required key or subscription ID is missing or not valid for the operation. |
| `5` | `UNKNOWN_INSTRUMENT` | A valid instrument selector does not match an instrument. |
| `6` | `ALREADY_SUBSCRIBED` | The request overlaps a same-channel subscription, an all-instruments subscription conflicts with an explicit one, or an update is already pending. |
| `7` | `AUTHENTICATION_FAILED` | Authentication failed. The server closes the connection with close code `3000`. |
| `8` | `INVALID_FIELD` | An unknown key, a wrong JSON type, or a malformed or non-canonical instrument ID. |

| Condition | Close code | Close reason |
| :- | :- | :- |
| Authentication failure | `3000` | `Unauthorized User` |
| Invalid JSON | `1008` | `Invalid request` |

## Limits

| Limit | Value |
| :- | :- |
| Commands queued while authenticating | At most 16 commands and 16 KB of command data. Exceeding either limit fails authentication. |
| Authentication timeout | Authentication must complete within 5 seconds of the first command, or it fails. |
| Keepalive | When the server has received nothing from you for 10 seconds, it sends a WebSocket ping. Answer with a pong. |
| Idle timeout | The server closes a connection from which it has received nothing for 30 seconds. |
| Connections | At most 2,000 connections per gateway instance. |
| Connection attempts | At most 10 connection attempts per IP address per 30 seconds. |
| Channels per subscribe | 1 |
| Subscriptions per update | 1 |
| Orderbook depth | 10 price levels per side. |