bnbchain

---
name: bnbchain
slug: bnbchain
source: clawhub
description: interact with bnb chain mcp server. blocks, contracts, tokens, nfts, wallet, greenfield, erc-8004 agent tools.
---

# bnbchain

## intent

use the bnb chain model context protocol (mcp) server to query blockchain data and execute transactions on bsc, opbnb, ethereum, base, polygon, and other evm-compatible networks. read block info, balances, contract state, token/nft metadata. write transactions, approve token spending, transfer assets, register erc-8004 agents, and manage greenfield buckets and objects. use this skill when you need deterministic on-chain reads, need to sign and broadcast transactions, or need to interact with decentralized storage. never run this without understanding the network you're targeting and whether a transaction is destructive.

## inputs

### external connections

**bnb chain mcp server:** npx @bnb-chain/mcp@latest. fetches from npm registry at install time. audit the source code at https://github.com/bnb-chain/bnbchain-mcp before use if you need to review dependencies or signing logic.

### environment variables

**PRIVATE_KEY** (optional but required for writes): hex-encoded private key for signing transactions, approvals, contract writes, erc-8004 registration, and greenfield operations. set in the mcp server's environment (e.g. in your claude/cursor mcp config), not passed as a chat parameter or stored in version control. the server uses it only to sign; it does not log, store, or transmit the key. omit this if you only need read-only access (blocks, balances, contract reads, nft metadata).

**RPC endpoints:** the mcp server uses public rpc endpoints for bsc, opbnb, ethereum, base, polygon, and greenfield by default. no configuration needed unless you self-host or override with custom rpc urls.

### supported networks

use get_supported_networks to list all available networks. common networks: bsc (mainnet), bsc-testnet, opbnb (mainnet), ethereum, ethereum-sepolia, base, base-sepolia, polygon, polygon-mumbai, greenfield (storage chain).

### user inputs required

- network name (e.g. "bsc", "ethereum", "base-sepolia"): mandatory for any write operation (transfer, contract write, approve, erc-8004 register, greenfield create/upload). optional for reads; defaults to bsc if omitted.
- recipient address or contract address: for transfers and approvals.
- amounts, token addresses, contract abi, function parameters: context-specific; see procedure.
- agentURI (json metadata url): required for erc-8004 registration; must follow the agent metadata profile at https://best-practices.8004scan.io/docs/01-agent-metadata-standard.html.

## procedure

### 1. verify the network and private key availability

**inputs:** user intent (read-only or write), desired network name.

**steps:**
- if the user requests a write operation (transfer, approve, write_contract, register_erc8004_agent, greenfield create/upload/delete), ask the user to confirm the network name explicitly. do not assume or default to bsc or mainnet.
- confirm that PRIVATE_KEY is set in the mcp server environment if writes are needed. if the user reports "tool failed" or "no signer", PRIVATE_KEY is likely missing; guide them to set it in their mcp config.
- if the user only needs reads (get_block, get_balance, read_contract, get_nft_info), network is optional and defaults to bsc.

**outputs:** confirmed network name (string), confirmation that private key is available (boolean, only for writes).

**edge cases:**
- user specifies mainnet without understanding the risk: warn explicitly that testnet is safer for development.
- network name is invalid or not in supported list: call get_supported_networks and show the user valid options.
- user wants to write but has not generated or provided a wallet: offer to generate a new wallet and fund it on testnet first.

### 2. call the appropriate tool

**inputs:** tool name, network (if required), parameters (address, amount, abi, etc.).

**steps:**
- select the tool from the available tools table below, e.g. get_block_by_number, transfer_native_token, read_contract, gnfd_upload_object.
- pass network as a parameter for writes; omit or use default (bsc) for reads unless the user specifies otherwise.
- for transfers: pass recipient, amount, network. the tool derives the sender from PRIVATE_KEY.
- for contract writes: pass contract address, function name, parameters, abi (or let the tool infer), network.
- for erc-8004 registration: pass agentURI, network. the tool returns an agent ID.
- for greenfield operations: pass bucket name, object name, file data (upload), network. greenfield uses the same PRIVATE_KEY for auth.

**outputs:** transaction hash (for writes), data (for reads), or error message.

**edge cases:**
- rate limiting: if the rpc endpoint returns a 429 or rate limit error, wait 5-10 seconds and retry.
- insufficient gas: estimate_gas before sending. if gas estimate fails, the recipient or contract may not exist, or network may be misconfigured.
- invalid abi: read_contract and write_contract require a valid json abi matching the contract. if the abi is missing or malformed, the tool will fail; fetch the abi from a block explorer (e.g. bscscan, etherscan) and re-call.
- expired signature / nonce mismatch: if a write tool fails with "nonce too low" or "signature expired", the account may have multiple pending transactions or the network may have reorged; wait a few seconds and retry, or check the latest nonce via web3.
- empty result sets: get_nft_balance, get_erc20_balance, and similar read tools return 0 or empty arrays if the address holds no tokens; this is not an error.
- network timeout: if the rpc endpoint is unreachable, the tool will timeout after ~30 seconds; catch the timeout and suggest retrying with a different rpc or checking network status.

### 3. interpret and present the result

**inputs:** tool output (transaction hash, data, error, or null).

**steps:**
- for writes (transfer, approve, write_contract, erc-8004 register, greenfield create): present the transaction hash and a link to the block explorer (e.g. https://bscscan.com/tx/{hash} for bsc).
- for reads (get_balance, get_nft_info, read_contract): parse the return value (number, string, object, array) and explain it in plain language.
- for erc-8004 registration: present the agent ID and a link to check registration: https://www.8004scan.io/ (mainnet) or https://testnet.8004scan.io/ (testnet).
- for greenfield: present the bucket/object name and storage status.

**outputs:** human-readable summary, explorer links, next steps if applicable.

**edge cases:**
- user calls a read tool but gets "private key missing" error: this indicates the tool internally requires a write capability (e.g. a view function that reads private storage); clarify with the tool author or use a different tool.
- tool returns hex-encoded data instead of decoded values: this can happen if the abi is missing or incorrect; offer to help decode the hex using the abi.

### 4. confirm receipt and finality (writes only)

**inputs:** transaction hash, network.

**steps:**
- after a write operation, offer to check the transaction status via get_transaction_receipt.
- poll the receipt until status is "success" (1) or "failed" (0).
- if success, the transaction is mined and state is finalized on bsc/opbnb (instant) or ethereum/base (12+ block confirmations).
- if failed, parse the revert reason and explain why (insufficient balance, contract reverted, etc.).

**outputs:** confirmation of finality, or error reason.

**edge cases:**
- transaction is pending for >5 minutes: the network may be congested or the gas price may be too low. offer to check mempool status or speed up the tx via a replacement transaction (if supported by the network and wallet).
- transaction is dropped from mempool: the nonce may be out of order or the sender's account was reset; advise the user to check the latest nonce and resubmit.

### available tools reference

**read-only (no private key needed):**
- get_block_by_hash, get_block_by_number, get_latest_block
- get_transaction, get_transaction_receipt, estimate_gas
- get_chain_info, get_supported_networks
- is_contract, resolve_ens
- get_address_from_private_key (derives address from a private key without signing)
- read_contract (calls a view/pure function)
- get_erc20_token_info, get_native_balance, get_erc20_balance
- get_nft_info, check_nft_ownership, get_nft_balance
- get_erc1155_token_metadata, get_erc1155_balance
- get_erc8004_agent, get_erc8004_agent_wallet
- gnfd_get_bucket_info, gnfd_list_buckets, gnfd_get_object_info, gnfd_list_objects, gnfd_get_account_balance, gnfd_get_payment_account_info, gnfd_get_payment_balance

**state-changing (require private key in environment):**
- transfer_native_token (network required)
- transfer_erc20 (network required)
- transfer_nft (network required)
- transfer_erc1155 (network required)
- approve_token_spending (network required)
- write_contract (network required)
- register_erc8004_agent (network required)
- set_erc8004_agent_uri (network required)
- gnfd_create_bucket, gnfd_delete_bucket, gnfd_upload_object, gnfd_download_object, gnfd_delete_object, gnfd_create_folder (all require network and greenfield auth)
- gnfd_deposit_to_payment, gnfd_withdraw_from_payment, gnfd_disable_refund, gnfd_create_payment (all require network)

## decision points

**read-only vs. state-changing:**
- if the user asks for a balance, block info, contract state, or metadata (nft, token, agent info), use read-only tools. no private key needed.
- if the user wants to transfer, approve, write contract state, register an agent, or manage greenfield storage, use state-changing tools. private key must be in the mcp server environment.

**network selection for writes:**
- if the user specifies a network explicitly (e.g. "on bsc mainnet", "on base-sepolia"), use it and pass it to the tool.
- if the user does not specify a network and requests a write, ask the user to confirm the network name before calling the tool. do not default to bsc or any mainnet. offer testnet as the safe default for development.
- if the user specifies mainnet for a high-value transaction without context, warn them and ask for confirmation.

**private key availability:**
- if a write tool fails with "no signer" or "private key not found", the PRIVATE_KEY env var is missing. guide the user to set it in their mcp config (e.g. in claude/cursor settings, under "env" for the bnbchain-mcp server).
- if the user wants to write but has not set up a wallet, offer to help generate one and fund it on testnet.

**erc-8004 agent registration workflow:**
- if the user is an ai agent and wants to be discoverable via the erc-8004 identity registry, call register_erc8004_agent with an agentURI (json metadata file). the tool returns an agent ID.
- after registration, inform the user to check https://www.8004scan.io/ (mainnet) or https://testnet.8004scan.io/ (testnet) to verify registration.
- if the user later wants to update metadata, call set_erc8004_agent_uri (owner only).

**greenfield storage:**
- if the user needs to store files on-chain (not just read them), use gnfd_create_bucket and gnfd_upload_object. these require network and private key.
- if the user needs to manage payments for greenfield storage, use gnfd_deposit_to_payment and gnfd_get_payment_balance.
- gnfd_disable_refund is irreversible; confirm before calling.

**error handling and retry:**
- if estimate_gas fails, the transaction is likely invalid (bad recipient, contract revert, etc.); do not call transfer_native_token or write_contract without fixing the underlying issue.
- if a transaction fails on-chain (status 0 in receipt), parse the revert reason and explain what went wrong. do not retry automatically; ask the user to fix the issue first.
- if an rpc endpoint is slow or returns a rate limit error, wait 5-10 seconds and retry. if the error persists, suggest checking network status or using a different rpc.

## output contract

**for read operations:**
- return a structured json object (parsed from the blockchain) or a formatted text summary.
- include block number, timestamp, contract state, balance, token metadata, or nft info as applicable.
- include a direct link to the block explorer (e.g. bscscan.com, etherscan.io) if relevant.

**for write operations:**
- return the transaction hash (40 hex chars, prefixed with 0x).
- include a block explorer link in the format: https://{network-domain}/tx/{hash}.
- for erc-8004 registration, also return the agent ID.
- for greenfield operations, return the bucket/object name and storage status.

**for errors:**
- return the error type (rpc error, invalid abi, insufficient gas, nonce mismatch, rate limit, timeout) and a plain-language explanation.
- suggest the corrective action (set env var, confirm network, fetch abi, wait and retry, increase gas price, etc.).

**file locations:** no files are written to disk by this skill. all data is on-chain or returned to the user in chat.

## outcome signal

- **read-only operations:** the user can see the blockchain data (balance, block, contract state, nft metadata) printed in chat. they can verify it by clicking the explorer link and checking on-chain.
- **write operations:** the user receives a transaction hash and can watch it confirm on the block explorer. after confirmation, the on-chain state changes (balance transfers, contract state updates, agent registration visible on 8004scan.io, greenfield object stored).
- **private key setup:** if a write fails with "no signer", the outcome signal is the user setting PRIVATE_KEY in their mcp config and retrying. after successful retry, the transaction hash appears.
- **network confirmation:** if the user doesn't specify a network for a write, the outcome signal is the user confirming the network name so you can call the tool safely.
- **erc-8004 registration:** the outcome signal is the agent ID returned by register_erc8004_agent, and the user seeing their agent listed on https://www.8004scan.io/ or https://testnet.8004scan.io/ within 1-2 blocks.
- **greenfield storage:** the outcome signal is the bucket/object name confirmed as created or uploaded, and a link to check storage status.

---

**credits:** bnb chain mcp server authors and community. source: https://github.com/bnb-chain/bnbchain-mcp.