WebSockets API

The WebSockets API provides data feeds providing the trader real-time information.

See the guide for examples on how to use the WebSockets API.

Common schemas

Interactions with the WebSockets endpoint is done using common base JSON schemas for all channels/feed types. For specific feeds, see the following subsections.

Subscribe

Use the following schema to subscribe to a channel.

JSON Schema

{ 
    "type": "subscribe", 
    "channel": "v4_trades",
    "id": "BTC-USD",
    "batched": false
}

Response

Unsubscribe

Use the following schema to unsubscribe from a channel. Similar scheme to the subscribe schema, however with the unsubscribe type, and without the batched field.

JSON Schema

{
    "type": "unsubscribe",
    "channel": "v4_trades",
    "id": "BTC-USD"
}

Response

Data

After subscription, the incoming messages will be serialized using the following schema.

JSON Schema

Channels

The available clients API is presented below. For each, the subscription and unsubscription functions are shown. Internally, these functions send messages serialized in the subscribe and unsubscribe JSON schemas above.

For each channel/feed type the sub-schemas employed in the contents field of the received Data (after subscription) are shown.

Subaccounts

Data feed of a subaccount. Data contains updates to the subaccount such as position, orders and fills updates.

Method Declaration

# class `Subaccounts`
def subscribe(self, address: str, subaccount_number: int) -> Self
def unsubscribe(self, address: str, subaccount_number: int)

Schema

The field id is a string containing the subaccount ID (address and subaccount number). It is formattted as {address}/{subaccount-number}.

The field contents is serialized using the following schemas.

Messages

Markets

Data feed of all dYdX markets. Data contains updates to all markets, including market parameters and oracle prices.

Method Declaration

# class `Markets`
def subscribe(self, batched: bool = True) -> Self
def unsubscribe(self)

Schema

The field id is not employed in the subscribe/unsubscribe schemas.

The field contents is serialized using the following schemas.

Messages

Trades

Data feed of the trades on a market. Data contains order fills updates, such as the order side, price and size.

Method Declaration

# class `Trades`
def subscribe(self, market: str, batched: bool = True) -> Self
def unsubscribe(self, market: str)

Schema

The field id is the market/ticker as a string.

The field contents is serialized using the following schemas.

Messages

Orders

Data feed of the orders of a market. Data contains lists of the bids and asks of the order book.

Method Declaration

# class `OrderBook`
def subscribe(self, market: str, batched: bool = True) -> Self
def unsubscribe(self, market: str)

Schema

The field id is the market/ticker as a string.

The field contents is serialized using the following schemas.

Messages

Candles

Data feed of the candles of a market. Data contains updates for open, low, high, and close prices, trade volume, for a certain time resolution.

Method Declaration

# class `Candles`
def subscribe(self, id: str, resolution: CandlesResolution, batched: bool = True) -> Self
def unsubscribe(self, id: str, resolution: CandlesResolution)

Schema

The field id is a string containing the market and candle resolution. It is formatted as {market}/{resolution}.

The field contents is serialized using the following schemas.

Messages

Parent Subaccounts

Data feed of a parent subaccount. This channel returns similar data to the subaccount channel.

A parent subaccount is a subaccount numbered between 0 and 127. Used for isolated position management by the dYdX frontend (web).

Method Declaration

# Coming soon.

Schema

The field id is a string containing the subaccount ID (address and subaccount number). It is formattted as {address}/{subaccount-number}.

The field contents is serialized using the following schemas.

Messages

Block Height

Data feed of current block height. Data contains the last block height and time.

Method Declaration

Schema

The field id is not employed in the subscribe/unsubscribe schemas.

The field contents is serialized using the following schemas.

Messages