Stream subscriptions
Listen Key Mechanism
Description
The listen_key
is a unique token required for user authentication and to establish a WebSocket connection. It binds a user to a WebSocket session, ensuring that only authenticated users can access the private streams.
Acquiring a Listen Key
Users must first authenticate with the server to receive a
listen_key
This key is then used in the WebSocket connection headers to validate the user's session
Listen Key Expirations
Listen keys have a limited lifetime of 60 minutes
Users can prolong the key's lifetime
The server monitors the listen's key expirations and will automatically close the WebSocket connection when they expire
WebSocket Connection Query parameters documentation
listen_key parameter
The listen_key
parameter is crucial for accessing the WebSocket server. It carries the listen_key
token that is unique to each user session.
Obtaining the listen_key
:
listen_key
:The
listen_key
can be obtained via aGET
request to thelisten_key
endpoint provided by the server after user authentication.Once acquired, the
listen_key
must be included in the query parameter for the WebSocket handshake.
Signer parameter
The signer
parameter identifies the main account associated with the WebSocket connection. This query parameter is used along with the listen_key
to establish a secure and authenticated connection.
Usage:
Key:
Signer
Value: Address of the signer of trading account.
WebSocket Server Streams Documentation
1. Fills Stream (fills_
prefix)
fills_
prefix)Description
This is a private stream that provides real-time information about order fills.
Requires authentication and authorization to access specific trading accounts.
Connection Request
To subscribe to the Fills Stream:
Action: "subscribe"
Stream: "fills_{trading_account_address}"
Replace
{trading_account_address}
with the specific trading account you want to subscribe to.
ID: A unique request identifier.
{
"action": "subscribe",
"stream": "fills_{trading_account_address}",
"id": "unique_request_id"
}
Example subscription request:
{
"action": "subscribe", "stream": "fills_0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f",
"base": "ETH", "quote": "USDC", "ecosystem_book": true,
"id": "5"
}
Example subscription response (same response structure as for HTTP requests
{ "result": "OK", "id": "5"}
Example Stream Events
Order flow:
submit -> if succ response -> put into processing queue ->:
failed to process -> NOT_PROCCESSED (matcher result = FAILED_VALIDATION)
processed -> ACK -> OPEN -> ...
Partially filled
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "OK", // matching engine result
"fill_price": "2716.2819", // avg fill price
"fill_base_qty": "0.0007704", // fill qty in base
"fill_quote_qty": "2.092623", // fill qty in quote
"acc_base_qty": "0.0013676", // accumulated so far
"acc_quote_qty": "3.714786", // accumulated so far
"hash": "0x05fabffcde5a985b39a304803a501fe9d835e5762666592c2442e767fbc91798", // hash of the associated order
"is_sell_side": false,
"status": "PARTIALLY_FILLED"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
Fully filled
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "OK",
"fill_price": "2802.823411",
"fill_base_qty": "0.0011943",
"fill_quote_qty": "3.347412",
"acc_base_qty": "0.0011943",
"acc_quote_qty": "3.347412",
"hash": "0x054706cf2b72d614c864d6cad4a9a2634fae9901fd714bc71a0046a4afa8ea68",
"is_sell_side": false,
"status": "FILLED"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
Failed validation
example#1
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "FAILED_VALIDATION", <--- error description
"fill_price": "0",
"fill_base_qty": "0",
"fill_quote_qty": "0",
"acc_base_qty": "0",
"acc_quote_qty": "0",
"hash": "0x02e8e9fc7a892f225aa80d4e23f988da60daf35efe06886396a5ba70e610ede2",
"is_sell_side": false,
"status": "NOT_PROCESSED", <--- order status
"error_code_orderbook": "FAILED_SIGN_CHECK" <--- new field
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
example#2
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "FAILED_VALIDATION",
"fill_price": "0",
"fill_base_qty": "0",
"fill_quote_qty": "0",
"acc_base_qty": "0",
"acc_quote_qty": "0",
"hash": "0x006bfc44272f61d09c54ddec5d648d114262b5520b5825c4be5d517afa7ba788",
"is_sell_side": true,
"status": "NOT_PROCESSED",
"error_code_orderbook": "NOT_ENOUGH_BALANCE"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDT"
}
}
Cancelled
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "OK",
"fill_price": "0",
"fill_base_qty": "0",
"fill_quote_qty": "0",
"acc_base_qty": "0",
"acc_quote_qty": "0",
"hash": "0x07cec852aa9cfb6ed7007f793088e6a3c92f400e6299acf78060f916cfc95c67",
"is_sell_side": true,
"status": "CANCELLED"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
Failed to cancel
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"report_type": "CANCEL_ORDER",
"req_hash": "0x0576635fb70c1d49bd11778c9c6d74fa7c0075667ca0f8b673e7199d5c105ce6", // hash of the request
"entity_hash": "0x043b508c740f9912df5f5bab044087b79ce9e6f3ada48c2f2a3edd8496df50ca", // order hash intented to be cancelled
"error_code_orderbook": "NO_ORDERS_WITH_THIS_ID"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580"
}
Matching engine unable to match remaining amount
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"matcher_result": "SLIPPAGE",
"fill_price": "0",
"fill_base_qty": "0",
"fill_quote_qty": "0",
"acc_base_qty": "0",
"acc_quote_qty": "0",
"hash": "0x01d19066b73825550e387d6532736ceca2847193fe40ab2640a266d8751e6bb8",
"is_sell_side": true,
"status": "ACC"
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
Examples of special events:
Cancel all order under specified ticker
{
"result": {
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"cancel_ticker_hash": "0x01d19066b73825550e387d6532736ceca2847193fe40ab2640a266d8751e6bb8", // hash of cancel all request
},
"stream": "fills",
"client": "0x033e29bc9b537bae4e370559331e2bf35b434b566f41a64601b37f410f46a580",
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
FAILED_ROLLUP:
{
"result": {
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f",
"fill_price": 2000, // fill price
"fill_base_qty": 2, // fill qty in base asset that was failed
"fill_quote_qty": 4000, // fill qty in quote asset that was failed
"hash": "0x05fabffcde5a985b39a304803a501fe9d835e5762666592c2442e767fbc91798",
"is_sell_side": false,
"status": "FAILED_ROLLUP", // trade was failed due to some exceptional situation eg router taker
},
"stream": "fills",
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f"
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
REIMBURSE:
{
"result": {
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f",
"price": 0
"fill_base_qty": "0.35", // reimburse amount in main gas token
"hash": "0x05fabffcde5a985b39a304803a501fe9d835e5762666592c2442e767fbc91798",
"is_sell_side": false,
"status": "REIMBURSE", // router trade was failed, so we incentivize market makers
},
"stream": "fills",
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f"
"pair": {
"base": "STRK", // always strk/strk
"quote": "STRK"
}
}
EXPIRED:
{
"result": {
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f",
"fill_price": 1958, // fill price
"pair": "ETH-USDC", #
"fill_base_qty": 2, // expired amount
"fill_quote_qty": 3916, // expired amount
"hash": "0x05fabffcde5a985b39a304803a501fe9d835e5762666592c2442e767fbc91798",
"is_sell_side": false,
"status": "OK",
},
"stream": "fills",
"client": "0x541cf2823e5d004e9a5278ef8b691b97382fd0c9a6b833a56131e12232a7f0f"
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
2. Best Bid and Offer (BBO) Stream (bbo
)
bbo
)Description
Provides real-time best bid and offer updates for a specified trading pair.
Connection Request
To subscribe to the BBO Stream:
Action: "subscribe"
Stream: "bbo"
Base: The base token of the trading pair.
Quote: The quote token of the trading pair.
Ecosystem_book: Boolean indicating whether to use Ecosystem Book updates.
ID: A unique request identifier.
{
"action": "subscribe",
"stream": "bbo",
"base": "base_token",
"quote": "quote_token",
"ecosystem_book": true,
"id": "unique_request_id"
}
Example subscription request:
{
"action": "subscribe", "stream": "bbo",
"base": "ETH", "quote": "USDC", "ecosystem_book": true,
"id": "5"
}
Example subscription response (same response structure as for HTTP requests)
{ "result": "OK", "id": "5"}
Example Stream Event:
{
"result": {
"bid": ["1958", "124.23", 2], // price and volume and num orders
"ask": ["195", "87.11", 25],
"time": 1705221916000 # epoch in millis
},
"stream": "bbo",
"millis": 0,
"ecosystem": true,
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
3. Trade Stream (trade
)
trade
)Description
Real-time stream of trade data for a specified trading pair.
Connection Request
To subscribe to the Trade Stream:
Use the same format as the BBO stream but with Stream: "trade".
{
"action": "subscribe",
"stream": "trade",
"base": "base_token",
"quote": "quote_token",
"ecosystem_book": true,
"id": "unique_request_id"
}
Example subscription Request:
{
"action": "subscribe", "stream": "trade",
"base": "ETH", "quote": "USDC", "ecosystem_book": true,
"id": "5"
}
Example subscription Response (same response structure as for HTTP requests)
{ "result": "OK", "id": "5"}
Example Stream Output
{
"result": {
"price 1958, "base_qty": "2", "quote_qty":"3916", "is_sell_side": true,
"time": 1705221916000 # epoch in millis
},
"stream": "trade",
"millis": 0,
"ecosystem": true,
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
4. Snapshot Stream (snap
)
snap
)Description
Provides snapshots of trading data (specific details not provided in the code).
Connection Request
To subscribe to the Snapshot Stream:
Use the same format as the BBO stream but with Stream: "snap".
{
"action": "subscribe",
"stream": "snap",
"base": "base_token",
"quote": "quote_token",
"ecosystem_book": true,
"id": "unique_request_id"
}
Example Stream Output
{
"result": {
"bids": ["1958", "0", 0], # 0 means the level was removed
"asks": [
["1958", "4300", 2], # non zero means new volume on price level
...
],
"msg_id": "3", // user can use this msg id to apply incremental update to snapshot that they query from rest
"time": 1705221916000
},
"stream": "snap",
"millis": 0,
"ecosystem": true,
"pair": {
"base": "AETH",
"quote": "AUSDC"
}
}
Unsubscribe from a Stream
To unsubscribe from any stream:
Action: "unsubscribe"
Stream: Specify the stream you want to unsubscribe from.
ID: A unique request identifier.
{
"action": "unsubscribe",
"stream": "specified_stream",
"id": "unique_request_id"
}
Example Stream Output
{
"result": "OK",
"id": 0
}
Last updated