Bscscan API migration and queries by data type

Bscscan API migration replaces deprecated programmatic endpoints with Etherscan V2 queries for BNB Smart Chain data. Use chainid=56 for mainnet and choose the action by the record you need: balance for native BNB, tokenbalance for a specified ERC-20-compatible token, txlist for normal transactions or a token-transfer action for movement records. V2 requests require an Etherscan API key, and BNB Smart Chain account and transaction access depends on an eligible paid plan. Source-code and ABI retrieval have a Free-tier exception. The migration concerns the API service; balances, transaction records and contract interfaces still answer different questions.

Updated on

Bottom line: The value field represents native BNB units in normal-transaction records and token units in fungible-transfer records.

Which V2 query matches the data you need?

A balance endpoint answers a holdings question, a normal-transaction endpoint describes an outer transaction and a transfer endpoint describes token movement. These categories share an address or transaction hash without returning interchangeable records. Start with the object your application needs to display or calculate, then select the matching module and action.

Contract endpoints supply published code and interface definitions. Receipts expose execution details, while logs retain event records for decoding. Balance results are integer strings, history results are arrays and ABI results contain a JSON-encoded interface. Preserve these output types when replacing a legacy parser.

Balances and transfers in a worked comparison

A token-balance query reports holdings, while a token-transfer query reports movement inside the requested history window. In this hypothetical comparison, use the same BNB Smart Chain address and ERC-20-compatible token contract, with 3 token decimals. Assume successful queries return a latest balance of 13,728 raw units and an incoming transfer of 5848 raw units within the selected block range.

Dividing the 13,728 raw balance units by 1000 gives 13.728 tokens held. The same conversion turns the incoming transfer’s 5848 raw units into 5.848 tokens. The tokenbalance quantity describes holdings, while the tokentx quantity describes movement. That event alone does not explain the whole holding; earlier activity can account for a different balance.

A different decimal setting rescales both displayed amounts. Changing the history window changes the transfer records included, while the balance query retains its own state selection. The comparison only holds for the same contract and network, with the stated decimal setting.

Build the V2 request around the correct chain

Etherscan V2 uses HTTP GET requests with query parameters for the chain, module, action and API key. BNB Smart Chain mainnet uses chain ID 56. Set chainid=56 for that network. Match module to the endpoint family and action to its operation, then supply the required account address, contract address or transaction hash. Moving to V2 also requires the unified service and an Etherscan API key.

Replacing the key alone leaves a legacy integration pointed at its deprecated service. Changing only the service leaves chain selection and authentication unresolved. Preserve parameter names and their casing, including contractaddress where the endpoint requires it. The API key belongs in private application configuration; redact it from shared request records.

Graphic: Build the V2 request around the correct chain (Bscscan)

View image file

Native BNB and contract-token balances

Native balances use action=balance ; balances for a specified ERC-20-compatible token use action=tokenbalance , both under the account module.

Native BNB units

The native-balance endpoint queries an address at a selected state, using a tag such as latest . Its result is a decimal integer string in wei. On BNB Smart Chain, divide that integer by 10^18 to express the balance in BNB. Retain integer precision during parsing, especially when the raw quantity exceeds your programming language’s exact-number range.

Token-contract units

The token-balance endpoint also requires contractaddress , which identifies the token whose holdings the query returns. Convert raw token units using amount / 10^d , where d is that contract’s decimal setting. The ERC-20 standard makes the decimals method optional, so missing metadata does not justify assuming BNB’s decimal count. Store the raw amount when the display scale remains unknown.

Normal transactions and internal activity

Transaction-history queries separate signed outer transactions from indexed internal activity, so the requested record determines the appropriate action.

Outer transaction records

action=txlist returns normal transactions associated with an address. Its records include the sender, recipient, native value and execution-related fields. When to contains a contract address, it identifies the direct destination of the outer call. A contract call can generate token-transfer records with different recipients, so an application should not treat the outer destination as a token recipient.

Internal activity records

action=txlistinternal returns internal activity indexed for the selected address and block range. Records have their own fields, including a call type, traceId and error information. Keep them distinct from signed outer transactions when storing or counting activity. An outer transaction and its internal records describe related execution at different levels; combining their counts does not measure unique outer transactions.

Fungible, NFT and multi-token transfer endpoints

Transfer endpoints classify movement by token standard, and their quantity and identifier fields carry different meanings across those standards.

Fungible-token movements

action=tokentx returns ERC-20 transfer records with account addresses, a token contract and raw transfer values. On BNB Smart Chain, this is the relevant API category for compatible fungible-token transfers. The record’s value describes a token movement; the normal-transaction endpoint’s identically named field describes native value. Keep the endpoint type attached to the field in storage.

Individual NFT movements

action=tokennfttx returns ERC-721 transfers of non-fungible tokens (NFTs). A tokenID identifies the NFT within its contract; it is not an amount to divide by decimal precision. Group NFT identifiers with their chain and contract address, because a token ID alone does not identify an asset across separate collections.

ERC-1155 token quantities

action=token1155tx returns ERC-1155 transfers with both tokenID and tokenValue . ERC-1155 allows a contract to manage multiple token types, including fungible and non-fungible configurations. The ID selects the type, while the value describes its transferred quantity. Preserve those meanings instead of treating every record as one indivisible NFT.

Receipts and event logs

A receipt query returns execution details for one transaction, while a log query selects emitted events by contract and block range. Use module=proxy with action=eth_getTransactionReceipt and txhash for the receipt. It includes the transaction’s execution status, gas usage and logs. That status concerns on-chain execution, distinct from an account endpoint’s data-query status.

module=logs with action=getLogs returns event records using address , fromBlock and toBlock . These parameter names differ from the account-history filters. Topics and data need the matching event definition for decoding. Multiple logs can share a transaction hash, so event storage also needs the log index. This detail matters when counting movements without collapsing different events from the same transaction.

Contract source and ABI retrieval

Contract queries return code or interface information, while account queries return chain activity or holdings. With module=contract , choose action=getsourcecode for published contract source information or action=getabi for the application binary interface (ABI). The ABI describes callable functions and event layouts. It can describe token approval methods alongside balance and transfer methods, without reporting their current values.

The ABI endpoint returns a JSON-encoded string inside its result, so applications need to parse that string after parsing the response. It only supplies an ABI for a verified contract. Source-code results may also include compiler settings and proxy implementation information. Those fields support interpretation of the contract interface; retrieving them does not certify its safety or transfer behavior.

Block ranges, sorting and pagination

Block boundaries and pagination define the history a request returns, so a successful first page can represent only part of the selected range. Account transaction and transfer queries use startblock and endblock to bound the search. The page parameter selects a page, and offset sets its record count subject to the endpoint’s limits. Sorting with asc starts with older records; desc starts with newer ones. Use a fixed block range for a bounded export, and retain the selected sort order across its pages. A query timeout may require a smaller range. Keep page completion separate from the unrelated question of an address’s current balance.

Plan access and response errors

BNB Smart Chain account and transaction queries require paid API access, while source-code and ABI endpoints retain a Free-tier exception. Access depends on both the chosen network and endpoint. Successful source retrieval therefore does not establish access to balance or history queries. PRO endpoint availability is a separate plan entitlement. Rate limits and request allowances also follow the service plan, so schedule calls within its permitted throughput.

For account and contract responses, inspect status , message and result together. A status of 0 can indicate an error or an empty result.

Proxy responses use a JSON-RPC-shaped envelope, so the same parser cannot assume every V2 action returns identical fields. Authentication errors, access restrictions and timeouts require different handling. A valid empty history concerns the selected filters; an invalid key or plan refusal says nothing about account activity. Preserve the original error text so a failed query does not become a fabricated zero balance.

RPC alternatives and endpoint coverage

BSCTrace via MegaNode provides a separate BNB Smart Chain API route using JSON-RPC requests over HTTP POST. Its eth_getBalance returns a hexadecimal quantity, while the V2 account-balance action returns a decimal integer string. Both represent native balance in the network’s smallest unit, so their parsers must handle different encodings. Standard balance and receipt methods do not provide an indexed address-wide transaction list. Enhanced transfer APIs have their own categories and filters. Available migration mappings do not make every indexed endpoint interchangeable. Choose the integration whose data types, units and endpoint coverage match the application. Handle contract verification separately if the selected API does not provide that service.

Bscscan FAQ

Can a V2 request contain several chain IDs?

A V2 data query accepts one chain ID per request. A comma-separated set of IDs does not request a combined result and can trigger a missing-or-unsupported-chain error. Keep each request tied to its selected network when assembling data from multiple chains. Reusing an API key does not combine their records.

Why can a newly created Etherscan key fail during a Bscscan API migration?

A newly created Etherscan API key can take a few minutes to activate. During that interval, a correctly formed request may still receive an invalid-key error. V2 requires an Etherscan key, so a legacy chain-specific key is a separate credential problem. An activation delay does not resolve an endpoint’s plan restriction.

When should a native-balance query use a historical endpoint?

On mainnet with the Standard plan or above, use the historical native-balance endpoint when the required block lies outside the recent range accepted by the ordinary balance action. The standard endpoint accepts a hexadecimal block tag within the last 128 blocks, as well as latest. Historical queries have their own parameters and access conditions; changing the tag alone does not make the standard action an unrestricted archive query.

Will a token-transfer response include the original transaction input?

Token-transfer responses mark the input field as deprecated. Normal-transaction records expose an input field for the outer call. Token movement and call data answer different questions: the transfer record describes the event, while input describes the transaction’s encoded instructions. For calls with arguments, the method name or selector alone cannot reconstruct their encoded values.

How does testnet selection affect a BNB Smart Chain V2 migration?

BNB Smart Chain testnet uses chain ID 97, while mainnet uses chain ID 56. The selected environment determines which balances, contracts and transactions a query addresses. Testnet records do not confirm mainnet activity, even when an address string matches. PRO endpoints support mainnet environments, so a testnet integration must use endpoints available on testnet.

Does token-transfer history reveal a contract’s current spending allowance?

Token-transfer history does not report the current ERC-20 allowance for an owner and spender. Allowance is separate contract state, and a recorded movement does not establish the permission remaining afterward. An application displaying spending permissions needs the relevant allowance state, not a total of transfer values.

Can a token-contract filter work without an account address?

The tokentx endpoint accepts contractaddress without address to list transfers for a selected token contract. At least one of those filters must be present. A contract-wide query can cover different holders within its block range, so its records describe token activity rather than one account’s complete transaction history.