(Private WebSocket) User Account Information WebSocket Interface
Description
01. Private WebSocket connections do not require subscriptions; data is automatically pushed after a successful connection. This includes both trading messages and custom messages.
02. Trading messages are identified with the type type-event. Other message types will be defined separately.
03. The event field within the body of a trading message can be one of the following: Snapshot, ACCOUNT_UPDATE, DEPOSIT_UPDATE, WITHDRAW_UPDATE, TRANSFER_IN_UPDATE, TRANSFER_OUT_UPDATE, ORDER_UPDATE, FORCE_WITHDRAW_UPDATE, FORCE_TRADE_UPDATE, FUNDING_SETTLEMENT, ORDER_FILL_FEE_INCOME, START_LIQUIDATING, FINISH_LIQUIDATING, or UNRECOGNIZED.
04. Ping-Pong Mechanism:
Server Ping (Heartbeat):
After a successful WebSocket connection, the server sends a Ping message at a fixed interval. The message body looks like: {"type":"ping","time":"1693208170000"}. The time field is the server's timestamp when the Ping was sent.
The client must respond with a Pong message upon receipt, with a body like: {"type":"pong","time":"1693208170000"}.
If the server doesn't receive a Pong response after 5 consecutive Pings, the server will terminate the connection.
Client Ping (Latency Measurement):
After a successful WebSocket connection, the client can also initiate a Ping message with a body like: {"type":"ping","time":"1693208170000"}. The time field is the client's timestamp when the Ping was sent.
The server will immediately respond with a Pong message, with a body like: {"type":"pong","time":"1693208170000"}. The time field in the Pong will match the time field in the client's Ping.
05. Authentication:
Web:
Browsers don't allow custom headers during WebSocket connections, so special handling is required.
Use the same authentication logic as HTTP. Create a JSON string using the X-edgeX-Api-Signature, X-edgeX-Api-Timestamp key-value pairs, for example: {"X-edgeX-Api-Signature": "00e6b34cf9c3c0ca407cc2fe149fad836206c97201f236137c0e89fd079760470672b5257fa372710b5863d1ec6e0215e5bd6b2c3a319eda88886250a100524706ea3dd81a7fc864893c8c6f674e4a4510c369f939bdc0259a0980dfde882c2d", "X-edgeX-Api-Timestamp": "1705720068228"}.
Base64 encode this JSON string.
During the WebSocket request, pass the base64 encoded value in the SEC_WEBSOCKET_PROTOCOL header.
App/API:
App/API WebSocket connections can use custom headers. Therefore, Apps/API can continue using the same authentication logic as HTTP, or they can use the Web authentication method described above.
WebSocket is a GET request and there is no need to sign the request body.
URL: /api/v1/private/ws
Payload
{
// The type for trading messages is "trade-event". Custom messages have their own defined type. "error" indicates an error message sent by the server.
"type": "trade-event",
// The body of a trading message has the structure below. The message structure for custom messages will be defined separately by the user.
"content": {
// The event that triggered the data update
"event": "ACCOUNT_UPDATE",
// Data update version
"version": "1000",
// Data
"data": {
// Account information
"account": [
],
// Collateral information
"collateral": [
],
// Collateral transaction details
"collateralTransaction": [
],
// Position information
"position": [
],
// Position transaction details
"positionTransaction": [
],
// Deposit records
"deposit": [
],
// Withdrawal records
"withdraw": [
],
// Transfer in records
"transferIn": [
],
// Transfer out records
"transferOut": [
],
// Order information
"order": [
],
// Trade details
"orderFillTransaction": [
]
}
}
}
(Public WebSocket) Market Data WebSocket Interface
URL: /api/v1/public/ws
Description
01. When subscribing or unsubscribing, the server will validate the channel. For invalid channels, the server will respond with an error message, for example: {"type":"error","content":{"code":"INVALID_CONTRACT_ID""msg":"invalid contractId:100000001"}}
02. The message structure for subscribing and unsubscribing is: {"type": "subscribe", "channel": "ticker.10000001"}.
03. Ping-Pong Mechanism:
Server Ping (Heartbeat):
After a successful WebSocket connection, the server sends a Ping message at a fixed interval. The message body looks like: {"type":"ping","time":"1693208170000"}. The time field is the server's timestamp when the Ping was sent.
The client must respond with a Pong message upon receipt, with a body like: {"type":"pong","time":"1693208170000"}.
If the server doesn't receive a Pong response after 5 consecutive Pings, the server will terminate the connection.
Client Ping (Latency Measurement):
After a successful WebSocket connection, the client can also initiate a Ping message with a body like: {"type":"ping","time":"1693208170000"}. The time field is the client's timestamp when the Ping was sent.
The server will immediately respond with a Pong message, with a body like: {"type":"pong","time":"1693208170000"}. The time field in the Pong will match the time field in the client's Ping.
After a successful subscription, a full dataset is pushed once initially (depthType=SNAPSHOT), and subsequent pushes will be incremental updates (depthType=CHANGED).
Channel Explanation
Channel
Description
depth.{contractId}.{depth}
Subscribe to the order book of contract contractId with a depth of depth