HTTP API

The Binance Chain HTTP API provides access to a Binance Chain node deployment and market data services.

Version: 1.0.0

License: Apache 2.0

/api/v1/time


GET

Summary: Get the block time.

Description: Gets the latest block time and the current time according to the HTTP service.

Destination: Validator node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/time

URL for testnet: https://testnet-dex.binance.org/api/v1/time

Responses

Code Description Schema
200 Success Times
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/node-info


GET

Summary: Get node information.

Description: Gets runtime information about the node.

Destination: Validator node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/node-info

URL for testnet: https://testnet-dex.binance.org/api/v1/node-info

Responses

Code Description Schema
200 Success ResultStatus

/api/v1/validators


GET

Summary: Get validators.

Description: Gets the list of validators used in consensus.

Destination: Witness node.

Rate Limit: 10 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/validators

URL for testnet: https://testnet-dex.binance.org/api/v1/validators

Responses

Code Description Schema
200 Success [ Validators ]
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/peers


GET

Summary: Get network peers.

Description: Gets the list of network peers.

Destination: Witness node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/peers

URL for testnet: https://testnet-dex.binance.org/api/v1/peers

Responses

Code Description Schema
200 Success [ Peer ]
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/account/{address}


GET

Summary: Get an account.

Description: Gets account metadata for an address.

Destination: Witness node.

Rate Limit: 5 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/account/bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m

URL for testnet: https://testnet-dex.binance.org/api/v1/account/tbnb185tqzq3j6y7yep85lncaz9qeectjxqe5054cgn

Parameters

Name Located in Description Required Schema
address path The account address to query Yes string

Responses

Code Description Schema
200 Success Account
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/account/{address}/sequence


GET

Summary: Get an account sequence.

Description: Gets an account sequence for an address.

Destination: Validator node.

Rate Limit: 5 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/account/bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m/sequence

URL for testnet: https://testnet-dex.binance.org/api/v1/account/tbnb13g2le062t340klgm2l2khzr57y3qxlekuhfuch/sequence

Parameters

Name Located in Description Required Schema
address path The account address to query Yes string

Responses

Code Description Schema
200 Success AccountSequence
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/tx/{hash}


GET

Summary: Get a transaction.

Description: Gets transaction metadata by transaction ID. By default, transactions are returned in a raw format. You may add ?format=json to the end of the path to obtain a more readable response.

Destination: Seed node.

Rate Limit: 10 requests per IP per second.

Example:

Below is an example response of a send transaction when ?format=json is used.

    {
     code:0,
     hash:"433806D6A4AB6359CB56EC55BA99896DFAB2AF11326B74881A2ABA7049C492D3",
     height:"7850389",
     log:"Msg 0: ",
     ok:true,
     tx:{
        type:"auth/StdTx",
        value:{
           data:null,
           memo:"101192150",
           msg:[
              {
                 type:"cosmos-sdk/Send",
                 value:{
                    inputs:[
                       {
                          address:"bnb1jafs33u9u6f7w7wzfmm4rr9rzy2cgqzp78kwaw",
                          coins:[
                             {
                                amount:"496429373",
                                denom:"BNB",

                             }
                          ],

                       }
                    ],
                    outputs:[
                       {
                          address:"bnb136ns6lfw4zs5hg4n85vdthaad7hq5m4gtkgf23",
                          coins:[
                             {
                                amount:"496429373",
                                denom:"BNB",

                             }
                          ],

                       }
                    ],

                 },

              }
           ],
           signatures:[
              {
                 account_number:"438",
                 pub_key:{
                    type:"tendermint/PubKeySecp256k1",
                    value:"A3mfgg/i12XNyy9esqCjI7yrkrOs9dngP7c9cDUEJly5",

                 },
                 sequence:"0",
                 signature:"VvvGz3qbyirJ7vv01Df8tuAd7K4I+HK+yEBfep+qwtMKuHWQQH3XtMB9Pqtc2jlia0AtDe+BUEMtIyh3/N66IQ==",

              }
           ],
           source:"1",

        },

     },

  }

Parameters

Name Located in Description Required Schema
hash path The transaction hash to query Yes string
format query Response format (json or amino) No string

Responses

Code Description Schema
0 Success Transaction
404 Not Found
500 Bad Request Error
default Generic error response Error

/api/v1/tokens


GET

Summary: Get tokens list.

Description: Gets a list of tokens that have been issued.

Destination: Witness node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/tokens

URL for testnet: https://testnet-dex.binance.org/api/v1/tokens

Parameters

Name Located in Description Required Schema
limit query default 500; max 1000. No integer
offset query start with 0; default 0. No integer

Responses

Code Description Schema
200 Success [ Token ]
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/markets


GET

Summary: Get market pairs.

Description: Gets the list of market pairs that have been listed.

Destination: Witness node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/markets

URL for testnet: https://testnet-dex.binance.org/api/v1/markets

Parameters

Name Located in Description Required Schema
limit query default 500; max 1000. No integer
offset query start with 0; default 0. No integer

Responses

Code Description Schema
200 Success [ Market ]
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/fees


GET

Summary: Obtain trading fees information.

Description: Gets the current trading fees settings.

Destination: Witness node.

Rate Limit: 1 request per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/fees

URL for testnet: https://testnet-dex.binance.org/api/v1/fees

Responses

Code Description Schema
200 Success [ Fee ]
default Generic error response Error

/api/v1/depth


GET

Summary: Get the order book.

Description: Gets the order book depth data for a given pair symbol.

The given limit must be one of the allowed limits below.

Destination: Validator node.

Rate Limit: 10 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/depth?symbol=xxx-000_BNB

URL for testnet: https://testnet-dex.binance.org/api/v1/depth?symbol=xxx-000_BNB

Parameters

Name Located in Description Required Schema
symbol query Market pair symbol, e.g. NNB-0AD_BNB Yes string
limit query The limit of results. Allowed limits: [5, 10, 20, 50, 100, 500, 1000] No integer

Responses

Code Description Schema
200 Success MarketDepth
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/broadcast


POST

Summary: Broadcast a transaction.

Description: Broadcasts a signed transaction. A single transaction must be sent hex-encoded with a content-type of text/plain.

Destination: Witness node.

Rate Limit: 5 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/broadcast

URL for testnet: https://testnet-dex.binance.org/api/v1/broadcast

Parameters

Name Located in Description Required Schema
sync query Synchronous broadcast (wait for DeliverTx)? No boolean
body body Yes binary

Responses

Code Description Schema
200 Success [ Transaction ]
400 Bad Request Error
401 Bad Signature Error
404 Not Found
default Generic error response Error

/api/v1/klines


GET

Summary: Get candlestick bars.

Description: Gets candlestick/kline bars for a symbol. Bars are uniquely identified by their open time.

If the time window is larger than limits, only the first n klines will return. In this case, please either shrink the window or increase the limit to get proper amount of klines.

Rate Limit: 10 requests per IP per second.

URL for mainnet: https://dex.binance.org/api/v1/klines?symbol=NNB-338_BNB&interval=5m

URL for testnet: https://testnet-dex.binance.org/api/v1/klines?symbol=NNB-338_BNB&interval=5m

Example

[
  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
]

Parameters

Name Located in Description Required Schema
symbol query symbol Yes string
interval query interval. Allowed value: [1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1M] Yes enum string
limit query default 300; max 1000. No integer
startTime query start time in Milliseconds No long
endTime query end time in Milliseconds No long

Responses

Code Description Schema
200 OK [ Candlestick ]

/api/v1/orders/closed


GET

Summary: Get closed orders.

Description: Gets closed (filled and cancelled) orders for a given address.

Query Window: Default query window is latest 7 days; The maximum start - end query window is 3 months.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
address query the owner address Yes string
end query end time in Milliseconds No long
limit query default 500; max 1000. No integer
offset query start with 0; default 0. No integer
side query order side. 1 for buy and 2 for sell. No integer
start query start time in Milliseconds No long
status query order status list. Allowed value: [Ack, PartialFill, IocNoFill, FullyFill, Canceled, Expired, FailedBlocking, FailedMatching] No enum string
symbol query symbol No string
total query total number required, 0 for not required and 1 for required; default not required, return total=-1 in response No integer

Responses

Code Description Schema
200 OK OrderList

/api/v1/orders/open


GET

Summary: Get open orders.

Description: Gets open orders for a given address.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
address query the owner address Yes string
limit query default 500; max 1000. No integer
offset query start with 0; default 0. No integer
symbol query symbol No string
total query total number required, 0 for not required and 1 for required; default not required, return total=-1 in response No integer

Responses

Code Description Schema
200 OK OrderList
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/orders/{id}


GET

Summary: Get an order.

Description: Gets metadata for an individual order by its ID.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
id path order id Yes string

Responses

Code Description Schema
200 OK Order
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/ticker/24hr


GET

Summary: Get a market ticker.

Description: Gets 24 hour price change statistics for a market pair symbol.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
symbol query symbol No string

Responses

Code Description Schema
200 OK [ TickerStatistics ]
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/trades


GET

Summary: Get market trades.

Description: Gets a list of historical trades.

Query Window: Default query window is latest 7 days; The maximum start - end query window is 3 months.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
address query the buyer/seller address No string
buyerOrderId query buyer order id No string
end query end time in Milliseconds No long
height query block height No long
limit query default 500; max 1000. No integer
offset query start with 0; default 0. No integer
quoteAsset query quote asset No string
sellerOrderId query seller order id No string
side query order side. 1 for buy and 2 for sell. No integer
start query start time in Milliseconds No long
symbol query symbol No string
total query total number required, 0 for not required and 1 for required; default not required, return total=-1 in response No integer

Responses

Code Description Schema
200 OK TradePage
400 Bad Request Error
404 Not Found
default Generic error response Error

/api/v1/block-exchange-fee


GET

Summary: Trading fee of the address grouped by block

Description: Get historical trading fees of the address, including fees of trade/canceled order/expired order. Transfer and other transaction fees are not included. Order by block height DESC.

Query Window: Default query window is latest 7 days; The maximum start - end query window is 3 months.

Rate Limit: 5 requests per IP per second.

Parameters

Name Located in Description Required Schema
address query the seller/buyer address No string
end query end time No long
limit query default 50; max 1000. No integer
offset query start with 0; default 0. No integer
start query start time No long
total query total number required, 0 for not required and 1 for required; default not required, return total=-1 in response No integer

Responses

Code Description Schema
200 OK BlockExchangeFeePage

/api/v1/transactions


GET

Summary: Get transactions.

Description: Gets a list of transactions. Multisend transaction is not available in this API.

Query Window: Default query window is latest 24 hours; The maximum start - end query window is 3 months.

Rate Limit: 60 requests per IP per minute.

Parameters

Name Located in Description Required Schema
address query address Yes string
blockHeight query blockHeight No long
endTime query endTime in Milliseconds No long
limit query limit No integer
offset query offset No integer
side query transaction side. Allowed value: [ RECEIVE, SEND] No enum string
startTime query start time in Milliseconds No long
txAsset query txAsset No string
txType query transaction type. Allowed value: [ NEW_ORDER,ISSUE_TOKEN,BURN_TOKEN,LIST_TOKEN,CANCEL_ORDER,FREEZE_TOKEN,UN_FREEZE_TOKEN,TRANSFER,PROPOSAL,VOTE,MINT,DEPOSIT] No enum string

Responses

Code Description Schema
200 OK TxPage
400 Bad Request Error
404 Not Found
default Generic error response Error

Models


Error

Name Type Description Example
code long error code 400
message string error message

Times

Name Type Description Example
ap_time string event time e.g. 2019-01-21T10:30:00Z
block_time string the time of latest block e.g. 2019-01-21T10:30:00Z

Validators

Name Type Description Example
block_height long Current block height 12345
validators [ Validator ]

Validator

Name Type Description Example
address string (hex address) Address
pub_key [ integer ] Public key bytes
voting_power integer
accum integer

Peer

Name Type Description Example
id string Authenticated identifier 8c379d4d3b9995c712665dc9a9414dbde5b30483
original_listen_addr string (RemoteAddr) Original listen address before PeersService changed it
listen_addr string (RemoteAddr) Listen address
access_addr string (RemoteAddr) Access address (HTTP)
stream_addr string (RemoteAddr) Stream address (WS)
network string Chain ID Binance-Chain-Nile
version string Version 0.30.1
moniker string Moniker (Name) data-seed-1
capabilities [ string ] Array of capability tags: node, qs, ap, ws node,ap
accelerated boolean Is an accelerated path to a validator node

Transaction

Name Type Description Example
hash string (hex) Hash of transaction, it returned as bytes before, and now it returns as hex string
log string Log of transaction
data string Data of transaction
height string Height of transaction
code integer Result code of transaction
ok boolean
tx object Detail of transaction, like transaction type, messages and signature

For example, below is the detail of a send transaction. Most of the fields are fixed, but the detail of msg varies with msg type, if you query with --format=json.

{
    "type": "auth/StdTx", // fixed, type of transaction
    "value": {            // fixed, detail of the transaction
        "data": null,     // fixed, data of the transaction
        "memo": "",       // fixed, memo
        "msg": [          // fixed, msgs of the transaction
            {
                "type": "cosmos-sdk/Send",  // vary with msg type
                "value": {                  // value content vary with mst type
                    "inputs": [
                        {
                            "address": "bnb1vt4zwu5hy7tyryktud6mpcu8h2ehh6xw66gzwp",
                            "coins": [
                                {
                                    "amount": "100000000000000",
                                    "denom": "BNB"
                                }
                            ]
                        }
                    ],
                    "outputs": [
                        {
                            "address": "bnb1kg8mh20tndur9d9rry4wjunhpfzcud30qzf0qv",
                            "coins": [
                                {
                                    "amount": "100000000000000",
                                    "denom": "BNB"
                                }
                            ]
                        }
                    ]
                }
            }
        ],
        "signatures": [ // fixed, signatures of the transaction
            {
                "account_number": "0",
                "pub_key": {
                    "type": "tendermint/PubKeySecp256k1",
                    "value": "AoWY3eWBOnnvLPTz4RsUlX1pWCkLLPewu1vAAoTEzxzR"
                },
                "sequence": "1",
                "signature": "6O2TQAgleFNPw4zIWBLaNvOf5dR7DHNSr2DwAPeFK6lokRqZd2KR2BD+WlmaWj4LdLo5N+utN1JtY41E91N0uw=="
            }
        ],
        "source": "0"  // fixed, source of the transaction
    }
}

| |

Account

Name Type Description Example
account_number integer
address string (address)
balances [ Balance ]
public_key [ integer ] Public key bytes
sequence long sequence is for preventing replay attack

AccountSequence

Name Type Description Example
sequence long number used for preventing replay attack 1

Balance

Name Type Description Example
symbol string (currency) asset symbol BNB
free string (fixed8) In decimal form, e.g. 0.00000000 0.00000000
locked string (fixed8) In decimal form, e.g. 0.00000000 0.00000000
frozen string (fixed8) In decimal form, e.g. 0.00000000 0.00000000

Token

Name Type Description Example
name string token name Binance Chain Native Token
symbol string unique token trade symbol BTC-000
original_symbol string token symbol BTC
total_supply string (fixed8) total token supply in decimal form, e.g. 1.00000000 0.00000000
owner string (address) Address which issue the token

Market

Name Type Description Example
base_asset_symbol string (currency) symbol of base asset BNB
quote_asset_symbol string (currency) symbol of quote asset ABC-5CA
list_price string (fixed8) In decimal form 1.00000000
tick_size string (fixed8) Minimium price change in decimal form 0.00000001
lot_size string (fixed8) Minimium trading quantity in decimal form 1.00000000

Fee

Name Type Description Example
msg_type string Transaction msg type that this fee applies to submit_proposal
fee number The fee amount 1000000000
fee_for integer 1 = proposer, 2 = all, 3 = free 1
multi_transfer_fee string Fee for multi-transfer 200000
lower_limit_as_multi string e.g. 2 2
fixed_fee_params FixedFeeParams Set if the fee is fixed
dex_fee_fields DexFeeFieldParams dex fee

FixedFeeParams

Name Type Description Example
msg_type string Transaction msg type that this fee applies to submit_proposal
fee number The fixed fee amount 1000000000
fee_for integer 1 = proposer, 2 = all, 3 = free 1

DexFeeFieldParams

Name Type Description Example
fee_name string fee name
fee_value integer fee value

MarketDepth

Name Type Description Example
asks [ string (fixed8) ] Price and qty in decimal form, e.g. 1.00000000 ["1.00000000","800.00000000"]
bids [ string (fixed8) ] Price and qty in decimal form, e.g. 1.00000000 ["1.00000000","800.00000000"]

Candlestick

Name Type Description Example
close number closing price
closeTime long
high number the highest price
low number the lowest price
numberOfTrades integer
open number open price
openTime long time of open trade
quoteAssetVolume number
volume number

OrderList

Name Type Description Example
order [ Order ] list of orders
total long

Order

Name Type Description Example
cumulateQuantity string
fee string trading fee on the block of this order
lastExecutedPrice string price of last execution
lastExecutedQuantity string quantity of last execution
orderCreateTime dateTime time of order creation
orderId string order ID
owner string order issuer
price string order price
quantity string order quantity
side integer 1 for buy and 2 for sell
singleFee string trading fee of this order
status string enum [Ack, PartialFill, IocNoFill, FullyFill, Canceled, Expired, FailedBlocking, FailedMatching, IocExpire]
symbol string
timeInForce integer 1 for Good Till Expire(GTE) order and 3 for Immediate Or Cancel (IOC)
tradeId string trade ID
transactionHash string
transactionTime dateTime time of transaction
type integer only 2 is available for now, meaning limit order

TickerStatistics

Name Type Description Example
askPrice string ask price
askQuantity string ask quantity
bidPrice string bid price
bidQuantity string bid quantity
closeTime long time of closing
count long total count
firstId string
highPrice string
lastId string
lastPrice string
lastQuantity string
lowPrice string
openPrice string
openTime long
prevClosePrice string
priceChange string
priceChangePercent string
quoteVolume string
symbol string
volume string
weightedAvgPrice string

TradePage

Name Type Description Example
total long
trade [ Trade ]

Trade

Name Type Description Example
baseAsset string base asset
blockHeight long block height
buyFee string trading fee for the buyer address on the block of this trade
buyerId string id of buyer
buyerOrderId string order id for buyer
buySingleFee string trading fee for the buyer address on this single trade
price string trade price
quantity string trade quantity
quoteAsset string quote asset
sellFee string trading fee for the seller address on the block of this trade
sellerId string seller ID
sellerOrderId string seller order ID
sellSingleFee string trading fee for the seller address on this single trade
symbol string asset symbol
tickType string enum [Unknown,SellTaker,BuyTaker,BuySurplus,SellSurplus,Neutral]
time long trade time
tradeId string trade ID

BlockExchangeFeePage

Name Type Description Example
blockExchangeFee [ BlockExchangeFee ]
total long

BlockExchangeFee

Name Type Description Example
address string
blockHeight long
blockTime long timestamp of a block
fee string total fee collected
tradeCount long trade count of the address on the block

TxPage

Name Type Description Example
total long total sum of transactions
tx [ Tx ]

Tx

Name Type Description Example
blockHeight long block height
code integer transaction result code 0
confirmBlocks long
data string
fromAddr string from address
orderId string order ID
timeStamp dateTime time of transaction
toAddr string to address
txAge long
txAsset string
txFee string
txHash string hash of transaction
txType string type of transaction
value string value of transaction

ExchangeRate

Name Type Description Example
ExchangeRate object

ResultStatus

Name Type Description Example
validator_info [ ValidatorInfo ]
sync_info [ SyncInfo ]
node_info [ NodeInfo ]

NodeInfo

Name Type Description Example
Protocol_Version [ ProtocolVersion ]
ID string
listen_addr string
network string
version string
channels string
moniker string
other object

SyncInfo

Name Type Description Example
latest_block_hash string (hex)
latest_app_hash string (hex)
latest_block_height long
latest_block_time time
catching_up boolean

ProtocolVersion

Name Type Description Example
P2P integer (uint64)
block integer (uint64)
app integer (uint64)

ValidatorInfo

Name Type Description Example
address string hex address
pub_key string hex-encoded
voting_power long