Bullish WebSocket Private Data API
AsyncAPI 3.0.0 document for the authenticated private stream — real-time orders, trades, asset accounts, trading accounts, derivatives positions, AMM instructions and market-maker-protection triggers.
AsyncAPI Specification
asyncapi: 3.0.0
info:
title: Private Data
version: 1.0.0
description: |
All private data updates are realtime.
Multiple topics and multiple accounts can be subscribed to within a single connection.
A default subscribed trading account can be pre-specified by using this endpoint.
```
/trading-api/v1/private-data?tradingAccountId={id}
```
Otherwise controlled by parameters in the subscription message listed below
```
/trading-api/v1/private-data
```
Please note that [authentication is mandatory](/websocket/protocol/authentication)
servers:
prod-public:
host: api.exchange.bullish.com
protocol: wss
description: Production / Public
prod-registered:
host: registered.api.exchange.bullish.com
protocol: wss
description: Production / Registered
prod-direct:
host: prod.access.bullish.com
protocol: wss
description: Production / Direct Connect
simnext-public:
host: api.simnext.bullish-test.com
protocol: wss
description: SimNext / Public
simnext-registered:
host: registered.api.simnext.bullish-test.com
protocol: wss
description: SimNext / Registered
simnext-direct:
host: simnext.access.bullish.com
protocol: wss
description: SimNext / Direct Connect
channels:
data:
address: /trading-api/v1/private-data
messages:
subscribe:
title: Subscription
summary: Let you subscribe to a given topic
payload:
type: object
required:
- id
- method
- params
properties:
method:
type: string
description: '"subscribe"'
example: subscribe
id:
$ref: "#/components/schemas/PrivateDataJsonRpcRequestId"
jsonrpc:
$ref: "#/components/schemas/PrivateDataJsonRpcVersion"
type:
$ref: "#/components/schemas/PrivateDataJsonRpcCommandType"
params:
type: object
required:
- topic
- tradingAccountId
properties:
topic:
type: string
description: |
Topic selected among
- [orders](/websocket/private/private-data#operation-receive-orders)
- [trades](/websocket/private/private-data#operation-receive-trades)
- ~~[spotAccounts](/websocket/private/private-data#operation-receive-spotAccounts)~~ `Deprecated`
- [assetAccounts](/websocket/private/private-data#operation-receive-assetAccounts)
- [tradingAccounts](/websocket/private/private-data#operation-receive-tradingAccounts)
- ~~[derivativesPositions](/websocket/private/private-data#operation-receive-derivativesPositions)~~ `Deprecated`
- [derivativesPositionsV2](/websocket/private/private-data#operation-receive-derivativesPositionsV2)
- [ammInstructions](/websocket/private/private-data#operation-receive-ammInstructions)
- [mmpTrigger](/websocket/private/private-data#operation-receive-mmpTrigger)
- [mmpRequest](/websocket/private/private-data#operation-receive-mmpRequest)
example: orders
tradingAccountId:
type: string
description: Trading account Id to be subscribed to
example: "1111"
subscribe-ack:
title: Acknowledgment
summary: Confirm the subscription was opened
payload:
type: object
properties:
id:
$ref: "#/components/schemas/PrivateDataJsonRpcRequestId"
jsonrpc:
$ref: "#/components/schemas/PrivateDataJsonRpcVersion"
result:
type: object
properties:
responseCodeName:
type: string
description: '"OK"'
example: OK
responseCode:
type: string
description: "200"
example: "200"
message:
type: string
description: Confirmation that the subscription was opened
example: Successfully subscribed
subscribe-msg-0-orders:
title: Snapshot
summary: Initial full state of the subscribed order data
payload:
type: object
properties:
type:
type: string
description: '"snapshot"'
example: snapshot
dataType:
type: string
description: '"V1TAOrder"'
example: V1TAOrder
data:
type: array
description: List of orders
items:
type: object
properties:
handle:
type: string
description: |
unique numeric (i64) identifier generated on the client side expressed as a string value
Deprecated; scheduled for removal.
Replaced by: clientOrderId
example: null
clientOrderId:
type: string
description: unique numeric (i64) identifier generated on the client side expressed as a string value
example: null
orderId:
type: string
description: unique order id
example: "392883006043848705"
symbol:
type: string
description: market symbol
example: BTCUSD
price:
type: string
description: price, see asset value format
example: "66858.2000"
averageFillPrice:
type: string
description: average fill price, see asset value format
example: "66858.2000"
stopPrice:
type: string
description: stop price, see asset value format
example: null
margin:
type: boolean
description: |
indicates if the order was allowed to borrow (does not indicate that borrowing occurred)
Deprecated; scheduled for removal.
Replaced by: allowBorrow
example: false
allowBorrow:
type: boolean
description: indicates if the order was allowed to borrow (does not indicate that borrowing occurred)
example: false
quantity:
type: string
description: quantity, see asset value format
example: "2.00000000"
quantityFilled:
type: string
description: quantity filled, see asset value format
example: "2.00000000"
quoteAmount:
type: string
description: quote quantity deducted from asset account, see asset value format
example: "23000.0000"
baseFee:
type: string
description: base fee rate that will be charged upon trade execution, see asset value format
example: "0.00000000"
quoteFee:
type: string
description: quote fee rate that will be charged upon trade execution, see asset value format
example: "0.0005"
side:
type: string
description: order side
example: BUY
borrowedQuantity:
type: string
description: |
quantity borrowed, see asset value format - BUY order borrows quote, SELL order borrows base
Deprecated; scheduled for removal.
Replaced by: borrowedBaseQuantity and borrowedQuoteQuantity
example: "0.0010"
isLiquidation:
type: string
description: indicates if the order was executed as a liquidation order
example: false
type:
type: string
description: order type
example: LMT
timeInForce:
type: string
description: time in force
example: GTC
status:
type: string
description: order status
example: CLOSED
statusReason:
type: string
description: status reason code, see details
example: Executed
statusReasonCode:
type: string
description: status reason code, see details
example: 6002
createdAtDatetime:
type: string
description: denotes the time the order was ACK'd by the exchange, ISO 8601 with millisecond as string
example: "2021-12-30T07:36:35.918Z"
createdAtTimestamp:
type: string
description: denotes the time the order was ACK'd by the exchange
example: "1640849795918"
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
example: "1640849795920"
example:
- 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"
subscribe-msg-1-orders:
title: Update
summary: Incremental update to the subscribed order data
payload:
type: object
properties:
type:
type: string
description: '"update"'
example: update
dataType:
type: string
description: '"V1TAOrder"'
example: V1TAOrder
data:
description: An order
type: object
properties:
handle:
type: string
description: |
unique numeric (i64) identifier generated on the client side expressed as a string value
Deprecated; scheduled for removal.
Replaced by: clientOrderId
example: null
clientOrderId:
type: string
description: unique numeric (i64) identifier generated on the client side expressed as a string value
example: null
orderId:
type: string
description: unique order id
example: "392883006043848705"
symbol:
type: string
description: market symbol
example: BTCUSD
price:
type: string
description: price, see asset value format
example: "66858.2000"
averageFillPrice:
type: string
description: average fill price, see asset value format
example: "66858.2000"
stopPrice:
type: string
description: stop price, see asset value format
example: null
margin:
type: boolean
description: |
indicates if the order was allowed to borrow (does not indicate that borrowing occurred)
Deprecated; scheduled for removal.
Replaced by: allowBorrow
example: false
allowBorrow:
type: boolean
description: indicates if the order was allowed to borrow (does not indicate that borrowing occurred)
example: false
quantity:
type: string
description: quantity, see asset value format
example: "2.00000000"
quantityFilled:
type: string
description: quantity filled, see asset value format
example: "2.00000000"
quoteAmount:
type: string
description: quote quantity deducted from asset account, see asset value format
example: "23000.0000"
baseFee:
type: string
description: base fee rate that will be charged upon trade execution, see asset value format
example: "0.00000000"
quoteFee:
type: string
description: quote fee rate that will be charged upon trade execution, see asset value format
example: "0.0005"
side:
type: string
description: order side
example: BUY
borrowedQuantity:
type: string
description: |
quantity borrowed, see asset value format - BUY order borrows quote, SELL order borrows base
Deprecated; scheduled for removal.
Replaced by: borrowedBaseQuantity and borrowedQuoteQuantity
example: "0.0010"
isLiquidation:
type: string
description: indicates if the order was executed as a liquidation order
example: false
type:
type: string
description: order type
example: LMT
timeInForce:
type: string
description: time in force
example: GTC
status:
type: string
description: order status
example: CLOSED
statusReason:
type: string
description: status reason code, see details
example: Executed
statusReasonCode:
type: string
description: status reason code, see details
example: 6002
createdAtDatetime:
type: string
description: denotes the time the order was ACK'd by the exchange, ISO 8601 with millisecond as string
example: "2021-12-30T07:36:35.918Z"
createdAtTimestamp:
type: string
description: denotes the time the order was ACK'd by the exchange
example: "1640849795918"
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
example: "1640849795920"
example:
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"
subscribe-msg-0-trades:
title: Snapshot
summary: Initial full state of the subscribed trade data
payload:
type: object
properties:
type:
type: string
description: '"snapshot"'
example: snapshot
dataType:
type: string
description: '"V1TATrade"'
example: V1TATrade
data:
type: array
description: List of trades
items:
type: object
properties:
tradeId:
type: string
description: unique trade id
orderId:
type: string
description: unique order id
handle:
type: string
description: unique numeric identifier (i64) generated on the client side expressed as a string value
symbol:
type: string
description: market symbol
price:
type: string
description: price, see asset value format
quantity:
type: string
description: quantity, see asset value format
quoteAmount:
type: string
description: quote quantity deducted from asset account, see asset value format
baseFee:
type: string
description: base fee, see asset value format
quoteFee:
type: string
description: quote fee, see asset value format
side:
type: string
description: order side
tradeRebateAmount:
type: string
description: amount of rebate that is credited to the user as part of the trade
tradeRebateAssetSymbol:
type: string
description: symbol of the asset in which the rebate is paid
isTaker:
type: boolean
description: denotes whether this is a taker's trade
otcMatchId:
type: string
description: unique OTC match id
otcTradeId:
type: string
description: unique Bullish OTC trade id
clientOtcTradeId:
type: string
description: unique client OTC trade id
createdAtDatetime:
type: string
description: denotes the time the trade was executed by the exchange, ISO 8601 with millisecond as string
createdAtTimestamp:
type: string
description: denotes the time the trade was executed by the exchange
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
auctionId:
type: string
description: unique Bullish auction identifier. Present only for auction trades
example:
- 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"
subscribe-msg-1-trades:
title: Update
summary: Incremental update to the subscribed trade data
payload:
type: object
properties:
type:
type: string
description: '"update"'
example: update
dataType:
type: string
description: '"V1TATrade"'
example: V1TATrade
data:
description: A trade
type: object
properties:
tradeId:
type: string
description: unique trade id
orderId:
type: string
description: unique order id
handle:
type: string
description: unique numeric identifier (i64) generated on the client side expressed as a string value
symbol:
type: string
description: market symbol
price:
type: string
description: price, see asset value format
quantity:
type: string
description: quantity, see asset value format
quoteAmount:
type: string
description: quote quantity deducted from asset account, see asset value format
baseFee:
type: string
description: base fee, see asset value format
quoteFee:
type: string
description: quote fee, see asset value format
side:
type: string
description: order side
tradeRebateAmount:
type: string
description: amount of rebate that is credited to the user as part of the trade
tradeRebateAssetSymbol:
type: string
description: symbol of the asset in which the rebate is paid
isTaker:
type: boolean
description: denotes whether this is a taker's trade
otcMatchId:
type: string
description: unique OTC match id
otcTradeId:
type: string
description: unique Bullish OTC trade id
clientOtcTradeId:
type: string
description: unique client OTC trade id
createdAtDatetime:
type: string
description: denotes the time the trade was executed by the exchange, ISO 8601 with millisecond as string
createdAtTimestamp:
type: string
description: denotes the time the trade was executed by the exchange
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
auctionId:
type: string
description: unique Bullish auction identifier. Present only for auction trades
example:
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"
subscribe-msg-0-spotAccounts:
title: Snapshot
summary: Initial full state of the subscribed spot accounts data
payload:
type: object
properties:
type:
type: string
description: '"snapshot"'
example: snapshot
dataType:
type: string
description: '"V1TASpotAccount"'
example: V1TASpotAccount
data:
type: array
description: List of spot accounts
items:
type: object
example:
- {}
subscribe-msg-1-spotAccounts:
title: Update
summary: Incremental update to the subscribed spot accounts data
payload:
type: object
properties:
type:
type: string
description: '"update"'
example: update
dataType:
type: string
description: '"V1TASpotAccount"'
example: V1TASpotAccount
data:
description: A spot account
type: object
example: {}
subscribe-msg-0-assetAccounts:
title: Snapshot
summary: Initial full state of the subscribed asset accounts data
payload:
type: object
properties:
type:
type: string
description: '"snapshot"'
example: snapshot
dataType:
type: string
description: '"V1TAAssetAccount"'
example: V1TAAssetAccount
data:
type: array
description: List of asset accounts
items:
type: object
properties:
tradingAccountId:
type: string
description: id of the trading account
assetId:
type: string
description: asset id
assetSymbol:
type: string
description: asset symbol
availableQuantity:
type: string
description: the assets that are available to use on the account, see asset value format
borrowedQuantity:
type: string
description: the assets on the account that are borrowed, see asset value format
lockedQuantity:
type: string
description: the assets on the account that are locked in orders, loans, and AMM instructions, see asset value format
loanedQuantity:
type: string
description: the assets on the account that are being loaned, see asset value format
updatedAtDatetime:
type: string
description: denotes the time the asset account was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestamp:
type: string
description: denotes the time the asset account was updated by the exchange
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
example:
- 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"
subscribe-msg-1-assetAccounts:
title: Update
summary: Incremental update to the subscribed asset accounts data
payload:
type: object
properties:
type:
type: string
description: '"update"'
example: update
dataType:
type: string
description: '"V1TAAssetAccount"'
example: V1TAAssetAccount
data:
description: An asset accounts
type: object
properties:
tradingAccountId:
type: string
description: id of the trading account
assetId:
type: string
description: asset id
assetSymbol:
type: string
description: asset symbol
availableQuantity:
type: string
description: the assets that are available to use on the account, see asset value format
borrowedQuantity:
type: string
description: the assets on the account that are borrowed, see asset value format
lockedQuantity:
type: string
description: the assets on the account that are locked in orders, loans, and AMM instructions, see asset value format
loanedQuantity:
type: string
description: the assets on the account that are being loaned, see asset value format
updatedAtDatetime:
type: string
description: denotes the time the asset account was updated by the exchange, ISO 8601 with millisecond as string
updatedAtTimestamp:
type: string
description: denotes the time the asset account was updated by the exchange
publishedAtTimestamp:
type: string
description: denotes the time the update was broadcasted to connected WebSockets
example:
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"
subscribe-msg-0-tradingAccounts:
title: Snapshot
summary: Initial full state of the subscribed trading accounts data
payload:
type: object
properties:
type:
type: string
description: '"snapshot"'
example: snapshot
dataType:
type: string
description: '"V1TATradingAccount"'
example: V1TATradingAccount
data:
type: array
description: List of trading accounts
items:
type: object
properties:
tradingAc
# --- truncated at 32 KB (95 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bullish/refs/heads/main/asyncapi/bullish-ws-private-data-asyncapi.yml