Skip to main content

Private WebSockets

Private data WebSocket

  • All private data updates are realtime.

Establishing a WebSocket connection

  1. Getting private data from a single trading account.
  • Connect to /trading-api/v1/private-data?tradingAccountId=<id of the Trading Account>
  • For example, to subscribe to the orders topic, the following subscription message is sent:
{
"jsonrpc": "2.0",
"type": "command",
"method": "subscribe",
"params": {
"topic": "orders"
},
"id": "1611082473000"
}
  • It is possible to subscribe to multiple topics with a single subscription message. For example, a topic of assetAccounts+derivativesPositionsV2 would subscribe to both assetAccounts and derivativesPositionsV2
  1. Getting private data from multiple trading accounts.
  • Connect to /trading-api/v1/private-data
  • For example, to subscribe to the orders topic for each of your trading accounts, the following subscription message is sent for each trading account you wish to subscribe to:
{
"jsonrpc": "2.0",
"type": "command",
"method": "subscribe",
"params": {
"topic": "orders",
"tradingAccountId": "<Id of the Trading Account>"
},
"id": "1611082473000"
}
TopicDescriptionData TypeSubscription Type
ordersProvides snapshot and updates on your orders. The snapshot will contain all open orders and the 20 most recent closed orders.V1TAOrderBy <TOPIC>
tradesProvides snapshot and updates on your trades. The snapshot will contain the 20 most recent trades.V1TATradeBy <TOPIC>
spotAccountsDeprecated[more info] Provides snapshot and updates on assets in your account.V1TASpotAccountBy <TOPIC>
assetAccountsProvides snapshot and updates on assets in your account.V1TAAssetAccountBy <TOPIC>
tradingAccountsProvides snapshot and updates on your trading account summary.V1TATradingAccountBy <TOPIC>
heartbeatProvides heartbeat updates for health check.V1TAHeartbeatBy <TOPIC>
derivativesPositionsDeprecated[Replaced by: derivativesPositionsV2] Provides derivative position information on your trading account.V1TAPerpetualPositionBy <TOPIC>
derivativesPositionsV2Provides derivative position information on your trading account.V1TADerivativesPositionBy <TOPIC>
ammInstructionsProvides amm instructions update on your trading account.V1TAAmmInstructionBy <TOPIC>
mmpTriggerProvides snapshot and updates on your market maker protection trigger events.V1TAMMPTriggerBy <TOPIC>
mmpRequestProvides snapshot and updates on your market maker protection configurations.V1TAMMPConfigRequestBy <TOPIC>

Orders response

NameTypeDescription
handleStringunique numeric (i64) identifier generated on the client side expressed as a string value

Deprecatedto be remove towards the end of Q3 2024.
Replaced by: clientOrderId
clientOrderIdStringunique numeric (i64) identifier generated on the client side expressed as a string value
orderIdStringunique order id
symbolStringmarket symbol
priceStringprice, see asset value format
averageFillPriceStringaverage fill price, see asset value format
stopPriceStringstop price, see asset value format
marginBooleanindicates if the order was allowed to borrow (does not indicate that borrowing occurred)

Deprecatedto be remove towards the end of Q3 2024.
Replaced by: allowBorrow
allowBorrowBooleanindicates if the order was allowed to borrow (does not indicate that borrowing occurred)
quantityStringquantity, see asset value format
quoteAmountStringquote quantity deducted from asset account, see asset value format
quantityFilledStringquantity filled, see asset value format
baseFeeStringbase fee rate that will be charged upon trade execution, see asset value format
quoteFeeStringquote fee rate that will be charged upon trade execution, see asset value format
borrowedQuantityStringquantity borrowed, see asset value format - BUY order borrows quote, SELL order borrows base

Deprecatedto be remove towards the end of Q3 2024.
Replaced by: borrowedBaseQuantity & borrowedQuoteQuantity
borrowedBaseQuantityStringbase quantity borrowed, see asset value format
borrowedQuoteQuantityStringquote quantity borrowed, see asset value format
isLiquidationBooleanindicates if the order was executed as a liquidation order
sideStringorder side
typeStringorder type
timeInForceStringtime in force
statusStringorder status
statusReasonStringstatus reason, describes why the order is in a specific state
statusReasonCodeIntegerstatus reason code, see details
createdAtDatetimeStringdenotes the time the order was ACK'd by the exchange, ISO 8601 with millisecond as string
createdAtTimestampStringdenotes the time the order was ACK'd by the exchange
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TAOrder",
"data": [
{
"handle": null,
"orderId": "392883006043848705",
"symbol": "BTCUSD",
"price": "66858.2000",
"averageFillPrice": "66858.2000",
"stopPrice": null,
"margin": false,
"quantity": "2.00000000",
"quantityFilled": "2.00000000",
"quoteAmount": "23000.0000",
"baseFee": "0.00000000",
"quoteFee": "0.0005",
"side": "BUY",
"borrowedQuantity": "0.0010",
"isLiquidation": false,
"type": "LMT",
"timeInForce": "GTC",
"status": "CLOSED",
"statusReason": "Executed",
"statusReasonCode": 6002,
"createdAtDatetime": "2021-12-30T07:36:35.918Z",
"createdAtTimestamp": "1640849795918",
"publishedAtTimestamp": "1640849795920"
}
]
}

trades response

NameTypeDescription
tradeIdStringunique trade id
orderIdStringunique order id
handleStringunique numeric identifier (i64) generated on the client side expressed as a string value
symbolStringmarket symbol
priceStringprice, see asset value format
quantityStringquantity, see asset value format
quoteAmountStringquote quantity deducted from asset account, see asset value format
baseFeeStringbase fee, see asset value format
quoteFeeStringquote fee, see asset value format
sideStringorder side
tradeRebateAmountStringamount of rebate that is credited to the user as part of the trade
tradeRebateAssetSymbolStringsymbol of the asset in which the rebate is paid
isTakerBooleandenotes whether this is a taker's trade
otcMatchIdStringunique OTC match id
otcTradeIdStringunique Bullish OTC trade id
clientOtcTradeIdStringunique client OTC trade id
createdAtDatetimeStringdenotes the time the trade was executed by the exchange, ISO 8601 with millisecond as string
createdAtTimestampStringdenotes the time the trade was executed by the exchange
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TATrade",
"data": [
{
"tradeId": "100014000000000118",
"orderId": "392883006043848705",
"handle": "123456",
"symbol": "BTCUSD",
"price": "66858.2000",
"quantity": "2.00000000",
"quoteAmount": "23000.0000",
"baseFee": "0.00000000",
"quoteFee": "66.8582",
"side": "BUY",
"isTaker": false,
"tradeRebateAmount": "3.0000",
"tradeRebateAssetSymbol": "USDC",
"otcMatchId": "15",
"otcTradeId": "200014000000000118",
"clientOtcTradeId": "300014000000000118",
"createdAtDatetime": "2021-12-30T07:36:35.918Z",
"createdAtTimestamp": "1640849795918",
"publishedAtTimestamp": "1640849795920"
}
]
}

assetAccounts response

  • V1TAAssetAccount provides a more granular view of the assets in your trading account compared to V1TASpotAccount.
NameTypeDescription
tradingAccountIdStringid of the trading account
assetIdStringasset id
assetSymbolStringasset symbol
availableQuantityStringthe assets that are available to use on the account, see asset value format
borrowedQuantityStringthe assets on the account that are borrowed, see asset value format
lockedQuantityStringthe assets on the account that are locked in orders, loans, and AMM instructions, see asset value format
loanedQuantityStringthe assets on the account that are being loaned, see asset value format
updatedAtDatetimeStringdenotes the time the asset account was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestampStringdenotes the time the asset account was updated by the exchange
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TAAssetAccount",
"data": [
{
"tradingAccountId": "1111",
"assetId": "1",
"assetSymbol": "BTC",
"availableQuantity": "4.00000000",
"borrowedQuantity": "20.00000000",
"lockedQuantity": "0.00000000",
"loanedQuantity": "10.00000000",
"updatedAtDatetime": "2021-12-30T07:36:35.918Z",
"updatedAtTimestamp": "1640849795918",
"publishedAtTimestamp": "1640849795920"
},
{
"tradingAccountId": "1111",
"assetId": "2",
"assetSymbol": "USD",
"availableQuantity": "229016.0734",
"borrowedQuantity": "20000.0000",
"lockedQuantity": "0.0000",
"loanedQuantity": "10000.0000",
"updatedAtDatetime": "2021-12-30T07:36:35.918Z",
"updatedAtTimestamp": "1640849795918",
"publishedAtTimestamp": "1640849795920"
}
]
}

tradingAccounts response

  • Provides a summary of the total borrowed and total collateral values on the specific trading account id. totalBorrowedQuantity and totalCollateralQuantity do not represent the absolute quantity of the borrowed assets and are notional values represented in the reference asset.
  • snapshot contains a list with a single entry corresponding to the trading account id specified in the tradingAccountId query parameter when opening the WebSocket connection.
NameTypeDescription
tradingAccountIdStringid of the trading account
totalBorrowedQuantityStringtotal borrowed across all assets in this trading account displayed in the reference asset
totalCollateralQuantityStringtotal collateral across all assets in this trading account displayed in the reference asset
totalBorrowedUSDStringtotal borrowed across all assets in this trading account displayed in USD
totalCollateralUSDStringtotal collateral across all assets in this trading account displayed in USD
initialMarginUSDStringThe minimum margin one must maintain in order to be able to purposefully increase risk
warningMarginUSDStringThe minimum margin when the customer will receive warning via email/notifications over UI
liquidationMarginUSDStringThe minimum value of margin one must maintain in order to avoid liquidation
fullLiquidationMarginUSDStringThe value of margin when full liquidation occurs
endCustomerIdStringThe end customer id used for self trade prevention (default is institution id, max 32 characters)
defaultedMarginUSDStringThe value of margin when this trading account will be moved into a Defaulted state
riskLimitUSDStringThe maximum allowed borrowing for this trading account displayed in USD
totalLiabilitiesUSDStringThe total liabilities for this trading account displayed in USD
maxInitialLeverageStringThe maximum initial leverage
isPrimaryAccountStringWhether this trading account is the primary account
isBorrowingStringWhether this trading account is borrowing any asset
isLendingStringWhether this trading account has any open loan offers
isDefaultedStringWhether this trading account is in a defaulted state
takerFeeStringDeprecated and no longer accurate. See tradeFeeRate at Get Trading Account instead
makerFeeStringDeprecated and no longer accurate. See tradeFeeRate at Get Trading Account instead
referenceAssetSymbolStringasset symbol
liquidityAddonUSDStringExpected market impact of unwinding the portfolio in the case of a liquidation event
marketRiskUSDStringThe worst possible loss on the portfolio based on scenario analysis
marginProfileObjectContains the market risk multipliers applied to a trading account to derive the five individual Margin Requirement values
initialMarketRiskMultiplierPctStringMarket risk multiplier used to calculate initial margin requirement of the account
warningMarketRiskMultiplierPctStringMarket risk multiplier used to calculate warning margin requirement of the account
liquidationMarketRiskMultiplierPctStringMarket risk multiplier used to calculate liquidation margin requirement of the account
fullLiquidationMarketRiskMultiplierPctStringMarket risk multiplier used to calculate full liquidation margin requirement of the account
defaultedMarketRiskMultiplierPctStringMarket risk multiplier used to calculate defaulted margin requirement of the account
updatedAtDatetimeStringdenotes the time the trading account was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestampStringdenotes the time the trading account was updated by the exchange
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TATradingAccount",
"data": [
{
"tradingAccountId": "1111",
"totalBorrowedQuantity": "12000.0000",
"totalCollateralQuantity": "13000.0000",
"totalBorrowedUSD": "12000.0000",
"totalCollateralUSD": "13000.0000",
"referenceAssetSymbol": "USD",
"initialMarginUSD": "900000.0000",
"warningMarginUSD": "700000.0000",
"liquidationMarginUSD": "600000.0000",
"fullLiquidationMarginUSD": "500000.0000",
"endCustomerId": "PrimeBroker",
"defaultedMarginUSD": "300000.0000",
"riskLimitUSD": "1000000.0000",
"totalLiabilitiesUSD": "13000.0000",
"maxInitialLeverage": "3",
"isPrimaryAccount": true,
"isBorrowing": true,
"isLending": false,
"isDefaulted": false,
"takerFee": null,
"makerFee": null,
"liquidityAddonUSD": "100.0000",
"marketRiskUSD": "200.0000",
"marginProfile": {
"initialMarketRiskMultiplierPct": "200.00",
"warningMarketRiskMultiplierPct": "150.00",
"liquidationMarketRiskMultiplierPct": "100.00",
"fullLiquidationMarketRiskMultiplierPct": "75.00",
"defaultedMarketRiskMultiplierPct": "50.00"
},
"updatedAtDatetime": "2021-12-30T07:36:35.918Z",
"updatedAtTimestamp": "1640849795918",
"publishedAtTimestamp": "1640849795920"
}
]
}

Heartbeat response

  • Provides heartbeat update every 30s as an indicator of platform healthiness. Please refer to the heartbeat section for the details.
NameTypeDescription
sequenceNumberStringsequence number of the heartbeat
createdAtTimestampStringtime at which the heartbeat is generated
{
"type": "update",
"dataType": "V1TAHeartbeat",
"data": [
{
"sequenceNumber": "3",
"createdAtTimestamp": "1611082473000"
}
]
}

Derivative position response

Deprecated: Topic derivativesPosition will be replaced by derivativesPositionV2

  • Provide a detail view of the derivative position of each market.
NameTypeDescription
tradingAccountIdStringid of the trading account
symbolStringMarket symbol, e.g. BTC-USDC-PERP
sideStringSide of the position
quantityStringCurrent size of the position asset value format
notionalStringNotional value of the current position, calculated using the mark price
entryNotionalStringNotional value of the position, using the average entry price
mtmPnlStringSum of all mark-to-market profits and losses plus profits and losses realized from trading, accumulated since the last settlement
reportedMtmPnlStringThe profit/losses from the net price change since the last time the absolute quantity decreased. It is updated with every mark to market and is not updated during settlement or a position size increase
reportedFundingPnlStringSum of all funding payments received since the position was opened. This is updated every time funding is paid.
realizedPnlStringTotal profits realized since the trading account first opened this position. This is only updated every time a position's absolute quantity (aka size) is reduced.
createdAtDatetimeStringdenotes the time the position was created by the exchange, ISO 8601 with millisecond as string
createdAtTimestampStringdenotes the time the position was created by the exchange, number of milliseconds since EPOCH
updatedAtDatetimeStringdenotes the time the position was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestampStringdenotes the time the position was updated by the exchange number of milliseconds since EPOCH
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TAPerpetualPosition",
"data": [
{
"tradingAccountId": "111234567890",
"symbol": "BTC-USDC-PERP",
"side": "BUY",
"quantity": "1.00000000",
"notional": "30000.0000",
"entryNotional": "30000.0000",
"mtmPnl": "110.0000",
"reportedMtmPnl": "120.0000",
"reportedFundingPnl": "130.0000",
"realizedPnl": "140.0000",
"createdAtDatetime": "2020-01-01T00:00:00.000Z",
"createdAtTimestamp": "1577836800000",
"updatedAtDatetime": "2020-01-02T00:00:00.000Z",
"updatedAtTimestamp": "1577923200000",
"publishedAtTimestamp": "1577923300000"
}
]
}

Derivative position V2 response

  • Provide a detail view of the derivative position of each market.
NameTypeDescription
tradingAccountIdStringid of the trading account
symbolStringMarket symbol, e.g. BTC-USDC-PERP
sideStringSide of the position
quantityStringCurrent size of the position asset value format
notionalStringNotional value of the current position, calculated using the mark price
entryNotionalStringNotional value of the position, using the average entry price
mtmPnlStringSum of all mark-to-market profits and losses plus profits and losses realized from trading, accumulated since the last settlement
reportedMtmPnlStringThe profit/losses from the net price change since the last time the absolute quantity decreased. It is updated with every mark to market and is not updated during settlement or a position size increase
reportedFundingPnlStringSum of all funding payments received since the position was opened. This is updated every time funding is paid.
realizedPnlStringTotal profits realized since the trading account first opened this position. This is only updated every time a position's absolute quantity (aka size) is reduced.
settlementAssetSymbolStringSettlement asset symbol
eventTypeStringDerivatives position update event types
createdAtDatetimeStringdenotes the time the position was created by the exchange, ISO 8601 with millisecond as string
createdAtTimestampStringdenotes the time the position was created by the exchange, number of milliseconds since EPOCH
updatedAtDatetimeStringdenotes the time the position was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestampStringdenotes the time the position was updated by the exchange number of milliseconds since EPOCH
publishedAtTimestampStringdenotes the time the update was broadcasted to connected WebSockets
{
"tradingAccountId": "1111",
"type": "snapshot",
"dataType": "V1TADerivativesPosition",
"data": [
{
"tradingAccountId": "111234567890",
"symbol": "BTC-USDC-PERP",
"side": "BUY",
"quantity": "1.00000000",
"notional": "30000.0000",
"entryNotional": "30000.0000",
"mtmPnl": "110.0000",
"reportedMtmPnl": "120.0000",
"reportedFundingPnl": "130.0000",
"realizedPnl": "140.0000",
"settlementAssetSymbol": "USDC",
"eventType": "settlementUpdate",
"createdAtDatetime": "2020-01-01T00:00:00.000Z",
"createdAtTimestamp": "1577836800000",
"updatedAtDatetime": "2020-01-02T00:00:00.000Z",
"updatedAtTimestamp": "1577923200000",
"publishedAtTimestamp": "1577923300000"
}
]
}

ammInstruction response

  • Provides updates of the active AMM instructions on the specific trading account id.
  • This topic does not provide snapshot
NameTypeDescription
tradingAccountIdStringid of the trading account
instructionIdStringunique AMM instruction id
symbolStringmarket symbol
baseFeeStringbase fee, see asset value format
quoteFeeStringquote fee, see asset value format
statusStringorder status
statusReasonStringstatus reason, describes why the order is in a specific state
statusReasonCodeStringstatus reason code, see details
createdAtDatetimeStringdenotes the time the order was ACK'd by the exchange, ISO 8601 with millisecond as string
createdAtTimestampStringdenotes the time the order was ACK'd by the exchange
baseCurrentQuantityStringamount of base asset this AMM instruction currently holds, only for AMM instruction with OPEN status
baseInvestQuantityStringinitial base investment
basePriceStringcurrent price of base asset
baseWithdrawQuantityStringamount of base asset returned when AMM instruction is terminated
currentValueStringvalue of assets (base and quote) in USD amount that this AMM instruction currently holds
feeTierIdStringunique fee tier id, see Get Market By Symbol
finalValueStringvalue of assets (base and quote) in USD amount when AMM instruction was terminated, only for AMM instruction with CLOSED status
impermanentLossStringimpermanent loss
liquidityStringliquidity amount
lastDistributedPriceString(Perpetual market only) The price used at the time of settlement for AMM Instructions that can be used to determine mtmPnl and the actual Pnl
lowerBoundStringlower bound of price range, in quote currency
priceStringcurrent price of AMM, see Get Tick By Symbol
quoteCurrentQuantityStringamount of quote asset this AMM instruction currently holds, only for AMM instruction with OPEN status
quoteInvestQuantityStringinitial quote investment
quotePriceStringcurrent price of quote asset
quoteWithdrawQuantityStringamount of quote asset returned when AMM instruction is terminated
requestIDStringunique request id
updatedAtDatetimeStringdenotes the time the AMM instruction was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestampStringdenotes the time the AMM instruction was updated by the exchange
upperBoundStringupper bound of price range, in quote currency
{
"tradingAccountId": "1111",
"type": "update",
"dataType": "V1TAAmmInstruction",
"data": [
{
"instructionId": "100",
"symbol": "BTCUSDC",
"baseFee": "1.00000000",
"quoteFee": "1.0000",
"status": "OPEN",
"statusReason": "Ok",
"statusReasonCode": "1001",
"createdAtDatetime": "2021-05-20T01:01:01.000Z",
"createdAtTimestamp": "1621490985000",
"baseCurrentQuantity": "0.00000000",
"baseInvestQuantity": "0.00000008",
"basePrice": "345.67000000",
"baseWithdrawQuantity": "0.00000010",
"currentValue": "0.0000",
"feeTierId": "1",
"finalValue": "0.0001",
"impermanentLoss": "0.0000",
"liquidity": "0.0001",
"lowerBound": "0.0013",
"price": "456.7800",
"quoteCurrentQuantity": "0.0000",
"quoteInvestQuantity": "0.0009",
"quotePrice": "1.0000",
"quoteWithdrawQuantity": "0.0011",
"lastDistributedPrice": null,
"requestId": "197735387747975680",
"updatedAtDatetime": "2021-05-20T01:01:01.000Z",
"updatedAtTimestamp": "1621490985000",
"upperBound": "14000.0000"
}
]
}

mmpTrigger response

NameTypeDescription
tradingAccountIdStringid of the trading account
mmpTriggerIdStringunique MMP trigger id
underlyingAssetSymbolStringunderlying asset symbol
triggeredByStringtrigger reason
frozenTimeInSecondStringduration for which a market maker's trading activity is temporarily halted after a protective measure is triggered
frozenStartTimeStringstart time of the MMP trigger in epoch milliseconds
frozenUntilStringend time of the MMP trigger in epoch milliseconds
{
"tradingAccountId": "111000000000000",
"type": "snapshot",
"dataType": "V1TAMMPTrigger",
"data": [
{
"mmpTriggerId": "100000000000000"
"tradingAccountId": "111000000000000",
"underlyingAssetSymbol": "BTC",
"triggeredBy": "Delta Limit",
"frozenTimeInSecond": "10",
"frozenStartTime": "1611082473000",
"frozenUntil": "1611082483000"
}
]
}

mmpRequest response

NameTypeDescription
tradingAccountIdStringid of the trading account
requestIdStringid of the request
assetSymbolStringunderlying asset symbol
windowTimeInSecondStringtime window during which the MMP checks are conducted
frozenTimeInSecondStringduration for which a market maker's trading activity is temporarily halted after a protective measure is triggered
quantityLimitStringcap on the total number of contracts that a market maker can trade within windowTimeInSeconds
deltaLimitStringnet delta exposure that a market maker can accumulate within windowTimeInSeconds
statusStringstatus of the request
statusReasonStringstatus reason, describes why the request is in a specific state
isResetStringboolean value that indicates if it was a set or reset MMP configuration request
createdAtStringdenotes the time the request was ACK'd by the exchange
{
"tradingAccountId": "111000000000000",
"type": "snapshot",
"dataType": "V1TAMMPConfigRequest",
"data": [
{
"requestId": "1",
"tradingAccountId": "111000000000000",
"assetSymbol": "BTC",
"windowTimeInSecond": "10",
"frozenTimeInSecond": "10",
"quantityLimit": "1000",
"deltaLimit": "500",
"status": "CLOSED",
"statusReason": "Ok",
"isReset": "false",
"createdAt": "1611082473000"
}
]
}

See connect to private data WebSocket for a sample Python script.