Docbox

API Document Description

General API Information

Some endpoints will require an API Key.
The base endpoint is: https://www.tokocrypto.com
Some specified APIs another base endpoint is: https://api.binance.com
All endpoints return a JSON object.
Data is returned in ascending order. Oldest first, newest last.
All time and timestamp related fields are in milliseconds.

HTTP Return Codes

HTTP 4XX return codes are used for malformed requests; the issue is on the sender's side.
HTTP 403 return code is used when the WAF Limit (Web Application Firewall) has been violated.
HTTP 429 return code is used when breaking a request rate limit.
HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.
HTTP 5XX return codes are used for internal errors; the issue is on Server's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

Response fields description

Name	Type	Mandatory	Description
code	Number	Yes	Error Code，0 is success，else is fail
msg	String	Yes	error message
timestamp	Number	Yes	server timestamp
data	Object	No	response data

General Information on Endpoints

For GET endpoints, parameters must be sent as a query string.
For POST endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.
Parameters may be sent in any order.
If a parameter sent in both the query string and request body, the body string parameter will be used.

LIMITS

General Info on Limits

The following intervalLetter values for headers:
- SECOND => S
- MINUTE => M
- HOUR => H
- DAY => D
intervalNum describes the amount of the interval. For example, intervalNum 5 with intervalLetter M means "Every 5 minutes".
A 429 will be returned when either rate limit is violated.

IP Limits

Every request will contain X-MBX-USED-WEIGHT-(intervalNum)(intervalLetter) in the response headers which has the current used weight for the IP for all request rate limiters defined.
Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.
When a 429 is received, it's your obligation as an API to back off and not spam the API.
Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (HTTP status 418).
IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.
A Retry-After header is sent with a 418 or 429 responses and will give the number of seconds required to wait, in the case of a 418, to prevent a ban, or, in the case of a 429, until the ban is over.
The limits on the API are based on the IPs, not the API keys.

We recommend using the websocket for getting data as much as possible, as this will not count to the request rate limit.

Order Rate Limits

Every successful order response will contain a X-MBX-ORDER-COUNT-(intervalNum)(intervalLetter) header which has the current order count for the account for all order rate limiters defined.
Rejected/unsuccessful orders are not guaranteed to have X-MBX-ORDER-COUNT-** headers in the response.
The order rate limit is counted against each account.

Endpoint security type

Each endpoint has a security type that determines the how you will interact with it. This is stated next to the NAME of the endpoint.
- If no security type is stated, assume the security type is NONE.
API-keys are passed into the Rest API via the X-MBX-APIKEY header.
API-keys and secret-keys are case sensitive.
API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for SIGNED only, while another API-key can access everything except for SIGNED routes.
By default, API-keys can access all secure routes.

Security Type	Description
NONE	Endpoint can be accessed freely.
SIGNED	Endpoint requires sending a valid API-Key and signature.
API_KEY	Endpoint requires sending a valid API-Key.

SIGNED Endpoint security

SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.
Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.
The signature is not case sensitive.
totalParams is defined as the query string concatenated with the request body.

Timing security

A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.
An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.
The logic is as follows:
```
if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow)
 {
   // process request
 } 
 else 
 {
   // reject request
 }
```
Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

It is recommended to use a small recvWindow of 5000 or less! The max cannot go beyond 60,000!

SIGNED Endpoint Examples for POST /open/v1/orders

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key	Value
apiKey	cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV
secretKey	f9AbA6a8AD6bC2a97294a212244dda04ETfl0kc4BSUGOtL7m7rNELpt3Jh25SiP

Parameter	Value
symbol	BTC_USDT
side	0
type	1
quantity	'0.16'
price	'7500'
recvWindow	5000
timestamp	1581720670624

Example 1: As a request body

requestBody: symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000

HMAC SHA256 signature:

[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa

curl command:

(HMAC SHA256)
[linux]$  curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders' -d 'symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000&signature=33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa'

Example 2: As a query string

queryString: symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000

HMAC SHA256 signature:

[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders?symbol=BTC_USDT&side=0&type=1&quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000&signature=33824b5160daefc34257ab9cd3c3db7a0158a446674f896c9fc3b122ae656bfa'

Example 3: Mixed query string and request body

queryString: symbol=BTC_USDT&side=0&type=1
requestBody: quantity=1&price=0.1&recvWindow=5000×tamp=1499827319559
requestBody: symbol=BTC_USDT&side=0&type=1quantity=0.16&price=7500×tamp=1581720670624&recvWindow=5000

HMAC SHA256 signature:

[linux]$ echo -n "symbol=BTC_USDT&side=0&type=1quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000" | openssl dgst -sha256 -hmac "cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV"
(stdin)= 27dbb813ab6ee7ef61902f88f1a0a6cd4daca0503a5195dbdd3174f49a61ad79

curl command:

(HMAC SHA256)
[linux]$ curl -H "X-MBX-APIKEY: cfDC92B191b9B3Ca3D842Ae0e01108CBKI6BqEW6xr4NrPus3hoZ9Ze9YrmWwPFV" -X POST 'https://www.tokocrypto.com/open/v1/orders?symbol=BTC_USDT&side=0&type=1' -d 'quantity=0.16&price=7500&timestamp=1581720670624&recvWindow=5000&signature=27dbb813ab6ee7ef61902f88f1a0a6cd4daca0503a5195dbdd3174f49a61ad79'

Note that the signature is different in example 3. There is no & between "1" and "quantity=1".

Public API Definitions

Terminology

base asset refers to the asset that is the quantity of a symbol.
quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Symbol type:

1 MAIN
2 NEXT

Order status (status):

-2 SYSTEM_PROCESSING
0 NEW
1 PARTIALLY_FILLED
2 FILLED
3 CANCELED
4 PENDING_CANCEL (currently unused)
5 REJECTED
6 EXPIRED

Order types (orderTypes, type):

1 LIMIT
2 MARKET
3 STOP_LOSS
4 STOP_LOSS_LIMIT
5 TAKE_PROFIT
6 TAKE_PROFIT_LIMIT
7 LIMIT_MAKER

Order side (side):

0 BUY
1 SELL

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

Filters

Filters define trading rules on a symbol or an exchange. Filters come in two forms: symbol filters and exchange filters.

Symbol Filters

The PRICE_FILTER defines the price rules for a symbol. There are 3 parts:

minPrice defines the minimum price/stopPrice allowed; disabled on minPrice == 0.
maxPrice defines the maximum price/stopPrice allowed; disabled on maxPrice == 0.
tickSize defines the intervals that a price/stopPrice can be increased/decreased by; disabled on tickSize == 0.

Any of the above variables can be set to 0, which disables that rule in the price filter. In order to pass the price filter, the following must be true for price/stopPrice of the enabled rules:

price >= minPrice
price <= maxPrice
(price-minPrice) % tickSize == 0

/exchangeInfo format:

{
  "filterType": "PRICE_FILTER",
  "minPrice": "0.00000100",
  "maxPrice": "100000.00000000",
  "tickSize": "0.00000100"
}

PERCENT_PRICE

The PERCENT_PRICE filter defines valid range for a price based on the average of the previous trades. avgPriceMins is the number of minutes the average price is calculated over. 0 means the last price is used.

In order to pass the percent price, the following must be true for price:

price <= weightedAveragePrice * multiplierUp
price >= weightedAveragePrice * multiplierDown

/exchangeInfo format:

{
  "filterType": "PERCENT_PRICE",
  "multiplierUp": "1.3000",
  "multiplierDown": "0.7000",
  "avgPriceMins": 5
}

LOT_SIZE

The LOT_SIZE filter defines the quantity (aka "lots" in auction terms) rules for a symbol. There are 3 parts:

minQty defines the minimum quantity/icebergQty allowed.
maxQty defines the maximum quantity/icebergQty allowed.
stepSize defines the intervals that a quantity/icebergQty can be increased/decreased by.

In order to pass the lot size, the following must be true for quantity/icebergQty:

quantity >= minQty
quantity <= maxQty
(quantity-minQty) % stepSize == 0

/exchangeInfo format:

{
  "filterType": "LOT_SIZE",
  "minQty": "0.00100000",
  "maxQty": "100000.00000000",
  "stepSize": "0.00100000"
}

MIN_NOTIONAL

The MIN_NOTIONAL filter defines the minimum notional value allowed for an order on a symbol. An order's notional value is the price * quantity. applyToMarket determines whether or not the MIN_NOTIONAL filter will also be applied to MARKET orders. Since MARKET orders have no price, the average price is used over the last avgPriceMins minutes. avgPriceMins is the number of minutes the average price is calculated over. 0 means the last price is used.

/exchangeInfo format:

{
  "filterType": "MIN_NOTIONAL",
  "minNotional": "0.00100000",
  "applyToMarket": true,
  "avgPriceMins": 5
}

ICEBERG_PARTS

The ICEBERG_PARTS filter defines the maximum parts an iceberg order can have. The number of ICEBERG_PARTS is defined as CEIL(qty / icebergQty).

/exchangeInfo format:

{
  "filterType": "ICEBERG_PARTS",
  "limit": 10
}

MARKET_LOT_SIZE

The MARKET_LOT_SIZE filter defines the quantity (aka "lots" in auction terms) rules for MARKET orders on a symbol. There are 3 parts:

minQty defines the minimum quantity allowed.
maxQty defines the maximum quantity allowed.
stepSize defines the intervals that a quantity can be increased/decreased by.

In order to pass the market lot size, the following must be true for quantity:

quantity >= minQty
quantity <= maxQty
(quantity-minQty) % stepSize == 0

/exchangeInfo format:

{
  "filterType": "MARKET_LOT_SIZE",
  "minQty": "0.00100000",
  "maxQty": "100000.00000000",
  "stepSize": "0.00100000"
}

MAX_NUM_ORDERS

The MAX_NUM_ORDERS filter defines the maximum number of orders an account is allowed to have open on a symbol. Note that both "algo" orders and normal orders are counted for this filter.

/exchangeInfo format:

{
  "filterType": "MAX_NUM_ORDERS",
  "limit": 25
}

MAX_NUM_ALGO_ORDERS

The MAX_NUM_ALGO_ORDERS filter defines the maximum number of "algo" orders an account is allowed to have open on a symbol. "Algo" orders are STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.

/exchangeInfo format:

{
  "filterType": "MAX_NUM_ALGO_ORDERS",
  "maxNumAlgoOrders": 5
}

MAX_NUM_ICEBERG_ORDERS

The MAX_NUM_ICEBERG_ORDERS filter defines the maximum number of ICEBERG orders an account is allowed to have open on a symbol. An ICEBERG order is any order where the icebergQty is > 0.

/exchangeInfo format:

{
  "filterType": "MAX_NUM_ICEBERG_ORDERS",
  "maxNumIcebergOrders": 5
}

Exchange Filters

EXCHANGE_MAX_NUM_ORDERS

The MAX_NUM_ORDERS filter defines the maximum number of orders an account is allowed to have open on the exchange. Note that both "algo" orders and normal orders are counted for this filter.

/exchangeInfo format:

{
  "filterType": "EXCHANGE_MAX_NUM_ORDERS",
  "maxNumOrders": 1000
}

EXCHANGE_MAX_NUM_ALGO_ORDERS

The MAX_ALGO_ORDERS filter defines the maximum number of "algo" orders an account is allowed to have open on the exchange. "Algo" orders are STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.

/exchangeInfo format:

{
  "filterType": "EXCHANGE_MAX_ALGO_ORDERS",
  "maxNumAlgoOrders": 200
}

General endpoints

Check server time

GET /open/v1/common/time

Test connectivity to the Rest API and get the current server time.

Parameters: NONE

Response:

{
    "code": 0,
    "msg": "success",
    "timestamp": 1572265137927
}

Get all Supported Trading Symbol

GET /open/v1/common/symbols

This endpoint returns all Exchange's supported trading symbol.

Parameters: NONE

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "type": 1, // 1 - Main, 2 - Next.
                "symbol": "ADA_BNB",
                "baseAsset": "ADA",
                "basePrecision": 8,
                "quoteAsset": "BNB",
                "quotePrecision": 8,
                "filters": [
                    {
                        "applyToMarket": false,
                        "filterType": "PRICE_FILTER",
                        "maxPrice": "1000.00000000",
                        "minPrice": "0.00000100",
                        "tickSize": "0.00000100"
                    },
                    {
                        "applyToMarket": false,
                        "avgPriceMins": "5",
                        "filterType": "PERCENT_PRICE",
                        "multiplierDown": 0.2,
                        "multiplierUp": 5
                    },
                    {
                        "applyToMarket": false,
                        "filterType": "LOT_SIZE",
                        "maxQty": "9000000.00000000",
                        "minQty": "1.00000000",
                        "stepSize": "1.00000000"
                    },
                    {
                        "applyToMarket": true,
                        "avgPriceMins": "5",
                        "filterType": "MIN_NOTIONAL",
                        "minNotional": "0.10000000"
                    },
                    {
                        "applyToMarket": false,
                        "filterType": "ICEBERG_PARTS",
                        "limit": "10"
                    },
                    {
                        "applyToMarket": false,
                        "filterType": "MARKET_LOT_SIZE",
                        "maxQty": "4526300.00000000",
                        "minQty": "0.00000000",
                        "stepSize": "0.00000000"
                    },
                    {
                        "applyToMarket": false,
                        "filterType": "MAX_NUM_ALGO_ORDERS",
                        "maxNumAlgoOrders": "5"
                    }
                ],
                "orderTypes": [
                    "LIMIT",
                    "LIMIT_MAKER",
                    "MARKET",
                    "STOP_LOSS_LIMIT",
                    "TAKE_PROFIT_LIMIT"
                ],
                "icebergEnable": 1,
                "ocoEnable": 1,
                "spotTradingEnable": 1,
                "marginTradingEnable": 0
            }
          ]
    },
    "timestamp": 1571921637091
}

Market Data endpoints

Order book

GET https://api.binance.com/api/v3/depth (when symbol type is 1)
GET /open/v1/market/depth (when symbol type is not 1)

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES	when symbol type is 1, replace _ of symbol with null string
limit	INT	NO	Default 100; max 5000. Valid limits:[5, 10, 20, 50, 100, 500]

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
      "lastUpdateId": 1027024,
      "bids": [
            [
              "4.00000000",     // 价位
              "431.00000000",   // 挂单量
            ]
          ],
          "asks": [
            [
              "4.00000200",
              "12.00000000",
            ]
          ]
    },
    "timestamp": 1571921637091
}

Recent trades list

GET https://api.binance.com/api/v3/trades (when symbol type is 1)
GET /open/v1/market/trades (when symbol type is not 1)

Get recent trades (up to last 500).

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES	when symbol type is 1, replace _ of symbol with null string
fromId	LONG	NO	ID to get trades from INCLUSIVE.
limit	INT	NO	Default 500; max 1000.

Response:

{
    "code": 0,
    "msg": "success",
    "data": [
        {
          "id": 28457,
          "price": "4.00000100",
          "qty": "12.00000000",
          "time": 1499865549590,
          "isBuyerMaker": true,
          "isBestMatch": true
        }
    ],
    "timestamp": 1571921637091
}

Compressed/Aggregate trades list

GET https://api.binance.com/api/v3/aggTrades (when symbol type is 1)
GET /open/v1/market/agg-trades (when symbol type is not 1)

Get compressed, aggregate trades. Trades that fill at the time, from the same order, with the same price will have the quantity aggregated.

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES	when symbol type is 1, replace _ of symbol with null string
fromId	LONG	NO	ID to get aggregate trades from INCLUSIVE.
startTime	LONG	NO	Timestamp in ms to get aggregate trades from INCLUSIVE.
endTime	LONG	NO	Timestamp in ms to get aggregate trades until INCLUSIVE.
limit	INT	NO	Default 500; max 1000.

If fromId, startTime, and endTime are not sent, the most recent aggregate trades will be returned.

Response:

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "a": 26129,         // Aggregate tradeId
            "p": "0.01633102",  // Price
            "q": "4.70443515",  // Quantity
            "f": 27781,         // First tradeId
            "l": 27781,         // Last tradeId
            "T": 1498793709153, // Timestamp
            "m": true,          // Was the buyer the maker?
            "M": true           // Was the trade the best price match?
        }
    ],
    "timestamp": 1571921637091
}

Kline/Candlestick data

GET https://api.binance.com/api/v1/klines (when symbol type is 1)
GET /open/v1/market/klines (when symbol type is not 1)

Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES	when symbol type is 1, replace _ of symbol with null string
interval	ENUM	YES
startTime	LONG	NO
endTime	LONG	NO
limit	INT	NO	Default 500; max 1000.

If startTime and endTime are not sent, the most recent klines are returned.

Response:

 {
    "code": 0,
    "msg": "success",
    "data": [
        [
          1499040000000,      // Open time
          "0.01634790",       // Open
          "0.80000000",       // High
          "0.01575800",       // Low
          "0.01577100",       // Close
          "148976.11427815",  // Volume
          1499644799999,      // Close time
          "2434.19055334",    // Quote asset volume
          308,                // Number of trades
          "1756.87402397",    // Taker buy base asset volume
          "28.46694368",      // Taker buy quote asset volume
          "17928899.62484339" // Ignore.
        ]
    ],
    "timestamp": 1571921637091
}

Account endpoints

New order (SIGNED)

POST /open/v1/orders  (HMAC SHA256)

Send in a new order.

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
side	ENUM	YES	0,1
type	ENUM	YES	1,2,4,6
quantity	STRING	NO
quoteOrderQty	STRING	NO
price	STRING	NO
clientId	STRING	NO	Client's custom ID for the order, Server does not check it's uniqueness. Automatically generated if not sent.
stopPrice	STRING	NO	Used with `STOP_LOSS`, `STOP_LOSS_LIMIT`, `TAKE_PROFIT`, and `TAKE_PROFIT_LIMIT` orders.
icebergQty	STRING	NO	Used with `LIMIT`, `STOP_LOSS_LIMIT`, and `TAKE_PROFIT_LIMIT` to create an iceberg order.
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Additional mandatory parameters based on type:

Type	Additional mandatory parameters
`1`	`quantity`, `price`
`2`	`quantity` (sell) or `quoteOrderQty` (buy)
`3`	`quantity`, `stopPrice`
`4`	`quantity`, `price`, `stopPrice`
`5`	`quantity`, `stopPrice`
`6`	`quantity`, `price`, `stopPrice`
`7`	`quantity`, `price`

Other info:

LIMIT_MAKER are LIMIT orders that will be rejected if they would immediately match and trade as a taker.
STOP_LOSS and TAKE_PROFIT will execute a MARKET order when the stopPrice is reached.
Any LIMIT or LIMIT_MAKER type order can be made an iceberg order by sending an icebergQty.
Any order with an icebergQty MUST have timeInForce set to GTC.
MARKET orders using quantity specifies how much a user wants to buy or sell based on the market price.
MARKET orders using quoteOrderQty specifies the amount the user wants to spend (when buying) of the quote asset; the correct quantity will be determined based on the market liquidity and quoteOrderQty.
MARKET orders using quoteOrderQty will not break LOT_SIZE filter rules; the order will execute a quantity that will have the notional value as close as possible to quoteOrderQty.

Trigger order price rules against market price for both MARKET and LIMIT versions:

Price above market price: STOP_LOSS BUY, TAKE_PROFIT SELL
Price below market price: STOP_LOSS SELL, TAKE_PROFIT BUY

Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "4",
        "createTime": 1550130502385
    },
    "timestamp": 1550130502489
}

Query order (SIGNED)

GET /open/v1/orders/detail (HMAC SHA256)

Check an order's status.

Parameters:

Name	Type	Mandatory	Description
orderId	LONG	YES
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": 4,
        "orderListId": -1 //Unless part of an OCO, the value will always be -1.
        "clientId": "myOrder1",
        "symbol": "BTC_USDT",
        "side": 1,
        "type": 1,
        "price": 1,
        "status": 0,
        "origQty": 10.88,
        "origQuoteQty": 0,
        "executedQty": 0,
        "executedPrice": 0,
        "executedQuoteQty": 0,
        "createTime": 1550130502000
    },
    "timestamp": 1550130554182
}

Cancel order (SIGNED)

POST /open/v1/orders/cancel  (HMAC SHA256)

Cancel an active order.

Parameters:

Name	Type	Mandatory	Description
orderId	LONG	YES
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": 4,
        "orderListId": -1 // Unless part of an OCO, the value will always be -1.
        "clientId": "myOrder1",
        "symbol": "BTC_USDT",
        "side": 1,
        "type": 1,
        "price": 1,
        "status": 0,
        "origQty": 10.88,
        "origQuoteQty": 0,
        "executedQty": 0,
        "executedPrice": 0,
        "executedQuoteQty": 0,
        "createTime": 1550130502000
    },
    "timestamp": 1550130554182
}

All orders (SIGNED)

GET /open/v1/orders (HMAC SHA256)

Get all account orders; active, canceled, or filled.

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
type	ENUM	NO	1-open, 2-history, -1-all
side	ENUM	NO
startTime	LONG	NO
endTime	LONG	NO
fromId	String	NO	start order ID the searching to begin with.
direct	ENUM	NO	searching direction: prev - in ascending order from the start order ID; next - in descending order from the start order ID
limit	INT	NO	Default 500; max 1000.
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Notes:

if field "fromId" is defined, this field "direct" becomes mandatory.

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "orderId": "21",
                "clientId": "uuid",
                "symbol": "ADA_USDT",
                "symbolType": 1,
                "side": 1,
                "type": 1,
                "price": "0.1",
                "origQty": "10",
                "origQuoteQty": "1",
                "executedQty": "0",
                "executedPrice": "0",
                "executedQuoteQty": "0",
                "timeInForce": 1,
                "stopPrice": "0.0000000000000000",
                "icebergQty": "0.0000000000000000",
                "status": 0,
                "isWorking": 0,
                "createTime": 1572692016811
            }
        ]
    },
    "timestamp": 1572860756458
}

New OCO (SIGNED)

POST /open/v1/orders/oco (HMAC SHA256)

Send in a new OCO

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
listClientId	STRING	NO	Client's custom ID for the entire orderList, Server does not check it's uniqueness. Automatically generated if not sent.
side	ENUM	YES
quantity	STRING	YES
limitClientId	STRING	NO	Client's custom ID for the limit order, Server does not check it's uniqueness. Automatically generated if not sent.
price	STRING	YES
stopClientId	STRING	NO	Client's custom ID for the stop loss/stop loss limit order, Server does not check it's uniqueness. Automatically generated if not sent.
stopPrice	STRING	YES	Stop price
stopLimitPrice	STRING	YES	Stop limit price.
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Additional Info:

Price Restrictions:
- SELL: Limit Price > Last Price > Stop Price
- BUY: Limit Price < Last Price < Stop Price

Response:

{
    "code": 0,
    "message": "success",
    "data": {
        "orderId": "4",
        "createTime": 1550130502385
    },
    "timestamp": 1550130502489
}

Account information (SIGNED)

GET /open/v1/account/spot (HMAC SHA256)

Get current account information.

Parameters:

Name	Type	Mandatory	Description
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "makerCommission": "10.00000000",
        "takerCommission": "10.00000000",
        "buyerCommission": "0.00000000",
        "sellerCommission": "0.00000000",
        "canTrade": 1,
        "canWithdraw": 1,
        "canDeposit": 1,
        "accountAssets": [
            {
                "asset": "ADA",
                "free": "272.5550000000000000",
                "locked": "3.0000000000000000"
            }
        ]
    },
    "timestamp": 1572514387348
}

Account Asset information (SIGNED)

GET /open/v1/account/spot/asset (HMAC SHA256)

Get current account information for a specific asset.

Parameters:

Name	Type	Mandatory	Description
asset	STRING	YES
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
          "asset": "ADA",
          "free": "272.5550000000000000",
          "locked": "3.0000000000000000",
    },
    "timestamp": 1572514387348
}

Account trade list (SIGNED)

GET /open/v1/orders/trades  (HMAC SHA256)

Get trades for a specific account and symbol.

Parameters:

Name	Type	Mandatory	Description
symbol	STRING	YES
orderId	String	NO
startTime	LONG	NO
endTime	LONG	NO
fromId	LONG	NO	TradeId to fetch from. Default gets most recent trades.
direct	ENUM	NO	searching direction: prev - in ascending order from the start order ID; next - in descending order from the start order ID
limit	INT	NO	Default 500; max 1000.
recvWindow	LONG	NO	The value cannot be greater than `60000`
timestamp	LONG	YES

Notes:

if field "fromId" is defined, this field "direct" becomes mandatory.

Response:

{
    "code": 0,
    "msg": "success",
    "data": {
        "list": [
            {
                "tradeId": "3",
                "orderId": "2",
                "symbol": "ADA_USDT",
                "price": "0.04398",
                "qty": "250",
                "quoteQty": "10.995",
                "commission": "0.25",
                "commissionAsset": "ADA",
                "isBuyer": 1,
                "isMaker": 0,
                "isBestMatch": 1,
                "time": "1572920872276"
            }
        ]
    },
    "timestamp": 1573723498893
}

Wallet Endpoints

Withdraw (SIGNED)

POST /open/v1/withdraws (HMAC SHA256)

Submit a withdraw request.

Parameters:

Name	Type	Mandatory	Description
asset	STRING	YES
clientId	STRING	NO	Client's custom ID for withdraw order, Server does not check it's uniqueness. Automatically generated if not sent.
network	STRING	NO
address	STRING	YES
addressTag	STRING	NO	Secondary address identifier for coins like XRP,XMR etc.
amount	STRING	YES
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "成功",
    "data": {
        "withdrawId":"12"
    },
    "timestamp": 1571745049095
}

Withdraw History (SIGNED)

GET /open/v1/withdraws (HMAC SHA256)

Fetch withdraw history.

Parameters:

Name	Type	Mandatory	Description
asset	STRING	NO
status	INT	NO	0(0:Email Sent,1:Cancelled 2:Awaiting Approval 3:Rejected 4:Processing 5:Failure 10:Completed)
fromId	LONG	NO	ID to fetch from. Default gets most recent records.
startTime	LONG	NO
endTime	LONG	NO
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "成功",
    "data": {
        "list": [
            {
                "id": 1,
                "clientId": "1",
                "asset": "BTC",
                "network": "BTC",
                "address": "1G58aoKLVd1vHkv7wi6R2rKUrjuk4ZRtY3",
                "amount": "0.001",
                "fee": "0.0005",
                "txId": "",
                "status": 4,
                "createTime": 1572359825000,
            }
        ]
    },
    "timestamp": 1572402980747
}

Deposit History (SIGNED)

GET /open/v1/deposits (HMAC SHA256)

Fetch deposit history.

Parameters:

Name	Type	Mandatory	Description
asset	STRING	NO
status	INT	NO	0(0:pending, 1:success)
fromId	LONG	NO	ID to fetch from. Default gets most recent records.
startTime	LONG	NO
endTime	LONG	NO
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "成功",
    "data": {
        "list": [
            {
                "id": 1,
                "asset": "BTC",
                "network": "BTC",
                "address": "2",
                "addressTag": "2",
                "txId": "1",
                "amount": "1.000000000000000000000000000000",
                "status": 1,
                "insertTime": "0"
            }
        ]
    },
    "timestamp": 1572317515063
}

Deposit Address (SIGNED)

GET  /open/v1/deposits/address (HMAC SHA256)

Fetch deposit address.

Parameters:

Name	Type	Mandatory
asset	STRING	YES
network	STRING	YES
recvWindow	LONG	NO
timestamp	LONG	YES

Response:

{
    "code": 0,
    "msg": "成功",
    "data": {
        "address": "0x6915f16f8791d0a1cc2bf47c13a6b2a92000504b",
        "addressTag": "1231212",
        "asset": "BNB"
    },
    "timestamp": 1571745049095
}

General WSS information

The base endpoint is:

wss://stream.binance.com:9443(when symbol type is 1, replace _ of symbol with null string and convert symbol to lowercase)
wss://www.tokocrypto.com(when symbol type is not 1)

Streams can be accessed either in a single raw stream or in a combined stream
Raw streams are accessed at /ws/\<streamName>
Combined streams are accessed at /stream?streams=\<streamName1>/\<streamName2>/\<streamName3>
Combined stream events are wrapped as follows: {"stream":"\<streamName>","data":\<rawPayload>}
A single connection to stream.binance.com www.tokocrypto.com is only valid for 24 hours; expect to be disconnected at the 24 hour mark
The websocket server will send a ping frame every 3 minutes. If the websocket server does not receive a pong frame back from the connection within a 10 minute period, the connection will be disconnected. Unsolicited pong frames are allowed.

Live Subscribing/Unsubscribing to streams

The following data can be sent through the websocket instance in order to subscribe/unsubscribe from streams. Examples can be seen below.
The id used in the JSON payloads is an unsigned INT used as an identifier to uniquely identify the messages going back and forth.
In the response, if the result received is null this means the request sent was a success for non-query requests (e.g. Subscribing/Unsubscribing).

Request

{
  "method": "SUBSCRIBE",
  "params": [
    "btcusdt@aggTrade",
    "btcusdt@depth"
  ],
  "id": 1
}

Response
```
{
  "result": null,
  "id": 1
}
```

Unsubscribe to a stream

Request

{
  "method": "UNSUBSCRIBE",
  "params": [
    "btcusdt@depth"
  ],
  "id": 312
}

Response
```
{
  "result": null,
  "id": 312
}
```

Listing Subscriptions

Request

{
  "method": "LIST_SUBSCRIPTIONS",
  "id": 3
}

Response

{
  "result": [
    "btcusdt@aggTrade"
  ],
  "id": 3
}

Setting Properties

Currently, the only property can be set is to set whether combined stream payloads are enabled are not. The combined property is set to false when connecting using /ws/ ("raw streams") and true when connecting using /stream/.

Request

{
  "method": "SET_PROPERTY",
  "params": [
    "combined",
    true
  ],
  "id": 5
}

Response
```
{
  "result": null,
  "id": 5
}
```

Retrieving Properties

Request

{
  "method": "GET_PROPERTY",
  "params": [
    "combined"
  ],
  "id": 2
}

Response

{
  "result": true, // Indicates that combined is set to true.
  "id": 2
}

Error Messages

Error Message	Description
{"code": 0, "msg": "Unknown property"}	Parameter used in the `SET_PROPERTY` or `GET_PROPERTY` was invalid
{"code": 1, "msg": "Invalid value type: expected Boolean"}	Value should only be `true` or `false`
{"code": 2, "msg": "Invalid request: property name must be a string"}	Property name provided was invalid
{"code": 2, "msg": "Invalid request: request ID must be an unsigned integer"}	Parameter `id` had to be provided or the value provided in the `id` parameter is an unsupported type
{"code": 2, "msg": "Invalid request: unknown variant %s, expected one of `SUBSCRIBE`, `UNSUBSCRIBE`, `LIST_SUBSCRIPTIONS`, `SET_PROPERTY`, `GET_PROPERTY` at line 1 column 28"}	Possible typo in the provided method or provided method was neither of the expected values
{"code": 2, "msg": "Invalid request: too many parameters"}	Unnecessary parameters provided in the data
{"code": 2, "msg": "Invalid request: property name must be a string"}	Property name was not provided
{"code": 2, "msg": "Invalid request: missing field `method` at line 1 column 73"}	`method` was not provided in the data
{"code":3,"msg":"Invalid JSON: expected value at line %s column %s"}	JSON data sent has incorrect syntax.

Detailed Stream information

Aggregate Trade Streams

The Aggregate Trade Streams push trade information that is aggregated for a single taker order.

Stream Name: \<symbol>@aggTrade

Update Speed: Real-time

Payload:

{
  "e": "aggTrade",  // Event type
  "E": 123456789,   // Event time
  "s": "BNBBTC",    // Symbol
  "a": 12345,       // Aggregate trade ID
  "p": "0.001",     // Price
  "q": "100",       // Quantity
  "f": 100,         // First trade ID
  "l": 105,         // Last trade ID
  "T": 123456785,   // Trade time
  "m": true,        // Is the buyer the market maker?
  "M": true         // Ignore
}

Trade Streams

The Trade Streams push raw trade information; each trade has a unique buyer and seller.

Stream Name: \<symbol>@trade

Update Speed: Real-time

Payload:

{
  "e": "trade",     // Event type
  "E": 123456789,   // Event time
  "s": "BNBBTC",    // Symbol
  "t": 12345,       // Trade ID
  "p": "0.001",     // Price
  "q": "100",       // Quantity
  "b": 88,          // Buyer order ID
  "a": 50,          // Seller order ID
  "T": 123456785,   // Trade time
  "m": true,        // Is the buyer the market maker?
  "M": true         // Ignore
}

Kline/Candlestick Streams

The Kline/Candlestick Stream push updates to the current klines/candlestick every second.

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

Stream Name: \<symbol>@kline_\<interval>

Update Speed: 2000ms

Payload:

{
  "e": "kline",     // Event type
  "E": 123456789,   // Event time
  "s": "BNBBTC",    // Symbol
  "k": {
    "t": 123400000, // Kline start time
    "T": 123460000, // Kline close time
    "s": "BNBBTC",  // Symbol
    "i": "1m",      // Interval
    "f": 100,       // First trade ID
    "L": 200,       // Last trade ID
    "o": "0.0010",  // Open price
    "c": "0.0020",  // Close price
    "h": "0.0025",  // High price
    "l": "0.0015",  // Low price
    "v": "1000",    // Base asset volume
    "n": 100,       // Number of trades
    "x": false,     // Is this kline closed?
    "q": "1.0000",  // Quote asset volume
    "V": "500",     // Taker buy base asset volume
    "Q": "0.500",   // Taker buy quote asset volume
    "B": "123456"   // Ignore
  }
}

Individual Symbol Mini Ticker Stream

24hr rolling window mini-ticker statistics. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs.

Stream Name: \<symbol>@miniTicker

Update Speed: 1000ms

Payload:

  {
    "e": "24hrMiniTicker",  // Event type
    "E": 123456789,         // Event time
    "s": "BNBBTC",          // Symbol
    "c": "0.0025",          // Close price
    "o": "0.0010",          // Open price
    "h": "0.0025",          // High price
    "l": "0.0010",          // Low price
    "v": "10000",           // Total traded base asset volume
    "q": "18"               // Total traded quote asset volume
  }

All Market Mini Tickers Stream

24hr rolling window mini-ticker statistics for all symbols that changed in an array. These are NOT the statistics of the UTC day, but a 24hr rolling window for the previous 24hrs. Note that only tickers that have changed will be present in the array.

Stream Name: !miniTicker@arr

Update Speed: 1000ms

Payload:

[
  {
    // Same as <symbol>@miniTicker payload
  }
]

Partial Book Depth Streams

Top \<levels> bids and asks, pushed every second. Valid \<levels> are 5, 10, or 20.

Stream Names: \<symbol>@depth\<levels> OR \<symbol>@depth\<levels>@100ms

Update Speed: 1000ms or 100ms

Payload:

{
  "lastUpdateId": 160,  // Last update ID
  "bids": [             // Bids to be updated
    [
      "0.0024",         // Price level to be updated
      "10"              // Quantity
    ]
  ],
  "asks": [             // Asks to be updated
    [
      "0.0026",         // Price level to be updated
      "100"            // Quantity
    ]
  ]
}

Diff. Depth Stream

Order book price and quantity depth updates used to locally manage an order book.

Stream Name: \<symbol>@depth OR \<symbol>@depth@100ms

Update Speed: 1000ms or 100ms

Payload:

{
  "e": "depthUpdate", // Event type
  "E": 123456789,     // Event time
  "s": "BNBBTC",      // Symbol
  "U": 157,           // First update ID in event
  "u": 160,           // Final update ID in event
  "b": [              // Bids to be updated
    [
      "0.0024",       // Price level to be updated
      "10"            // Quantity
    ]
  ],
  "a": [              // Asks to be updated
    [
      "0.0026",       // Price level to be updated
      "100"           // Quantity
    ]
  ]
}

How to manage a local order book correctly

Open a stream to wss://stream.binance.com:9443/ws/bnbbtc@depth.
Buffer the events you receive from the stream.
Get a depth snapshot from https://api.binance.com/api/v3/depth?symbol=BNBBTC&limit=1000 .
Drop any event where u is <= lastUpdateId in the snapshot.
The first processed event should have U <= lastUpdateId+1 AND u >= lastUpdateId+1.
While listening to the stream, each new event's U should be equal to the previous event's u+1.
The data in each event is the absolute quantity for a price level.
If the quantity is 0, remove the price level.
Receiving an event that removes a price level that is not in your local order book can happen and is normal.

API Document Description

General API Information

HTTP Return Codes

Response fields description

General Information on Endpoints

LIMITS

General Info on Limits

IP Limits

Order Rate Limits

Endpoint security type

SIGNED Endpoint security

Timing security

SIGNED Endpoint Examples for POST /open/v1/orders

Example 1: As a request body

Example 2: As a query string

Example 3: Mixed query string and request body

Public API Definitions

Terminology

ENUM definitions

Filters

Symbol Filters

PRICE_FILTER

PERCENT_PRICE

LOT_SIZE

MIN_NOTIONAL

ICEBERG_PARTS

MARKET_LOT_SIZE

MAX_NUM_ORDERS

MAX_NUM_ALGO_ORDERS

MAX_NUM_ICEBERG_ORDERS

Exchange Filters

EXCHANGE_MAX_NUM_ORDERS

EXCHANGE_MAX_NUM_ALGO_ORDERS

General endpoints

Check server time

Get all Supported Trading Symbol

Market Data endpoints

Order book

Recent trades list

Compressed/Aggregate trades list

Kline/Candlestick data

Account endpoints

New order (SIGNED)

Query order (SIGNED)

Cancel order (SIGNED)

All orders (SIGNED)

New OCO (SIGNED)

Account information (SIGNED)

Account Asset information (SIGNED)

Account trade list (SIGNED)

Wallet Endpoints

Withdraw (SIGNED)

Withdraw History (SIGNED)

Deposit History (SIGNED)

Deposit Address (SIGNED)

General WSS information

Live Subscribing/Unsubscribing to streams

Subscribe to a stream

Unsubscribe to a stream

Listing Subscriptions

Setting Properties

Retrieving Properties

Error Messages

Detailed Stream information

Aggregate Trade Streams

Trade Streams

Kline/Candlestick Streams

Individual Symbol Mini Ticker Stream

All Market Mini Tickers Stream

Partial Book Depth Streams

Diff. Depth Stream

How to manage a local order book correctly