Skip to main content

WebSocket

Endpoint​

wss://big.one/ws/v2

Authenticate​

You need to authenticate customer before subscribe private data, like Order, Account etc.

Protocol​

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.

How to set the Websocket Protocol​

Set the request header Sec-WebSocket-Protocol to proto or json.

We recommand the proto format, and the proto file is here

RequestId​

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.

Response​

After successfully subscribing, the API will return the snapshot data first, then the update data if the subscription generates new data.

Error Response​
{
    "requestId":"1",
    "error":{
        "code":45000,
        "message":"GRPC error: xxx"
    }
}

KeepAlive​

Developers can use the Ping/Pong frame to keep the connection alive. Also we have priovid a HeartBeat message.

error code​
codetype
45000grpc error
45001login status error
otherdefault error

Supported Methods

AuthenticateCustomer​

{"requestId":"1", "authenticateCustomerRequest":{"token":"Bearer {YOUR_TOKEN}"}}

Parameters​

NameDescriptionExampleRequire
marketid of marketBTC-USDTtrue

Market Depth​

Subscribe​

{"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.

Response​

Snapshot 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"
    }
}

Update Data​

{
    "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"
    }
}

Depth​

NametypeDescriptionExample
marketStringmarket symbolBTC-USDT
asksPriceLevelAsk side (Sell side)
bidsPriceLevelBid side (Buy side)
changeIdStringCurrent change ID of this market
prevIdStringLast change ID of this marketchangeId and prevId are always sequential numbers. Developers can determine the accuracy of their local Depth data by comparing the values of changeId and prevId.

PriceLevel​

NametypeDescriptionExample
priceStringask price197.96
amountStringask amount5.0
orderCountIntask order count1

Unsubscribe​

{"requestId": "1", "unsubscribeMarketDepthRequest":{"market":"BTC-USDT"}}

Market Candle​

Subscribe​

{"requestId": "1", "subscribeMarketCandlesRequest":{"market":"BTC-USDT", "period": "MIN5", "limit": "20"}}

Parameters​

NameDescriptionExampleRequire
marketid of marketBTC-USDTtrue
periodtime periodMIN5true
limitexpect count of candles snapshot20false

Period​

SymbolDescription
MIN11 minute
MIN55 minutes
MIN1515 minutes
MIN3030 minutes
HOUR11 hour
HOUR33 hours
HOUR44 hours
HOUR66 hours
HOUR1212 hours
DAY11 day
WEEK11 week

Snapshot Data​

{
    "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"
            }
        ]
    }
}

Update Data​

{
    "requestId":"1",
    "candleUpdate":{
        "candle":{
            "market":"BTC-USDT",
            "time":"2018-09-12T05:30:00Z",
            "open":"9",
            "high":"9",
            "low":"9",
            "close":"9",
            "period":"MIN5"
        }
    }
}

Candle​

NameDescriptionExample
marketid of marketBTC-USDT
timeutc time of candle2018-09-12T13:40:00Z
openfirst price in this period9.0
highhighest price in this period9.0
lowlowest price in this period9.0
closelast price in this period9.0
periodtime periodMIN5

Unsubscribe​

{"requestId": "1", "unsubscribeMarketCandlesRequest":{"market":"BTC-USDT", "period": "MIN5"}}

Market Ticker​

Subscribe​

{"requestId": "1", "subscribeMarketsTickerRequest":{"markets":["BTC-USDT", "ONE-BTC"]}}

Parameters​

NameDescriptionExampleRequire
requestIdid of request1true
marketslist of market id["BTC-USDT"]true

Snapshot Data​

{
    "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"
            }
        ]
    }
}

Update Data​

{
    "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"
        }
    }
}

Ticker​

NameDescriptionExample
marketid of marketBTC-USDT
askfirst ask PriceLevel
bidfirst bid PriceLevel
openfirst price in 24hrs10.24
highhighest price in 24hrs10.24
lowlowest price in 24hrs10.24
closelast price in 24hrs10.24
volumetotal volume in 24hrs10.24

Unsubscribe​

{"requestId": "1", "unsubscribeMarketsTickerRequest":{"markets":["BTC-USDT", "ONE-BTC"]}}

Market Trade​

Subscribe​

{"requestId": "1", "subscribeMarketTradesRequest":{"market":"BTC-USDT", "limit": "20"}}

Parameters​

NameDescriptionExampleRequire
requestIdid of request1true
marketid of marketBTC-USDTtrue
limitexpect count of trades snapshot20false

Snapshot Data​

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"
            }
        ]
    }
}

Update Data​

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"
        }
    }
}

Trade​

NameDescriptionExample
idid of trade1
priceprice of trade9.0
amountamount of trade1000.0
marketid of marketBTC-USDT
createdAtcreate time of trade2018-09-12T09:52:37Z
makerOrderorder of maker
takerOrderorder of taker

Order​

NameDescriptionExample
idid of order1
priceprice of order10.24
stopPricestop price of order10.24
amountamount of order1000.0
marketid of marketBTC-USDT
sideorder sideASK
stateorder stateFILLED
filledAmountfilled amount1000.0
filledFeesfilled fees90.0
avgDealPriceaverage deal price of order9.0
createdAtcreate time of order2018-09-12T09:52:36Z
updatedAtupdate time of order2018-09-12T09:52:36Z

Unsubscribe​

{"requestId": "1", "unsubscribeMarketTradesRequest":{"market":"BTC-USDT"}}

User Account​

Subscribe​

{"requestId": "1", "subscribeViewerAccountsRequest":{}}

Snapshot Data​

{
    "requestId":"1",
    "accountsSnapshot":{
        "accounts":[
            {
                "asset":"BTC",
                "balance":"10.0",
                "lockedBalance":"0.0"
            }
        ]
    }
}

Update Data​

{
    "requestId":"1",
    "accountUpdate":{
        "account":{
            "asset":"BTC",
            "balance":"0.0",
            "lockedBalance":"0.0"
        }
    }
}

Account​

NameDescriptionExample
assetasset of accountBTC
balancebalance of account10.0
lockedBalancelocked balance of account10.0

Unsubscribe​

{"requestId": "1", "unsubscribeViewerAccountsRequest":{}}

User Order​

Subscribe one market's orders​

{"requestId": "1", "subscribeViewerOrdersRequest":{"market":"BTC-USDT"}}

Parameters​

NameDescriptionExampleRequire
marketid of marketBTC-USDTtrue

Snapshot Data​

{
    "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"
            }
        ]
    }
}

Update Data​

{
    "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"
        }
    }
}

Order​

NameDescriptionExample
idid of order1
priceprice of order10.24
stopPricestop price of order10.24
amountamount of order1000.0
marketid of marketBTC-USDT
sideorder sideASK
stateorder stateFILLED
filledAmountfilled amount1000.0
filledFeesfilled fees90.0
avgDealPriceaverage deal price of order9.0
createdAtcreate time of order2018-09-12T09:52:36Z
updatedAtupdate time of order2018-09-12T09:52:36Z

Unsubscribe​

{"requestId": "1", "unsubscribeViewerOrdersRequest":{"market":"BTC-USDT"}}

Subscribe all market's orders​

will not return snapshot, only push order update response

{"requestId": "1", "subscribeAllViewerOrdersRequest":{}}

Unsubscribe​

{"requestId": "1", "unsubscribeAllViewerOrdersRequest":{}}