wss://big.one/ws/v2
You need to authenticate customer before subscribe private data, like Order, Account etc.
Currently, we support two protocols: proto and json. Default json.
In proto mode, we utilize Google's Protocol Buffers (Protobuf ) to encode and decode data streams. The advantage of using Protobuf is that it compresses the data stream to a minimal size, reducing transmission latency. Furthermore, developers can auto-generate the corresponding data structures by providing a proto file, which is significantly lowering the barrier to entry.
Set the request header Sec-WebSocket-Protocolproto or json.
We recommand the proto format, and the proto file is here
requestId serves as the identifier for API requests. API responses will include the requestId, enabling you to match each response with its corresponding request. Therefore, it's essential to use a unique requestId for each request to ensure accurate tracking.
After successfully subscribing, the API will return the snapshot data first, then the update data if the subscription generates new data.
{
"requestId" :"1" ,
"error" :{
"code" :45000 ,
"message" :"GRPC error: xxx"
}
}
Developers can use the Ping/Pong frame to keep the connection alive. Also we have priovid a HeartBeat message.
code type
45000 grpc error 45001 login status error other default error
{"requestId" :"1" , "authenticateCustomerRequest" :{"token" :"Bearer {YOUR_TOKEN}" }}
Name Description Example Require
market id of market BTC-USDT true
{"requestId" : "1" , "subscribeMarketDepthRequest" :{"market" :"BTC-USDT" }}
After a user sends a subscription request for Depth data, the server will first push a depth snapshot of this market. Then, upon any changes in Depth, the server will push updates for the Depth data.
{
"requestId" : "1" ,
"depthSnapshot" : {
"depth" : {
"market" :"BTC-USDT" ,
"asks" :[
{
"price" :"197.96" ,
"amount" :"5.0" ,
"orderCount" :1
}
],
"bids" :[
{
"price" :"159.99" ,
"amount" :"1.07552" ,
"orderCount" :1
}
]
},
"changeId" :"2" ,
"prevId" :"1"
}
}
{
"requestId" : "1" ,
"depthUpdate" : {
"depth" : {
"market" :"BTC-USDT" ,
"asks" :[
{
"price" :"197.96" ,
"amount" :"5.0" ,
"orderCount" :"1"
}
],
"bids" :[
{
"price" :"159.99" ,
"amount" :"1.07552" ,
"orderCount" :"1"
}
]
},
"changeId" :"2" ,
"prevId" :"1"
}
}
Name type Description Example
market String market symbol BTC-USDT asks PriceLevel Ask side (Sell side) bids PriceLevel Bid side (Buy side) changeId String Current change ID of this market prevId String Last change ID of this market changeId and prevId are always sequential numbers. Developers can determine the accuracy of their local Depth data by comparing the values of changeId and prevId.
Name type Description Example
price String ask price 197.96 amount String ask amount 5.0 orderCount Int ask order count 1
{"requestId" : "1" , "unsubscribeMarketDepthRequest" :{"market" :"BTC-USDT" }}
{"requestId" : "1" , "subscribeMarketCandlesRequest" :{"market" :"BTC-USDT" , "period" : "MIN5" , "limit" : "20" }}
Name Description Example Require
market id of market BTC-USDT true period time period MIN5 true limit expect count of candles snapshot 20 false
Symbol Description
MIN1 1 minute MIN5 5 minutes MIN15 15 minutes MIN30 30 minutes HOUR1 1 hour HOUR3 3 hours HOUR4 4 hours HOUR6 6 hours HOUR12 12 hours DAY1 1 day WEEK1 1 week
{
"requestId" :"1" ,
"candlesSnapshot" :{
"candles" :[
{
"market" :"BTC-USDT" ,
"time" :"2018-09-12T13:40:00Z" ,
"open" :"9.0" ,
"high" :"9.0" ,
"low" :"9.0" ,
"close" :"9.0" ,
"period" :"MIN5"
}
]
}
}
{
"requestId" :"1" ,
"candleUpdate" :{
"candle" :{
"market" :"BTC-USDT" ,
"time" :"2018-09-12T05:30:00Z" ,
"open" :"9" ,
"high" :"9" ,
"low" :"9" ,
"close" :"9" ,
"period" :"MIN5"
}
}
}
Name Description Example
market id of market BTC-USDT time utc time of candle 2018-09-12T13:40:00Z open first price in this period 9.0 high highest price in this period 9.0 low lowest price in this period 9.0 close last price in this period 9.0 period time period MIN5
{"requestId" : "1" , "unsubscribeMarketCandlesRequest" :{"market" :"BTC-USDT" , "period" : "MIN5" }}
{"requestId" : "1" , "subscribeMarketsTickerRequest" :{"markets" :["BTC-USDT" , "ONE-BTC" ]}}
Name Description Example Require
requestId id of request 1 true markets list of market id ["BTC-USDT"] true
{
"requestId" :"1" ,
"tickersSnapshot" :{
"tickers" :[
{
"market" :"ETH-USDT" ,
"ask" :{
"price" :"197.96" ,
"amount" :"5.0" ,
"orderCount" :"1"
},
"bid" :{
"price" :"159.99" ,
"amount" :"1.07552" ,
"orderCount" :"1"
},
"open" :"197.46" ,
"high" :"0.0" ,
"low" :"0.0" ,
"close" :"213.96" ,
"volume" :"0.0"
}
]
}
}
{
"requestId" :"1" ,
"tickerUpdate" :{
"ticker" :{
"market" :"ETH-USDT" ,
"ask" :{
"price" :"197.96" ,
"amount" :"5.0" ,
"orderCount" :"1"
},
"bid" :{
"price" :"159.99" ,
"amount" :"1.07552" ,
"orderCount" :"1"
},
"open" :"197.46" ,
"high" :"220.0" ,
"low" :"190.0" ,
"close" :"213.96" ,
"volume" :"1000.0"
}
}
}
Name Description Example
market id of market BTC-USDT ask first ask PriceLevel bid first bid PriceLevel open first price in 24hrs 10.24 high highest price in 24hrs 10.24 low lowest price in 24hrs 10.24 close last price in 24hrs 10.24 volume total volume in 24hrs 10.24
{"requestId" : "1" , "unsubscribeMarketsTickerRequest" :{"markets" :["BTC-USDT" , "ONE-BTC" ]}}
{"requestId" : "1" , "subscribeMarketTradesRequest" :{"market" :"BTC-USDT" , "limit" : "20" }}
Name Description Example Require
requestId id of request 1 true market id of market BTC-USDT true limit expect count of trades snapshot 20 false
Note: The takerOrder and makerOrder fields are always null.
{
"requestId" :"1" ,
"tradesSnapshot" :{
"trades" :[
{
"id" :"28622" ,
"price" :"9.0" ,
"amount" :"10000.0" ,
"market" :"BTC-USDT" ,
"createdAt" :"2018-09-12T09:52:37Z" ,
"makerOrder" :null ,
"takerOrder" :null ,
"takerSide" :"BID"
}
]
}
}
Note: The takerOrder and makerOrder fields are always null.
{
"requestId" :"1" ,
"tradeUpdate" :{
"trade" :{
"id" :"28622" ,
"price" :"9.0" ,
"amount" :"10000.0" ,
"market" :"BTC-USDT" ,
"createdAt" :"2018-09-12T09:52:37Z" ,
"makerOrder" :null ,
"takerOrder" :{
"id" :"" ,
"price" :"" ,
"stopPrice" :"" ,
"amount" :"" ,
"market" :"" ,
"side" :"BID" ,
"state" :"PENDING" ,
"filledAmount" :"" ,
"filledFees" :"" ,
"avgDealPrice" :"" ,
"createdAt" :null ,
"updatedAt" :null ,
"businessUnit" :"SPOT" ,
"type" :"LIMIT" ,
"operator" :"LTE" ,
"ioc" :false
},
"takerSide" :"BID"
}
}
}
Name Description Example
id id of trade 1 price price of trade 9.0 amount amount of trade 1000.0 market id of market BTC-USDT createdAt create time of trade 2018-09-12T09:52:37Z makerOrder order of maker takerOrder order of taker
Name Description Example
id id of order 1 price price of order 10.24 stopPrice stop price of order 10.24 amount amount of order 1000.0 market id of market BTC-USDT side order side ASK state order state FILLED filledAmount filled amount 1000.0 filledFees filled fees 90.0 avgDealPrice average deal price of order 9.0 createdAt create time of order 2018-09-12T09:52:36Z updatedAt update time of order 2018-09-12T09:52:36Z
{"requestId" : "1" , "unsubscribeMarketTradesRequest" :{"market" :"BTC-USDT" }}
{"requestId" : "1" , "subscribeViewerAccountsRequest" :{}}
{
"requestId" :"1" ,
"accountsSnapshot" :{
"accounts" :[
{
"asset" :"BTC" ,
"balance" :"10.0" ,
"lockedBalance" :"0.0"
}
]
}
}
{
"requestId" :"1" ,
"accountUpdate" :{
"account" :{
"asset" :"BTC" ,
"balance" :"0.0" ,
"lockedBalance" :"0.0"
}
}
}
Name Description Example
asset asset of account BTC balance balance of account 10.0 lockedBalance locked balance of account 10.0
{"requestId" : "1" , "unsubscribeViewerAccountsRequest" :{}}
{"requestId" : "1" , "subscribeViewerOrdersRequest" :{"market" :"BTC-USDT" }}
Name Description Example Require
market id of market BTC-USDT true
{
"requestId" :"1" ,
"ordersSnapshot" :{
"orders" :[
{
"id" :"42844576" ,
"price" :"9.0" ,
"stopPrice" :"0.0" ,
"amount" :"10000.0" ,
"market" :"BTC-USDT" ,
"side" :"ASK" ,
"state" :"FILLED" ,
"filledAmount" :"10000.0" ,
"filledFees" :"90.0" ,
"avgDealPrice" :"9.0" ,
"createdAt" :"2018-09-12T09:52:36Z" ,
"updatedAt" :"2018-09-12T09:52:37Z"
}
]
}
}
{
"requestId" :"1" ,
"orderUpdate" :{
"order" :{
"id" :"42844576" ,
"price" :"9.0" ,
"stopPrice" :"0.0" ,
"amount" :"10000.0" ,
"market" :"BTC-USDT" ,
"side" :"ASK" ,
"state" :"FILLED" ,
"filledAmount" :"10000.0" ,
"filledFees" :"90.0" ,
"avgDealPrice" :"9.0" ,
"createdAt" :"2018-09-12T09:52:36Z" ,
"updatedAt" :"2018-09-12T09:52:37Z"
}
}
}
Name Description Example
id id of order 1 price price of order 10.24 stopPrice stop price of order 10.24 amount amount of order 1000.0 market id of market BTC-USDT side order side ASK state order state FILLED filledAmount filled amount 1000.0 filledFees filled fees 90.0 avgDealPrice average deal price of order 9.0 createdAt create time of order 2018-09-12T09:52:36Z updatedAt update time of order 2018-09-12T09:52:36Z
{"requestId" : "1" , "unsubscribeViewerOrdersRequest" :{"market" :"BTC-USDT" }}
will not return snapshot, only push order update response
{"requestId" : "1" , "subscribeAllViewerOrdersRequest" :{}}
{"requestId" : "1" , "unsubscribeAllViewerOrdersRequest" :{}}
