BNB Chain Wallet API

Wallet Management

The API can generate new wallets with BIP39 seed phrases or restore an existing wallet from a seed phrase. It also provides a separate endpoint for generating a 12-word BIP39 seed phrase without creating a wallet.

Balance and Token Discovery

The balance endpoint retrieves the native BNB balance together with token balances for a wallet address. By default, the API checks six popular BEP-20 tokens. When a BSCScan API key is available, it can additionally perform full token discovery. The project also includes a curated list of popular BEP-20 token contracts.

Transactions

The API supports sending both native BNB and BEP-20 tokens. Transactions are built and signed using the provided private key and submitted to BNB Chain. After submission, their status can be checked using the transaction hash. The transaction status endpoint distinguishes between pending, successful, failed, and not-found transactions.

Architecture

The project follows a simple layered architecture:

Routes → Services → Adapters

Routes handle request validation and responses, services contain the application logic, and adapters handle communication with external blockchain services such as BSC RPC and BSCScan. This keeps blockchain-specific operations separate from the API layer and business logic.

API

The main API operations include:

• Create or restore a wallet

• Generate a BIP39 seed phrase

• Retrieve BNB and token balances

• Discover tokens through BSCScan

• Send BNB or BEP-20 tokens

• Check transaction status

• Retrieve curated token contract addresses

• Check API health

Security

Private keys and seed phrases are sensitive credentials. The API receives them directly in requests and does not store wallet data on the server. Because of this design, the API should only be exposed on trusted networks unless additional security controls are implemented. CORS is open by default and should be restricted when deploying the API to a public environment.

Tech Stack

• FastAPI — asynchronous REST API framework

• Web3.py — interaction with BNB Chain through RPC

• eth-account — wallet creation and transaction signing

• mnemonic — BIP39 seed phrase generation

• BSCScan API — token discovery

Result

The result is a compact REST API that covers the core operations required to interact with BNB Chain wallets: generating and restoring wallets, retrieving native and token balances, sending transactions, and monitoring their status. The project also demonstrates how blockchain-specific operations can be isolated behind adapters while keeping the API and business logic separated.