GuidesAPI Reference
DocumentationLog In

Overview

The websocket feed is publicly available and provides real-time market data updates for orders and trades.

๐Ÿ“˜

Endpoint: wss://ws-feed.exchange.coinbase.com

Rate Limits

Real-time market data updates provide the fastest insight into order flow and trades. This means that you are responsible for reading the message stream and using the message relevant for your needsโ€”this can include building real-time order books or tracking real-time trades.

Specs

Websocket connections are rate-limited at 8 requests every second per IP and up to 20 requests for bursts. Messages sent by the client on each connection are rate-limited to 100 every second per IP.

Errors

An error message displays when the client is actively disconnected for any of these reasons:

  • The client has too many backed up messages (ErrSlowConsume).
  • The client is sending too many messages (ErrSlowRead).
  • The message size is too large (Message too big)
  • There are intermittent network issues.

Protocol

The websocket feed uses a bidirectional protocol that encodes all messages as JSON objects. All messages have a type attribute that can be used to handle the message appropriately.

๐Ÿ‘

New message types can be added at any time. Clients are expected to ignore messages they do not support.

Error messages:
Most failure cases trigger an error messageโ€”specifically, a message with the type "error". This can be helpful when implementing a client or debugging issues.

{
    "type": "error",
    "message": "error message",
    /* ... */
}

Subscribe

To begin receiving feed messages, you must send a subscribe message to the server indicating which channels and products to receive. This message is mandatoryโ€”you are disconnected if no subscribe has been received within 5 seconds.

๐Ÿšง

To receive feed messages, you must send a subscribe message or you are disconnected in 5 seconds.

// Request
// Subscribe to ETH-USD and ETH-EUR with the level2, heartbeat and ticker channels,
// plus receive the ticker entries for ETH-BTC and ETH-USD
{
    "type": "subscribe",
    "product_ids": [
        "ETH-USD",
        "ETH-EUR"
    ],
    "channels": [
        "level2",
        "heartbeat",
        {
            "name": "ticker",
            "product_ids": [
                "ETH-BTC",
                "ETH-USD"
            ]
        }
    ]
}

Unsubscribe

To unsubscribe from channel/product pairs, send an unsubscribe message. The structure is equivalent to subscribe messages.

๐Ÿ‘

You can also unsubscribe from a channel entirely by providing no product IDs.

// Request
{
    "type": "unsubscribe",
    "channels": [
        "heartbeat"
    ]
}

You receive a subscriptions message as a response to an unsubscribe message.

Specifying Product IDs

There are two ways to specify the product IDs to listen for within each channel:

  • You can define product IDs for an individual channel.
  • You can define product IDs at the root of the objectโ€”this adds them to all the channels you subscribe to.
// Request
{
    "type": "unsubscribe",
    "product_ids": [
        "ETH-USD",
        "ETH-EUR"
    ],
    "channels": [
        "ticker"
    ]
}

Once a subscribe message is received, the server responds with a subscriptions message that lists all channels you are subscribed to. Subsequent subscribe messages add to the list of subscriptions. If you already subscribed to a channel without being authenticated, you will remain in the unauthenticated channel.

// Response
{
    "type": "subscriptions",
    "channels": [
        {
            "name": "level2",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR"
            ],
        },
        {
            "name": "heartbeat",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR"
            ],
        },
        {
            "name": "ticker",
            "product_ids": [
                "ETH-USD",
                "ETH-EUR",
                "ETH-BTC"
            ]
        }
    ]
}

Authentication

You can authenticate yourself when subscribing to the WebSocket Feed. The benefits of authenticating are:

  • Messages (in which you are of the parties) are expanded and have more useful fields.
  • You receive private messages, such as lifecycle information about stop orders you placed.
// Authenticated feed messages add user_id and
// profile_id for messages related to your user
{
    "type": "open", // "received" | "open" | "done" | "match" | "change" | "activate"
    "user_id": "5844eceecf7e803e259d0365",
    "profile_id": "765d1549-9660-4be2-97d4-fa2d65fa3352",
    /* ... */
}

Here's an example of an authenticated subscribe request:

// Request
{
    "type": "subscribe",
    "product_ids": [
        "BTC-USD"
    ],
    "channels": [
        "full"
    ],
    "signature": "...",
    "key": "...",
    "passphrase": "...",
    "timestamp": "..."
}

To authenticate, send a subscribe message as usual, and pass in fields to GET /users/self/verify, just as if you were signing a request. To get the necessary parameters, go through the same process as you would to make authenticated calls to the API.

๐Ÿšง

Authenticated feed messages do not increment the sequence number, which means that it is currently not possible to detect if an authenticated feed message was dropped.

Websocket Compression Extension

Websocket compression, defined in RFC7692, compresses the payload of websocket messages which can increase total throughput and potentially reduce message delivery latency. The permessage-deflate extension can be enabled by adding the extension header. Currently, it is not possible to specify the compression level.

From RFC7692:

The simplest "Sec-WebSocket-Extensions" header in a client (or server's) opening handshake to offer (or accept) use of the "permessage-deflate" extension looks like this:

    GET wss://ws-feed.exchange.coinbase.com
       Sec-WebSocket-Extensions: permessage-deflate

Sequence Numbers

Most feed messages contain a sequence number. Sequence numbers are increasing integer values for each product, with each new message being exactly one sequence number greater than the one before it.

Sequence numbers that are greater than one integer value from the previous number indicate that a message has been dropped. Sequence numbers that are less than the previous number can be ignored or represent a message that has arrived out of order.

In either situation you may need to perform logic to make sure your system is in the correct state.

๐Ÿšง

Even though a websocket connection is over TCP, the websocket servers receive market data in a manner that can result in dropped messages. Your feed consumer should be designed to handle sequence gaps and out of order messages, or should use channels that guarantee delivery of messages.

๐Ÿ‘

To guarantee that messages are delivered and your order book is in sync, consider using the level2 channel.