BNB Smart Chain RPC Quickstart: Endpoint, Chain ID, and First Calls

BNB Smart Chain speaks standard Ethereum JSON-RPC. If you have connected to any EVM chain before, the same client libraries, the same method names, and the same request shape apply. What changes are the chain ID, the native token, the explorer, and a few operational details around block times and log queries. This quickstart gets you from zero to a working connection, then explains how to keep that connection healthy as your workload grows.

Chain settings you need before the first request

Get these values right and most connection problems disappear. They are the same values you paste into a wallet, a Hardhat config, or a viem client.

Use mainnet when you are deploying to production and testnet when you are iterating on contracts or testing wallet flows. Testnet BNB has no monetary value and is distributed through faucets, so treat it as a sandbox only.

Pick the right endpoint for your stage

Before you write code, decide what kind of endpoint fits the job. The wrong choice is the most common reason a quickstart turns into a debugging session.

• Local node. Full control and no third party, but you own sync time, disk, and upgrades. Reasonable for protocol work, heavy for app teams.
• Public endpoint. Fastest way to test a single request. Fine for a script or a demo, not for a production app with real traffic.
• Managed RPC API. A hosted endpoint with a stable URL, monitored nodes, and a dashboard. This is where most app teams land. OnFinality's RPC API service covers BNB Smart Chain alongside many other networks.
• Dedicated node. A node reserved for your workload when you need predictable throughput, archive access, or heavy log and trace queries. See dedicated nodes.

If you are unsure which tier fits, start with a managed endpoint and watch your request patterns for a week before committing to dedicated capacity.

Configure a wallet or client in one step

Most wallets accept a custom network. Paste the values from the table above. For a JavaScript client, viem is a compact way to confirm the connection works.

import { createPublicClient, http } from 'viem'
import { bsc } from 'viem/chains'

const client = createPublicClient({
  chain: bsc,
  transport: http('https://bnb.api.onfinality.io/public'),
})

const chainId = await client.getChainId()
const blockNumber = await client.getBlockNumber()
console.log({ chainId, blockNumber })

If chainId returns 56, your transport is pointed at mainnet. If it returns something else, you are on the wrong endpoint or the wrong network object.

Your first JSON-RPC calls with curl

Every EVM method works the same way. These three calls cover the checks you will run most often: confirm the chain, read the latest block, and read a balance.

# Confirm the chain ID
curl -s https://bnb.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# Latest block number
curl -s https://bnb.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

# Balance for an address (hex wei)
curl -s https://bnb.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"eth_getBalance","params":["0x0000000000000000000000000000000000000000","latest"]}'

eth_chainId returns 0x38, which is 56 in decimal. eth_blockNumber returns a hex block height. eth_getBalance returns wei as a hex string, so divide by 10^18 to get BNB.

Reading logs and events without timing out

eth_getLogs is the call that trips up most teams on BNB Smart Chain. The chain produces blocks quickly, so a wide block range can return a large result set and either time out or get rejected by a provider's range limit.

Practical rules:

1. Keep block ranges narrow, and paginate by block height rather than asking for everything at once.
2. Filter by contract address and topic when you can. A topic filter cuts the result set dramatically.
3. For backfills and indexers, use an archive-capable endpoint so historical state is available.
4. Cache results by block range so a retry does not re-query the same data.

const logs = await client.getLogs({
  address: '0xYourContract',
  fromBlock: 40_000_000n,
  toBlock: 40_000_500n,
})

If you need continuous event streaming instead of polling, use a WebSocket subscription where the endpoint supports it, and reconnect with backoff when the socket drops.

Testnet setup and faucet notes

Testnet uses chain ID 97 and the tBNB token. Point your client at the testnet endpoint and update the chain object so the explorer links and chain ID match.

import { bscTestnet } from 'viem/chains'

const testClient = createPublicClient({
  chain: bscTestnet,
  transport: http('https://bnb-testnet.api.onfinality.io/public'),
})

Faucets distribute small amounts of tBNB for contract deploys and transaction tests. Because faucet availability changes over time, check the current BNB Chain testnet documentation for a working faucet rather than hardcoding one. Testnet state can be reset or pruned, so never treat it as durable storage. For endpoint details, see the BNB Chain Testnet RPC page.

Failure modes and how to read them

Most quickstart failures fall into a small set of symptoms. Match the symptom to the likely cause before changing code.

When a call fails, log the full JSON-RPC error object. The code and message fields usually tell you whether the problem is your request, the endpoint, or the chain.

Production readiness checklist

A quickstart proves the connection works. Production needs a few more things in place.

• Redundant endpoints. Configure a primary and a fallback URL so a single endpoint issue does not take your app down.
• Retries with backoff. Treat transient errors as expected and retry idempotent reads.
• Monitoring. Track request success rate, latency, and error codes per method so you can see regressions early.
• Archive access. If you query historical state or backfill logs, confirm the endpoint supports it.
• Rate planning. Estimate peak requests per second and match the tier to that number. See RPC pricing for how tiers map to usage.
• Key management. Keep API keys out of client-side code and rotate them if they leak.

A simple health probe keeps you honest about endpoint quality:

curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' \
  https://bnb.api.onfinality.io/public \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'

Run this on a schedule and alert when the status code or latency drifts outside your normal range.

Where OnFinality fits

OnFinality runs BNB Smart Chain RPC as part of a broader network portfolio. You can start on a managed endpoint and move to a dedicated node when your workload needs predictable throughput or archive and trace access. The JSON-RPC surface does not change between tiers, so migrating is mostly a URL and key swap rather than a rewrite. Browse supported RPC networks to see what else is available, and use the BNB Smart Chain RPC page for current endpoint and network details.

Key Takeaways

• BNB Smart Chain mainnet uses chain ID 56 and the BNB token; testnet uses chain ID 97 and tBNB.
• The same Ethereum JSON-RPC methods work, so existing EVM tooling applies with a new endpoint and chain config.
• eth_getLogs needs narrow block ranges and filters; wide ranges are the most common source of timeouts.
• Match the endpoint tier to your stage: public for a test, managed for apps, dedicated for heavy or archive workloads.
• Production needs redundant endpoints, retries with backoff, monitoring, and a plan for archive access.

Frequently Asked Questions

What is the BNB Smart Chain chain ID? Mainnet is 56 and testnet is 97. Confirm with eth_chainId, which returns 0x38 on mainnet.

Can I use Ethereum tools on BNB Smart Chain? Yes. It is EVM-compatible, so ethers, viem, Hardhat, and Foundry work with the right chain config and endpoint.

Why does my eth_getLogs call fail? Usually the block range is too wide or the result set is too large. Narrow the range and filter by contract address and topic.

Do I need a dedicated node? Not to start. Move to a dedicated node when you need predictable throughput, archive access, or heavy trace and log queries.

How do I test without spending real BNB? Use testnet (chain ID 97) and a faucet for tBNB. Treat testnet state as temporary.

Where do I find the current endpoint? See the BNB Smart Chain RPC page for endpoint and network details, and RPC pricing for tier options.