HTTP API

Within the ecosystem of Binance Chain, there are several accelerated nodes which provides more secure and faster lines to access Binance Chain data service including HTTP API.

For mainnet, there are more accelerated nodes.

• dex-atlantic.binance.org

• dex-asiapacific.binance.org

• dex-european.binance.org

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	Error
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 100.	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/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/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/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 in Milliseconds	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

---

Note: This endpoint will be retired soon, use this api instead (please read the migration guide).

GET

Summary: Get transactions.

Description: Gets a list of transactions. Multisend transaction is not available in this API. Currently 'confirmBlocks' and 'txAge' are not supported.

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

Rate Limit: 15 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: [ TRANSFER,NEW_ORDER,ISSUE_TOKEN,BURN_TOKEN,LIST_TOKEN,CANCEL_ORDER,FREEZE_TOKEN,UN_FREEZE_TOKEN,TRANSFER,PROPOSAL,VOTE,MINT,DEPOSIT,CREATE_VALIDATOR,REMOVE_VALIDATOR,TIME_LOCK,TIME_UNLOCK,TIME_RELOCK,SET_ACCOUNT_FLAG,HTL_TRANSFER,CLAIM_HTL,DEPOSIT_HTL,REFUND_HTL]	No	enum string

Responses

Code	Description	Schema
200	OK	TxPage
400	Bad Request	Error
404	Not Found
403	Tx is not within 24h query window
default	Generic error response	Error

/api/v1/transactions-in-block/{blockHeight}

---

Note: This endpoint will be retired soon, use this api instead (please read the migration guide).

GET

Summary: Get transactions in the specific block.

Description: Get transactions in the block. Multi-send and multi-coin transactions are flattened as transactions. This API is deprecated.

Rate Limit: 1 requests per IP per second.

Rate Limit: 15 requests per IP per minute.

Parameters

Name	Located in	Description	Required	Schema
blockHeight	path	block height	Yes	string

Responses

Code	Description	Schema
200	OK	BlockTx
400	Bad Request. The block to query is higher than current highest block.	Error
404	Not Found
default	Generic error response	Error

/api/v2/transactions-in-block/{blockHeight}

Note: This endpoint will be retired soon, use this api instead (please read the migration guide).

---

GET

Summary: transactions in Block

Description: Get transactions in the block. Multi-send and multi-coin transactions are included as sub-transactions.

Rate Limit: 1 request per IP per second.

Rate Limit: 15 requests per IP per minute.

Parameters

Name	Located in	Description	Required	Schema
blockHeight	path	blockHeight	Yes	long

Responses

Code	Description	Schema
200	OK	BlockTxV2
400	Bad Request. The block to query is higher than current highest block.	Error

/api/v1/atomic-swaps

---

GET

Summary: AtomicSwap

Description: Get atomic swaps by address.

Rate Limit: 5 request per IP per second.

Rate Limit: 60 requests per IP per minute.

Parameters

Name	Located in	Description	Required	Schema
endTime	query	end time of blockTimestamp	No	long
fromAddress	query	At least one of toAddress and fromAddress should be provided as parameter	No	string
limit	query	default 25; max 1000.	No	integer
offset	query	start with 0; default 0.	No	integer
startTime	query	start time of blockTimestamp in Milliseconds; The maximum start - end query window is 3 months; Default query window is the latest 30 days.	No	long
toAddress	query	At least one of toAddress and fromAddress should be provided as parameter	No	string

Responses

Code	Description	Schema
200	OK	AtomicSwapPage

/api/v1/atomic-swaps/{id}

---

GET

Summary: AtomicSwap

Description: Get an AtomicSwap by swap id

Rate Limit: 5 request per IP per second.

Rate Limit: 60 request per IP per minute.

Parameters

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

Responses

Code	Description	Schema
200	OK	AtomicSwap

/api/v1/timelocks/{address}

---

GET

Summary: Gets time lock records given an address

Parameters

Name	Located in	Description	Required	Schema
address	path	The account address to query	Yes	string
id	query	the record id of timelock to query	No	long

Responses

Code	Description	Schema
200	Success	TimeLocks
400	Bad Request	Error
500	internal server error	Error

/api/v1/timelock/{account_addr}?(id={recordid})

---

GET

Summary: Get timelock records of an address.

Description: Get the timelock history of an address. Rate Limit: 60 requests per IP per minute.

Parameters

Name	Located in	Description	Required	Schema
address	path	The account address to query	Yes	string
id	query	the record id of timelock to query	No	long

Responses

Code	Description	Schema
200	Success	TimeLocks
400	Bad Request	Error
404	Not Found
500	internal server error	Error

/api/v1/mini/tokens

---

GET

Summary: Gets a list of available mini tokens.

Parameters

Name	Located in	Description	Required	Schema
offset	query	offset	No	integer
limit	query	limit	No	integer

Responses

Code	Description	Schema
200	Success	MiniTokens
400	Bad Request	Error
500	internal server error	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	validator's voting power
accum	integer	validator's accumulated voting power

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-Ganges
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
contract_address	string	smart contract address for this token
contract_decimals	int	the token decimals

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

SubTx

Name	Type	Description	Example
blockHeight	long
fromAddr	string
toAddr	string
txAsset	string
txFee	string
txHash	string
txType	string
value	string

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. Multiple assets are split by semicolon.
tradeCount	long	trade count of the address on the block

TxPage

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

BlockTx

Name	Type	Description	Example
blockHeight	long	block height
tx	[ Tx ]

BlockTxV2

Name	Type	Description	Example
blockHeight	long	block height
tx	[ TxV2 ]

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
source	long
sequence	long
swapId	string	Optional. Available when the transaction type is one of HTL_TRANSFER, CLAIM_HTL, REFUND_HTL, DEPOSIT_HTL
proposalId	string

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

AtomicSwapPage

Name	Type	Description	Example
atomicSwaps	[ AtomicSwap ]
total	long

AtomicSwap

Name	Type	Description	Example
blockTimestamp	long	Timestamp of block in which the swap is initiated. The unit is millisecond.
closedTime	long
crossChain	integer
expectedIncome	string
expireHeight	long
fromAddr	string
inAmount	string
outAmount	string
randomNumber	string
randomNumberHash	string
recipientOtherChain	string
status	integer
swapId	string
timestamp	string (int64)	The timestamp for randomNumberHash calculation, randomNumberHash=sha256(randomNumber, timestamp). The unit is second.
toAddr	string

TxV2

Name	Type	Description	Example
blockHeight	long
code	integer		0
data	string
fromAddr	string
memo	string
orderId	string	Optional. Available when the transaction type is NEW_ORDER
proposalId	string	Optional. Available when the transaction type is PROPOSAL
sequence	long
source	long
subTransactions	[ SubTx ]	Optional. Available when the transaction has sub-transactions, such as multi-send transaction or a transaction have multiple assets
swapId	string	Optional. Available when the transaction type is one of HTL_TRANSFER, CLAIM_HTL, REFUND_HTL, DEPOSIT_HTL
timeStamp	dateTime
toAddr	string
txAsset	string
txFee	string
txHash	string
txType	string
value	string

TimeLocks

Name	Type	Description	Example
id	long	The record id of the timelock transaction
description	string	The description of the timelock transaction
amount	[ ]
locktime	string	The available unlock time

MiniTokens

Name	Type	Description	Example
name	string		Binance Chain Mini Token
symbol	string		BTC-000
original_symbol	string		BTC
total_supply	string (fixed8)	In decimal form, e.g. 1.00000000	0.00000000
token_type	integer	Type of the mini token
owner	string (address)	Address
mintable	boolean	mintable
token_uri	string	URI for token description
contract_address	string	smart contract address for this token
contract_decimals	int	the token decimals