Websocket Account Stream

There is only one stream type for accounts, and the events are distinguished internally by different event names.

Please view Websocket General Info to learn how to establish a WebSocket connection.

info

The account stream can only be subscribed via the raw stream (/v1/single).

Basic

Stream Name: account@<evm_address>

In the user's single connection, a URL parameter called marketId can be passed. Only ORDER_UPDATE and TRADE_UPDATE events related to this market will be returned in this connection.

Authentication

When creating a connection, the timestamp and signature must be provided as query parameters. Please refer to private endpoint authentication, the logic behind is the same.

For example:

/v1/single/account@0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf?timestamp=1&signature=0x242e3704e2cbe5a242c604f312448626029480c2cb9403883834c58fd2a2e7e21f60c100bc74d13554e1c722f403ece645d344347a875cf08618de3acf5b76bb01

If an incorrect signature is provided, or the timestamp is more than 5 seconds away from the server, the request will be rejected and the connection will be aborted.

Generate valid timestamp and signature

generate a timestamp in millisecond unit
conduct a string in this format account=<evm_address>&timestamp=<timestamp>
hash the string with keccak256
use the corresponding private key to sign the hash
convert the signature to hex string

Test case:

# Test private key
pk: 0000000000000000000000000000000000000000000000000000000000000001

# pararms
address: 0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf
timestamp: 1

# after step 2, you should get this string
dataToSign: account=0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf&timestamp=1

# after step3, you should get this hash
hash: 0x85d676ee821d5c20716fbeb15d13d746aed151347de335fd9c8ab06497f54802

# after step 4, you should get this signature
signature: 0x242e3704e2cbe5a242c604f312448626029480c2cb9403883834c58fd2a2e7e21f60c100bc74d13554e1c722f403ece645d344347a875cf08618de3acf5b76bb01

Events

All events that may appear in this stream.

Account Update

{
    "balances": {
        "availableCreditAmounts": {
            "btcusdc": {
                "buy": "7373.0064",
                "sell": "30256.7964"
            },
            "ethusdc": {
                "buy": "3686.5032",
                "sell": "3686.5032"
            }
        },
        "availableMargin": "368.65032",
        "exposure": "11441.895",
        "frozenMargin": "0",
        "isSafe": true,
        "leverage": "12.162588",
        "marginRate": "0.082219",
        "netValue": "940.74507",
        "pendingWithdrawPrimaryCreditAmount": "0",
        "pendingWithdrawSecondaryCreditAmount": "0",
        "perpetualBalances": {
            "btcusdc": {
                "creditAmount": "-11500.64995",
                "paperAmount": "0.5",
                "serialNumber": 1
            },
            "ethusdc": {
                "creditAmount": "0",
                "paperAmount": "0",
                "serialNumber": 0
            }
        },
        "positionMargin": "572.09475",
        "primaryCreditAmount": "999.50002",
        "secondaryCreditAmount": "0"
    },
    "event": "ACCOUNT_UPDATE",
    "positions": [
        {
            "marketId": "btcusdc",
            "side": "LONG",
            "status": "OPEN",
            "size": "0.5",
            "maxSize": "0.5",
            "unrealizedPnl": "-58.75495",
            "realizedPnl": "0",
            "entryPrice": "23001.2999",
            "exitPrice": "0",
            "closedAt": null,
            "sumOpen": "0.5",
            "sumClose": "0",
            "liquidationPrice": "21651.855525",
            "lastUpdatedAt": 1658541980614
        }
    ]
}

Balances

Parameter	Type	Mandatory	Description
exposure	STRING	YES	Total position exposure, in quoted asset unit.
netValue	STRING	YES	The net worth of an account, in quoted asset unit.
leverage	STRING	YES	exposure / netValue
marginRate	STRING	YES	netValue / exposure
frozenMargin	STRING	YES	The margin occupied by open orders
primaryCreditAmount	STRING	YES	The value of primaryAmount on the blockchain, in quoted asset unit. Corresponds to the amount of currency deposited.
secondaryCreditAmount	STRING	YES	The value of secondaryAmount on the blockchain, in quoted asset unit.
pendingWithdrawPrimaryCreditAmount	STRING	YES	The value of pendingWithdrawPrimaryCreditAmount on the blockchain, in quoted asset unit.
pendingWithdrawSecondaryCreditAmount	STRING	YES	The value of pendingWithdrawSecondaryCreditAmount on the blockchain, in quoted asset unit.
perpetualBalances	OBJECT	YES	Real-time data on the blockchain for each perpetual contract trading pair.
availableCreditAmounts	OBJECT	YES	The amount of funds that can be used to buy or sell in each market, in quoted asset unit.

Positions

The response has the same structure as the Position response.

Order Update

Stream Name: ORDER_UPDATE

{
    "event": "ORDER_UPDATE",
    "order": {
        "id": 572262767,
        "account": "0x1EdAd6DaD44367a6e0e342E76e9Df595049b8224",
        "marketId": "btcusdc",
        "side": "SELL",
        "price": "21000",
        "tif": "GTC",
        "type": "LIMIT",
        "amount": "0.01",
        "availableAmount": "0",
        "filledAmount": "0",
        "canceledAmount": "0",
        "pendingAmount": "0.01",
        "expiredAmount": "0",
        "failedAmount": "0",
        "json": {
            "perp": "0x0eC7f726E7e64aB93dE3AA9d238684d99262c53f",
            "signer": "0x1EdAd6DaD44367a6e0e342E76e9Df595049b8224",
            "sender": "0x7777405dB28BcAc40F6FD2AABc62751384aAD38c",
            "paperAmount": "-10000000000000000",
            "creditAmount": "210000000",
            "info": "0x00005af3107a40000001c6bf52634000000001819149fb1e8d670a252ebc350a"
        },
        "hash": "0x000B8BcAc40F6Dc6DaD4436bf520F6F2AaABc62119fb1e89fb1e8d670a2c350a",
        "createdAt": 1655999957825,
        "status": "FILLED"
    },
    "index": 8763157,
    "timestamp": 1675481351242
}

The order field in the response has the same structure as the Order response.

It is possible to receive consecutive ORDER_UPDATE events for an order. Note that these messages are not pushed in strict order of occurrence. Please determine the order according to the index in the message, a larger index means a later occurrence.

Trade Update

Stream Name: TRADE_UPDATE

{
  "event": "TRADE_UPDATE",
  "trade": {
    "id": 22639773614081,
    "orderId": 235951393874432,
    "orderHash": "0x12ff40b471c4f89eb012e6baae077e4e08a07ab4763e3ef6cba05e674a7146f8",
    "commission": "-0.1473227590706791240489",
    "isMaker": false,
    "isBuyer": true,
    "marketId": "btcusdc",
    "price": "69841.78",
    "amount": "0.007",
    "quoteAmount": "488.89246",
    "time": 1730165320875,
    "status": "CREATED",
    "timeInForce": "IOC",
    "realizedPNL": null,
    "orderType": "MARKET",
    "account": "0xa0736B75ee726e8B28C0a9C53f9A354486704D37"
  },
  "timestamp": 1730165320889,
  "index": 416991080
}

The trade field in the response has the same structure as the Trade response.

Income Update

Stream Name: INCOME_UPDATE

{
    "event": "INCOME_UPDATE",
    "incomes": [
        {
            "id": 1289,
            "type": "FUNDING_FEE",
            "amount": "-17.032035",
            "time": 1656000030678,
            "marketId": "btcusdc"
        }
    ]
}

The income list in the response has the same structure as the Income response.

Websocket Account Stream

Basic​

Authentication​

Generate valid timestamp and signature​

Events​

Account Update​

Order Update​

Trade Update​

Income Update​