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: Credentials, signature, and authorization on the first command.
Commands: Subscribe, unsubscribe, list subscriptions, and update subscription.
Channels: Ticker, trade, orderbook, instrument lifecycle, and event lifecycle.

Connection

Property	Value
Endpoint	`wss://` host listed on the Coinbase 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.
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.

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.

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.

{
  "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:

{
  "id": 1,
  "type": "subscribed",
  "msg": {
    "channel": "ticker",
    "sid": 1
  }
}

The server streams ticker frames, starting at seq 1:

{
  "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:

{
  "id": 2,
  "cmd": "unsubscribe",
  "params": {
    "sid": 1
  }
}

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

{
  "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:

{
  "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.

REST API Overview

REST Endpoints

FIX

WebSocket

Connection

Data frames

Example session

Errors

Limits

​Connection

​Data frames

​Example session

​Errors

​Limits

Connection

Data frames

Example session

Errors

Limits