BSC API: JSON-RPC Methods, WebSocket, Finality & Examples

BSC API Quick Reference

The BSC API follows Ethereum JSON-RPC conventions on BNB Smart Chain. Mainnet uses chain ID 56 (0x38) and BNB as the native asset; testnet uses chain ID 97 (0x61) and tBNB. Because BSC is EVM-compatible, existing libraries like viem, ethers, and web3.js work with only the RPC URL changed.

OnFinality provides EVM-compatible HTTPS and WebSocket endpoints for BSC. Public mainnet: https://bnb.api.onfinality.io/public. Public testnet: https://bnb-testnet.api.onfinality.io/public. For production, create an API key and use your private endpoint from the OnFinality dashboard. Do not hardcode credentials; use environment variables.

Standard eth_* JSON-RPC Methods for BSC

The BSC API supports standard Ethereum JSON-RPC methods. The most common groups are chain info, account state, block/transaction data, contract execution, and event logs. Use these before reaching for proprietary APIs.

eth_call, eth_getLogs, Block & Transaction Retrieval, and Troubleshooting

Use eth_call for read-only contract interactions. Pass a transaction object with to and data, and a block parameter such as latest or a specific block number. The response is the encoded return data. For historical state, providers must support archive data; otherwise, calls against past blocks may fail. OnFinality BSC mainnet configuration includes archive support, but verify your plan.

eth_getLogs is central for event indexing. On the official public BNB mainnet endpoints, eth_getLogs is disabled according to BNB Chain docs; attribute that limitation to the public list and do not assume the same for OnFinality. Managed providers typically enable logs but may enforce range limits. Use block ranges and topic filters to reduce response size.

When retrieving transactions, start with eth_getTransactionByHash, then eth_getTransactionReceipt for status and logs. If you receive null, the transaction may still be pending or not yet indexed. Polling works, but WebSocket subscriptions reduce latency.

BSC-Specific Finality Methods

BNB Smart Chain implements a dual-layer finality mechanism. Economic Finality provides fast finality through a slashing mechanism, while Probabilistic Finality is fallback based on block depth. The API exposes methods to query finalized state directly.

Use eth_getFinalizedHeader to get the latest finalized block header, eth_getFinalizedBlock to get the full finalized block, and eth_newFinalizedHeaderFilter to create a filter that tracks new finalized headers. These methods help confirm irreversibility sooner than waiting for a large confirmation count. Treat them as BSC-specific extensions beyond standard Ethereum.

WebSocket Subscriptions for Real-Time Events

Use WebSocket subscriptions (eth_subscribe) for newHeads, logs, and newPendingTransactions instead of polling when your application needs low-latency updates. WebSockets maintain a persistent connection, reducing request overhead and avoiding rate-limit pressure from repeated polling.

Choose polling when events are infrequent, you need historical ranges, or the provider does not expose WSS. For high-frequency event streams such as DEX swaps or oracle updates, subscriptions are usually the better path. Implement reconnection with exponential backoff because connections can drop.

``ts import { createPublicClient, webSocket } from 'viem'; import { bsc } from 'viem/chains'; const client = createPublicClient({ chain: bsc, transport: webSocket('wss://YOUR_ONFINALITY_WS_ENDPOINT'), }); const unwatch = client.watchBlockNumber({ onBlockNumber: (blockNumber) => console.log('New block:', blockNumber), }); ``

curl and viem Examples with Safe Placeholders

Always replace placeholders with your own OnFinality endpoint and credentials. The examples below use https://bnb.api.onfinality.io/public for public read-only calls and YOUR_API_KEY for authenticated access. Never commit API keys to source control.

``bash curl -X POST https://bnb.api.onfinality.io/public \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' ``

``ts import { createPublicClient, http } from 'viem'; import { bsc } from 'viem/chains'; const client = createPublicClient({ chain: bsc, transport: http('https://bnb.api.onfinality.io/public'), }); const blockNumber = await client.getBlockNumber(); console.log(blockNumber); ``

BSC Health, Transaction, Receipt, and Trace/Debug Methods

The inspected official BSC API documentation includes eth_health to check node health, eth_getTransactionsByBlockNumber to fetch transactions by block number, and eth_getTransactionDataAndReceipt to combine transaction and receipt data in one call. Use these when they simplify your workflow; test them against your provider before relying on them.

Trace and debug methods such as debug_traceTransaction or trace_block are not part of standard JSON-RPC; availability depends on the provider. OnFinality's BNB mainnet configuration states that trace/API access is provided, but confirm the exact method names and plan eligibility from your OnFinality dashboard. Do not assume every public endpoint supports them.

Endpoint Selection and Operational Checks

When moving beyond public endpoints, evaluate providers using workload fit, method support, WebSocket availability, archive data, and finality support. Use the BNB Chain network page to compare OnFinality options: /networks/bnb.

For dedicated setup, start with the endpoint guide /rpc-assistant/bnb-smart-chain-endpoint. For provider selection, review /rpc-assistant/bnb-chain-rpc-provider. For developer workflow, use /rpc-assistant/binance-smart-chain-developer.

• Confirm mainnet chain ID 56 and testnet chain ID 97 before sending transactions.
• Test eth_getFinalizedBlock and eth_getLogs against your actual endpoint with realistic block ranges.
• Check whether your plan includes archive data for historical eth_call or trace/debug methods.
• Use WebSocket subscriptions only when real-time events justify persistent connections; otherwise poll with sensible intervals.
• Keep credentials in environment variables and rotate API keys regularly.

Frequently Asked Questions