WebSocket(Alpha) · BigONE Developer API

WebSocket API provide the quasi real-time market transaction data.

【DISCLAIMER】 The WebSocket API is still in Alpha stage. BigONE cannot guarantee the availability, validity and correctness of it. You have to know clearly that you have to take the risk on your own. The risks include but not limited to the program bugs, errors and insecurity. When you use this API means that you agreed with this disclaimer and considered yourself have the ability to take the risks and you're responsible for this behavior. Our company is responsible for interpreting this document. The relevant laws and regulations of the state should be the standard if there are divergence in this declaration.

API Endpoint

Notice

You need to authenticate customer before subscribe viewer orders or accounts
And set WebSocket's subprotocol as json

Sec-WebSocket-Protocol: json

requestId: requestId is the identification for the API request. The API Responses will carry the requestId for you to know the response corresponds to which request. So you should use unique requestId in different requests.

AuthenticateCustomer

{"requestId":"1", "authenticateCustomerRequest":{"token":"Bearer xxx.xxx.xxx"}}

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true
token	open api token of customer	Bearer xxx.xxx.xxx	true

Market Depth

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

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true
market	id of market	BTC-USDT	true

Example of depth snapshot response

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

Example of depth update response

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

depth

Name	Description	Example
market	id of market	BTC-USDT
asks	list of depth ask
bids	list of depth bid

ask / bid

Name	Description	Example
price	ask price	197.96
amount	ask amount	5.0
orderCount	ask order count	1

unsubscribe

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

Market Candle

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

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true
market	id of market	BTC-USDT	true
period	symbol of candle period	MIN5	true
limit	expect count of candles snapshot	20	false

period

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

Example of candles snapshot response

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

Example of candle update response

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

candle

Name	Description	Example
market	id of market	BTC-USDT
time	utc time of candle	2018-09-12T13:40:00Z
open	open of candle	9.0
high	high of candle	9.0
low	low of candle	9.0
close	close of candle	9.0
period	symbol of candle period	MIN5

unsubscribe

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

Market Ticker

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

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true
markets	list of market id	["BTC-USDT"]	true

Example of tickers snapshot response

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

Example of ticker update response

{
    "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":"0.0",
            "low":"0.0",
            "close":"213.96",
            "volume":"0.0"
        }
    }
}

ticker

Name	Description	Example
market	id of market	BTC-USDT
ask	ticker ask
bid	ticker bid
open	open of ticker	10.24
high	high of ticker	10.24
low	low of ticker	10.24
close	close of ticker	10.24
volume	volume of ticker	10.24

ask / bid

Name	Description	Example
price	ask price	197.96
amount	ask amount	5.0
orderCount	ask order count	1

unsubscribe

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

Market Trade

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

Request Parameters

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

Example of trades snapshot Response，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"
            }
        ]
    }
}

Example of trades update Response, Note: makerOrder field is always null; takerOrder field is always not null and only 'side' is real data.

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

Response Parameters

trade

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

makerOrder / takerOrder

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

unsubscribe

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

User Account

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

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true

Example of accounts snapshot response

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

Example of user accounts update response

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

account

Name	Description	Example
asset	asset of account	BTC
balance	balance of account	10.0
lockedBalance	locked balance of account	10.0

unsubscribe

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

User Order

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

Request Parameters

Name	Description	Example	Require
requestId	id of request	1	true
market	id of market	BTC-USDT	true

Example of user orders snapshot response

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

Example of user order update response

{
    "requestId":"1",
    "orderUpdate":{
        "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

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

unsubscribe

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

Response

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

Response of authenticate customer success

{"requestId":"1","success":{"ok":true}}

Response with error

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

error code

code	type
45000	grpc error
45001	login status error
other	default error