Skip to main content

HTTP API

Within the ecosystem of BNB Becon Chain, there are several accelerated nodes which provides more secure and faster lines to access BNB Beacon 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

Responses

CodeDescriptionSchema
200SuccessTimes
400Bad RequestError
404Not Found
defaultGeneric error responseError

/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

Responses

CodeDescriptionSchema
200SuccessResultStatus

/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

Responses

CodeDescriptionSchema
200Success[ Validators ]
400Bad RequestError
404Not Found
defaultGeneric error responseError

/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

Responses

CodeDescriptionSchema
200Success[ Peer ]
400Bad RequestError
404Not Found
defaultGeneric error responseError

/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

Parameters

NameLocated inDescriptionRequiredSchema
addresspathThe account address to queryYesstring

Responses

CodeDescriptionSchema
200SuccessAccount
400Bad RequestError
404Not FoundError
defaultGeneric error responseError

/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

Parameters

NameLocated inDescriptionRequiredSchema
addresspathThe account address to queryYesstring

Responses

CodeDescriptionSchema
200SuccessAccountSequence
400Bad RequestError
404Not Found
defaultGeneric error responseError

/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

NameLocated inDescriptionRequiredSchema
hashpathThe transaction hash to queryYesstring
formatqueryResponse format (json or amino)Nostring

Responses

CodeDescriptionSchema
0SuccessTransaction
404Not Found
500Bad RequestError
defaultGeneric error responseError

/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

Parameters

NameLocated inDescriptionRequiredSchema
limitquerydefault 100.Nointeger
offsetquerystart with 0; default 0.Nointeger

Responses

CodeDescriptionSchema
200Success[ Token ]
400Bad RequestError
404Not Found
defaultGeneric error responseError

/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

Responses

CodeDescriptionSchema
200Success[ Fee ]
defaultGeneric error responseError

/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

Parameters

NameLocated inDescriptionRequiredSchema
syncquerySynchronous broadcast (wait for DeliverTx)?Noboolean
bodybodyYesbinary

Responses

CodeDescriptionSchema
200Success[ Transaction ]
400Bad RequestError
401Bad SignatureError
404Not Found
defaultGeneric error responseError

/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

NameLocated inDescriptionRequiredSchema
addressquerythe seller/buyer addressNostring
endqueryend timeNolong
limitquerydefault 50; max 1000.Nointeger
offsetquerystart with 0; default 0.Nointeger
startquerystart time in MillisecondsNolong
totalquerytotal number required, 0 for not required and 1 for required; default not required, return total=-1 in responseNointeger

Responses

CodeDescriptionSchema
200OKBlockExchangeFeePage

/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

NameLocated inDescriptionRequiredSchema
addressqueryaddressYesstring
blockHeightqueryblockHeightNolong
endTimequeryendTime in MillisecondsNolong
limitquerylimitNointeger
offsetqueryoffsetNointeger
sidequerytransaction side. Allowed value: [ RECEIVE, SEND]Noenum string
startTimequerystart time in MillisecondsNolong
txAssetquerytxAssetNostring
txTypequerytransaction 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]Noenum string

Responses

CodeDescriptionSchema
200OKTxPage
400Bad RequestError
404Not Found
403Tx is not within 24h query window
defaultGeneric error responseError

/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

NameLocated inDescriptionRequiredSchema
blockHeightpathblock heightYesstring

Responses

CodeDescriptionSchema
200OKBlockTx
400Bad Request. The block to query is higher than current highest block.Error
404Not Found
defaultGeneric error responseError

/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

NameLocated inDescriptionRequiredSchema
blockHeightpathblockHeightYeslong

Responses

CodeDescriptionSchema
200OKBlockTxV2
400Bad 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

NameLocated inDescriptionRequiredSchema
endTimequeryend time of blockTimestampNolong
fromAddressqueryAt least one of toAddress and fromAddress should be provided as parameterNostring
limitquerydefault 25; max 1000.Nointeger
offsetquerystart with 0; default 0.Nointeger
startTimequerystart time of blockTimestamp in Milliseconds; The maximum start - end query window is 3 months; Default query window is the latest 30 days.Nolong
toAddressqueryAt least one of toAddress and fromAddress should be provided as parameterNostring

Responses

CodeDescriptionSchema
200OKAtomicSwapPage

/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

NameLocated inDescriptionRequiredSchema
idpathswap idYesstring

Responses

CodeDescriptionSchema
200OKAtomicSwap

/api/v1/timelocks/{address}​


GET​

Summary: Gets time lock records given an address

Parameters

NameLocated inDescriptionRequiredSchema
addresspathThe account address to queryYesstring
idquerythe record id of timelock to queryNolong

Responses

CodeDescriptionSchema
200SuccessTimeLocks
400Bad RequestError
500internal server errorError

/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

NameLocated inDescriptionRequiredSchema
addresspathThe account address to queryYesstring
idquerythe record id of timelock to queryNolong

Responses

CodeDescriptionSchema
200SuccessTimeLocks
400Bad RequestError
404Not Found
500internal server errorError

/api/v1/mini/tokens​


GET​

Summary: Gets a list of available mini tokens.

Parameters

NameLocated inDescriptionRequiredSchema
offsetqueryoffsetNointeger
limitquerylimitNointeger

Responses

CodeDescriptionSchema
200SuccessMiniTokens
400Bad RequestError
500internal server errorError

Models​


Error​

NameTypeDescriptionExample
codelongerror code400
messagestringerror message

Times​

NameTypeDescriptionExample
ap_timestringevent timee.g. 2019-01-21T10:30:00Z
block_timestringthe time of latest blocke.g. 2019-01-21T10:30:00Z

Validators​

NameTypeDescriptionExample
block_heightlongCurrent block height12345
validators[ Validator ]

Validator​

NameTypeDescriptionExample
addressstring (hex address)Address
pub_key[ integer ]Public key bytes
voting_powerintegervalidator's voting power
accumintegervalidator's accumulated voting power

Peer​

NameTypeDescriptionExample
idstringAuthenticated identifier8c379d4d3b9995c712665dc9a9414dbde5b30483
original_listen_addrstring (RemoteAddr)Original listen address before PeersService changed it
listen_addrstring (RemoteAddr)Listen address
access_addrstring (RemoteAddr)Access address (HTTP)
stream_addrstring (RemoteAddr)Stream address (WS)
networkstringChain IDBinance-Chain-Ganges
versionstringVersion0.30.1
monikerstringMoniker (Name)data-seed-1
capabilities[ string ]Array of capability tags: node, qs, ap, wsnode,ap
acceleratedbooleanIs an accelerated path to a validator node

Transaction​

NameTypeDescriptionExample
hashstring (hex)Hash of transaction, it returned as bytes before, and now it returns as hex string
logstringLog of transaction
datastringData of transaction
heightstringHeight of transaction
codeintegerResult code of transaction
okboolean
txobjectDetail 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​

NameTypeDescriptionExample
account_numberinteger
addressstring (address)
balances[ Balance ]
public_key[ integer ]Public key bytes
sequencelongsequence is for preventing replay attack

AccountSequence​

NameTypeDescriptionExample
sequencelongnumber used for preventing replay attack1

Balance​

NameTypeDescriptionExample
symbolstring (currency)asset symbolBNB
freestring (fixed8)In decimal form, e.g. 0.000000000.00000000
lockedstring (fixed8)In decimal form, e.g. 0.000000000.00000000
frozenstring (fixed8)In decimal form, e.g. 0.000000000.00000000

Token​

NameTypeDescriptionExample
namestringtoken nameBNB Chain Native Token
symbolstringunique token trade symbolBTC-000
original_symbolstringtoken symbolBTC
total_supplystring (fixed8)total token supply in decimal form, e.g. 1.000000000.00000000
ownerstring (address)Address which issue the token
contract_addressstringsmart contract address for this token
contract_decimalsintthe token decimals

Fee​

NameTypeDescriptionExample
msg_typestringTransaction msg type that this fee applies tosubmit_proposal
feenumberThe fee amount1000000000
fee_forinteger1 = proposer, 2 = all, 3 = free1
multi_transfer_feestringFee for multi-transfer200000
lower_limit_as_multistringe.g. 22
fixed_fee_paramsFixedFeeParamsSet if the fee is fixed
dex_fee_fieldsDexFeeFieldParamsdex fee

FixedFeeParams​

NameTypeDescriptionExample
msg_typestringTransaction msg type that this fee applies tosubmit_proposal
feenumberThe fixed fee amount1000000000
fee_forinteger1 = proposer, 2 = all, 3 = free1

DexFeeFieldParams​

NameTypeDescriptionExample
fee_namestringfee name
fee_valueintegerfee value

SubTx​

NameTypeDescriptionExample
blockHeightlong
fromAddrstring
toAddrstring
txAssetstring
txFeestring
txHashstring
txTypestring
valuestring

BlockExchangeFeePage​

NameTypeDescriptionExample
blockExchangeFee[ BlockExchangeFee ]
totallong

BlockExchangeFee​

NameTypeDescriptionExample
addressstring
blockHeightlong
blockTimelongtimestamp of a block
feestringtotal fee collected. Multiple assets are split by semicolon.
tradeCountlongtrade count of the address on the block

TxPage​

NameTypeDescriptionExample
totallongtotal sum of transactions
tx[ Tx ]

BlockTx​

NameTypeDescriptionExample
blockHeightlongblock height
tx[ Tx ]

BlockTxV2​

NameTypeDescriptionExample
blockHeightlongblock height
tx[ TxV2 ]

Tx​

NameTypeDescriptionExample
blockHeightlongblock height
codeintegertransaction result code0
confirmBlockslong
datastring
fromAddrstringfrom address
orderIdstringorder ID
timeStampdateTimetime of transaction
toAddrstringto address
txAgelong
txAssetstring
txFeestring
txHashstringhash of transaction
txTypestringtype of transaction
valuestringvalue of transaction
sourcelong
sequencelong
swapIdstringOptional. Available when the transaction type is one of HTL_TRANSFER, CLAIM_HTL, REFUND_HTL, DEPOSIT_HTL
proposalIdstring

ExchangeRate​

NameTypeDescriptionExample
ExchangeRateobject

ResultStatus​

NameTypeDescriptionExample
validator_info[ ValidatorInfo ]
sync_info[ SyncInfo ]
node_info[ NodeInfo ]

NodeInfo​

NameTypeDescriptionExample
Protocol_Version[ ProtocolVersion ]
IDstring
listen_addrstring
networkstring
versionstring
channelsstring
monikerstring
otherobject

SyncInfo​

NameTypeDescriptionExample
latest_block_hashstring (hex)
latest_app_hashstring (hex)
latest_block_heightlong
latest_block_timetime
catching_upboolean

ProtocolVersion​

NameTypeDescriptionExample
P2Pinteger (uint64)
blockinteger (uint64)
appinteger (uint64)

ValidatorInfo​

NameTypeDescriptionExample
addressstringhex address
pub_keystringhex-encoded
voting_powerlong

AtomicSwapPage​

NameTypeDescriptionExample
atomicSwaps[ AtomicSwap ]
totallong

AtomicSwap​

NameTypeDescriptionExample
blockTimestamplongTimestamp of block in which the swap is initiated. The unit is millisecond.
closedTimelong
crossChaininteger
expectedIncomestring
expireHeightlong
fromAddrstring
inAmountstring
outAmountstring
randomNumberstring
randomNumberHashstring
recipientOtherChainstring
statusinteger
swapIdstring
timestampstring (int64)The timestamp for randomNumberHash calculation, randomNumberHash=sha256(randomNumber, timestamp). The unit is second.
toAddrstring

TxV2​

NameTypeDescriptionExample
blockHeightlong
codeinteger0
datastring
fromAddrstring
memostring
orderIdstringOptional. Available when the transaction type is NEW_ORDER
proposalIdstringOptional. Available when the transaction type is PROPOSAL
sequencelong
sourcelong
subTransactions[ SubTx ]Optional. Available when the transaction has sub-transactions, such as multi-send transaction or a transaction have multiple assets
swapIdstringOptional. Available when the transaction type is one of HTL_TRANSFER, CLAIM_HTL, REFUND_HTL, DEPOSIT_HTL
timeStampdateTime
toAddrstring
txAssetstring
txFeestring
txHashstring
txTypestring
valuestring

TimeLocks​

NameTypeDescriptionExample
idlongThe record id of the timelock transaction
descriptionstringThe description of the timelock transaction
amount[ ]
locktimestringThe available unlock time

MiniTokens​

NameTypeDescriptionExample
namestringBNB Chain Mini Token
symbolstringBTC-000
original_symbolstringBTC
total_supplystring (fixed8)In decimal form, e.g. 1.000000000.00000000
token_typeintegerType of the mini token
ownerstring (address)Address
mintablebooleanmintable
token_uristringURI for token description
contract_addressstringsmart contract address for this token
contract_decimalsintthe token decimals