The Drip Protocol WebSocket API allows real-time communication with the Orion Aggregator to receive updates on various data related to spot and futures trading. This documentation provides an overview of the available WebSocket endpoints, message formats, subscriptions, and potential errors.
WebSocket Connection
To establish a WebSocket connection to the Orion Aggregator, use the following endpoint:
wss://dev.orionprotocol.io/v1
Upon successful connection, the Aggregator sends an initial message containing a connection ID for debugging purposes.
Keep in mind that the WebSocket connection has a lifetime limit of 24 hours. If the Aggregator detects that the connection has exceeded this lifetime, it will automatically close the connection and return an error message.
Keep Alive - Ping and Pong Messages
Ping-pong messages are used by the Aggregator to keep a WebSocket connection alive. The Aggregator sends ping messages to the client on a regular basis, anticipating a pong message in return.
To keep the connection alive, the client should send the identical pong message in response to each ping message. If you do not react within the chosen pong timeout period, the Aggregator will close the connection and display the error message "WS connection has reached pong timeout."
Subscriptions
Clients can use a single WebSocket connection to subscribe to various updates from the Orion Aggregator. The Aggregator provides the following types of updates:
Address State Updates (Spot and Futures)
Aggregated Order Book Updates
Swap Info Updates
Asset Pairs Config Updates
Each type of update has its own subscription format and subscription limits.
Message Types
There are two types of messages that can be sent or received using the WebSocket API:
Server Messages: Messages sent by the aggregator.
Client Messages: Messages sent by the client (you).
Both types of messages contain the required field "T" (message type):
{
"T": "i",
...
}
All the server messages contain an additional field "_" representing the aggregator's timestamp in milliseconds:
{
"T": "e",
"_": 1602847690892,
...
}
Server Messages
Initial Message
Sent by the aggregator after the connection is successfully established. This message contains the connection ID for debugging purposes.
{
"T": "i", // message type "i" - initial
"_": 1619082948988, // Aggregator's timestamp in ms
"i": "0007c3de-7216-4888-a0ca-10ce5a6fa612" // connection ID
}
Spot Address Updates
Represents updates of the spot address state, including balances and orders.
The "Address Updates" message can be sent without some fields:
If there are no changes in the spendable balance, the "b" field will be omitted.
If there are no changes in orders, the "o" field will be omitted.
Changes in orders can also have missing fields, as the aggregator avoids resending immutable fields if they have already been sent. Sub-orders have all their fields present.
Futures Address Updates
Represents updates of the futures address state, including balances and orders.
{
"T": "auf", // message type "auf" - address updates (futures)
"_": 1619082969008, // Aggregator's timestamp in ms
"S": "0x1FF516E5ce741085CFF86d37fc27747dF852a80a", // target address
"k": "i", // kind of message: "i" - initial message, "u" - updates
"id": "581faf3e-08b5-45ed-a0f0-0784f65e5e24", // request ID
"uc": ["o", "b"], // message contains orders and balances parts
"b": [
{
// Futures balances details (see below)
}
],
"o": [
{
// Futures order details (see below)
}
]
}
Order Details (Spot and Futures)
Orders details are included in the "o" array of the corresponding address update messages.
{
"I": "0x25ced1caa4fa8dbb19a1cb43edd728ca3c0be948d2fc7a0385f6404807116fd2", // id
"O": "0x1FF516E5ce741085CFF86d37fc27747dF852a80a", // sender (owner)
"P": "ETHUSDF", // instrument (asset pair)
"s": "buy", // side (buy/sell)
"a": "3.6", // amount
"A": "3.6", // settled amount
"p": "1443.2", // signed price
"L": "1440.0", // stop limit price
"E": "STOP_LIMIT", // execution type
"C": "≥ 16.0", // trigger condition
"F": "ORN", // fee asset
"f": "0.003", // fee
"l": false, // is liquidation order
"S": "SETTLED", // status
"T": 1613586846557, // creation time
"t": 1613586849558, // update time
"c": [ // sub orders (content)
{
// Sub order details (see below)
}
]
}
Sub Order Details
Sub order details are included in the "c" array of the corresponding order details.
The Aggregated Order Book Updates message provides real-time updates for the order book of a specific asset pair.
{
"T": "aobu", // message type "aobu" - aggregated order book updates
"_": 1619082969008, // Aggregator's timestamp in ms
"S": "ORN-USDT", // target asset pair
"ob": { // updates of order books in format: [price, amount, exchanges], price descending order for asks and bids. Exchanges exist only for ORION Aggregator's project mode
"a": [ // asks (sell orders)
["9.98", "143.67", ["BINANCE", "ORION_POOL"]],
["9.95", "487.16", ["BINANCE"]],
["9.92", "221.54", ["BINANCE", "KUCOIN"]]
],
"b": [ // bids (buy orders)
["9.87", "549.97", ["BINANCE"]],
["9.82", "466.54", ["BINANCE", "KUCION"]],
["9.80", "350.16", ["ORION_POOL", "KUCOIN"]]
]
}
}
Asset Pairs Config Updates (Deprecated)
This message is deprecated and used for representing updates to the asset pairs' configurations.
{
"T": "apcu", // message type "apcu" - asset pairs config updates
"_": 1619082969008, // Aggregator's timestamp in ms
"k": "u", // kind of message: "i" - initial message, "u" - updates
"id": "581faf3e-08b5-45ed-a0f0-0784f65e5e24", // request id
"u": [ // updates of asset pairs configs in format: [asset pair name, min amount, price precision]
[ "ETH-USDT", 0.01, 4 ],
[ "ORN-USDT", 1, 4 ]
]
}
Single Asset Pair Info Update
This message represents an update to the configuration of a single asset pair.
{
"T": "apiu", // message type "apiu" - asset pair info update
"_": 1619082969008, // Aggregator's timestamp in ms
"k": "u", // kind of message: "i" - initial message, "u" - updates
"id": "581faf3e-08b5-45ed-a0f0-0784f65e5e24", // request id
"u": ["ETH-USDT", 0.01, 4] // update of asset pair info in format: [asset pair name, min amount, price precision]
}
Swap Updates
The Swap Updates message represents updates to a swap request and provides details about the swap execution.
{
"T": "si",
"_": 1619096269032,
"S": "581faf3e-08b5-45ed-a0f0-0784f65e5e22", // swap request id
"ai": "ORN", // asset in
"a": 100.0, // amount in
"ao": "USDT", // asset out
"o": 450.0, // amount out
"p": 4.5, // price
"mo": 460.0, // market amount out, null for swap by amount out
"mi": null, // market amount in, null for swap by amount in
"mp": 4.6, // market price
"ma": 2.5, // min amount in
"mao": 12.0, // min amount out
"aa": 100.0, // available amount in, null for swap by amount out
"aao": null, // available amount out, null for swap by amount in
"ps": ["ORN", "USDT"], // path
"po": true, // is swap through pool optimal
"oi": { // info about the order equivalent to this swap
"p": "ORN-USDT", // asset pair
"s": "SELL", // side
"a": 100.0, // amount
"sp": 4.50675 // safe price (with safe deviation but without slippage)
},
"as": [ // execution alternatives
{
"e": ["PANCAKESWAP"], // exchanges
"ps": ["ORN", "USDT"], // path
"mo": 458.0, // market amount out
"mi": null, // market amount in
"mp": 4.58, // market price
"aa": 100.0, // available amount in
"aao": null, // available amount out
"po": true, // is swap through pool or curve optimal
"oi": { // info about the order equivalent to this swap
"p": "ORN-USDT", // asset pair
"s": "SELL", // side
"a": 100.0, // amount
"sp": 4.47675 // safe price (with safe deviation but without slippage)
}
}
],
"anm": { // address to ERC20 names, nullable
"0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c": "BNB",
"0x55d398326f99059ff775485246999027b3197955": "USDT"
}
}
Futures Trade Info Updates
Represents real-time updates for futures trade information.
{
"T": "fti", // message type "fti" - futures trade info
"_": 1619096269032, // Aggregator's timestamp in ms
"id": "UUID", // trade info request UUID, set by client side
"S": "0xADDRESS", // sender
"i": "BTCUSDF", // instrument
"bp": 22453.4, // buy price
"sp": 22453.3, // sell price
"bpw": 2.05, // buy power
"spw": 2.05, // sell power
"ma": 0.00054 // min amount
}
Error
Indicates an error response.
{
"T": "e", // message type "e" - error
"_": 1602847690892, // Aggregator's timestamp in ms
"c": 222310, // error code
"id": "UUID", // optional id of the message that the error is associated with
"m": "Error message"// error message
}
Unsubscription Done
Used as a response for unsubscription.
{
"T": "ud", // message type "ud" - unsubscription done
"_": 1619082969008, // Aggregator's timestamp in ms
"id": "UUID" // request id
}
Client Messages
Spot Address Updates Subscribe
Request for spot subscription to updates of the specified address.
Request for subscription to updates of the specified aggregated order book.
{
"T": "aobus", // message type "aobus" - aggregated order book updates subscribe
"S": "ORN-USDT", // target asset pair
"id": "UUID" // optional request id
}
Asset Pairs Config Updates Subscribe
Request for subscription to updates of the asset pairs configs.
{
"T": "apcus", // message type "apcus" - asset pairs config updates subscribe
"id": "UUID" // optional request id
}
Single Asset Pair Info Update Subscribe
Request for subscription to update of the specified asset pair info.
{
"T": "apius", // message type "apius" - asset pair info update subscribe
"S": "ORN-USDT", // target asset pair
"id": "UUID" // optional request id
}
Swap Info Subscribe
Request for subscription to updates of specified swap.
{
"T": "ss", // message type "ss" - swap subscribe
"S": {
"d": "UUID", // swap request UUID, set by client side
"i": "ORN", // asset in
"o": "USDT", // asset out
"a": 100.0, // amount IN/OUT
"e": true, // is amount IN? Value `false` means a = amount OUT, `true` if omitted
"es": ["EX1"], // exchanges for execution. Empty set means all exchanges. Empty set if omitted
"is": true // instant settlement flag, false if omitted
}
}
Futures Trade Info Subscribe
Request for subscription to updates of specified futures trade info.
{
"T": "fts", // message type "fts" - futures trade info subscribe
"S": {
"d": "UUID", // trade info request UUID, set by client side
"s": "0xADDRESS", // sender
"i": "BTCUSDF", // instrument
"a": 0.05, // amount
"p": null // optional target price. Null or absence means market order, limit otherwise
}
}
Unsubscribe - Ending Subscriptions
To unsubscribe from specific updates, use the following format:
To maintain a healthy connection, the Aggregator sends periodic pings, and the client responds with pongs:
{
"T": "pp",
"_": 1619170679409
}
Protocol - Establishing and Monitoring Connections
Connection - Initial Connection Message
After successfully establishing the connection, the Aggregator sends an initial message containing the connection ID to the client.
The connection has a limited lifetime of 24 hours. When approaching the limit, the Aggregator will inform the client with an error message:
{
"T": "e",
"_": 1602847690892,
"c": ERROR_CODE,
"id": "UUID",
"m": "WS connection has reached max allowed lifetime: 86400 seconds"
}
Keep Alive - Connection Maintenance
The Aggregator ensures connection continuity by sending pings at regular intervals and expecting corresponding pongs from the client.
To maintain the connection, the client must respond with the last received ping, unchanged. Failure to do so within the specified period (pong timeout) will lead to connection closure with the error message: "WS connection has reached pong timeout."
Subscriptions - Receiving Real-Time Updates
The WebSocket API provides various subscription options for real-time updates:
Address Updates - Monitoring Account Changes
The maximum count of address subscriptions per connection is limited to 10. Subscribing to the 11th address will result in an automatic unsubscribe from the first subscription, along with the message: "The limit of 10 subscriptions of this type was reached. The subscription of 0x1FF516E5ce741085CFF86d37fc27747dF852a80a was stopped."
Upon subscription, the client will receive a snapshot of the account balances and all active and finalized orders. Subsequent updates will be delivered in real-time.
Aggregated Order Book Updates - Tracking Market Depth
The maximum count of aggregated order book subscriptions per connection is limited to 3. Subscribing to the 4th asset pair will automatically unsubscribe the first subscription, accompanied by the same message as for address subscriptions.
Swap/Futures Trade Info Updates - Observing Trading Information
The maximum count of subscriptions per connection is limited to 10. Subscribing to the 11th swap or futures trade info will automatically unsubscribe from the first subscription, with the same message as for address subscriptions.
There is only one subscription option for asset pairs configuration updates. Stay informed about changes to the assets and their trading configurations.
