BNB Chain Wallet API

FastAPI-based REST API for managing wallets on BNB Chain (Binance Smart Chain). Create wallets, check balances, send BNB and BEP-20 tokens, and track transactions.

Features

• Wallet creation — generate new wallets with BIP39 seed phrases or restore existing ones
• Balance checking — BNB balance + automatic token discovery (6 popular tokens by default, full discovery with BSCScan API key)
• Sending funds — send BNB (native) or any BEP-20 token
• Transaction status — check confirmation status by transaction hash
• Token contracts — curated list of popular BSC token addresses

Tech Stack

• FastAPI — async web framework
• Web3.py — blockchain RPC interaction
• eth-account — wallet creation and transaction signing
• mnemonic — BIP39 seed phrase generation

Quick Start

Local

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Docker

docker compose up -d
# or
bash rebuild.sh

Access

Resource	URL
API	http://localhost:8000
Swagger UI	http://localhost:8000/docs
Health Check	http://localhost:8000/health

Environment Variables

Variable	Required	Default	Description
BSCSCAN_API_KEY	No	—	BSCScan API key for full token discovery. Without it, only 6 popular tokens are checked.

Get a free API key at bscscan.com/apis.

API Reference

Base path: /api/v1/wallets

POST /api/v1/wallets/create

Create a new wallet or restore an existing one from a seed phrase.

Request body (optional):

{
  "seed_phrase": "word1 word2 ... word12"
}

If seed_phrase is omitted, a new random wallet is generated.

Response 200:

{
  "address": "0x...",
  "private_key": "0x...",
  "seed_phrase": "word1 word2 ... word12",
  "network": "BNB Chain (Binance Smart Chain)",
  "chain_id": 56
}

Errors: 400 — invalid seed phrase.

---

GET /api/v1/wallets/generate-seed-phrase

Generate a random 12-word BIP39 seed phrase without creating a wallet.

Response 200:

{
  "seed_phrase": "word1 word2 ... word12"
}

---

GET /api/v1/wallets/{address}/balance

Get BNB and token balances for a wallet address.

Query parameters:

Param	Type	Default	Description
use_discovery	bool	true	Enable BSCScan-based full token discovery

Response 200:

{
  "address": "0x...",
  "bnb_balance": "0.001199",
  "bnb_balance_formatted": "0.001199 BNB",
  "token_balances": {
    "USDT": {
      "amount": 14.99,
      "formatted": "14.99 USDT",
      "name": "Tether USD",
      "contract_address": "0x..."
    }
  },
  "transaction_count": 2
}

Errors: 503 — not connected to BSC.

---

POST /api/v1/wallets/send

Send BNB or BEP-20 tokens.

Request body:

{
  "to_address": "0x...",
  "amount": "0.01",
  "token_address": null,
  "private_key": "0x..."
}

Field	Type	Description
to_address	str	Recipient address (0x-prefixed, 42 chars)
amount	decimal	Amount to send
token_address	str or null	Token contract address (null for BNB native)
private_key	str	Sender's private key for signing

Response 200:

{
  "transaction_hash": "0x...",
  "from_address": "0x...",
  "to_address": "0x...",
  "amount": "0.01",
  "status": "pending"
}

Errors: 400 — validation error, 503 — connection error.

---

GET /api/v1/wallets/transactions/{transaction_hash}/status

Check the status of a transaction.

Response 200:

{
  "transaction_hash": "0x...",
  "status": "success",
  "block_number": 12345678,
  "gas_used": 21000
}

status can be: not_found, pending, success, failed.

---

GET /api/v1/wallets/tokens/contracts

Get a list of popular BEP-20 token contract addresses on BSC.

Response 200:

{
  "tokens": [
    {
      "symbol": "USDT",
      "name": "Tether USD",
      "contract_address": "0x55d398326f99059fF775485246999027B3197955",
      "decimals": 18
    }
  ]
}

Health

Method	Path	Description
GET	/	API info and available endpoints
GET	/health	Health check ({"status": "healthy"})

Project Structure

app/
├── main.py                       # FastAPI app setup, CORS, routes
├── adapters/                     # External integrations (BSC RPC, BSCScan)
│   ├── wallet_balance_checker.py # Web3 + BSCScan balance queries
│   └── wallet_sender.py          # Transaction building and signing
├── models/wallets/               # Pydantic request/response schemas
│   ├── balance_response.py
│   ├── send_funds_request.py
│   ├── send_funds_response.py
│   ├── token_contract_response.py
│   └── transaction_status_response.py
├── routes/wallets/               # API endpoint handlers
│   ├── create_wallet.py
│   ├── get_wallet_balance.py
│   ├── get_token_contracts.py
│   ├── get_transaction_status.py
│   └── send_funds.py
├── services/                     # Business logic layer
│   ├── balance/                  # Balance retrieval and formatting
│   ├── tokens/                   # Token contract metadata
│   └── transactions/             # BNB/token sending, status checking
└── utils/logger.py               # File-based logging utility

Architecture: Routes → Services → Adapters. Routes validate input and return responses, services orchestrate business logic, adapters handle blockchain interaction.

Security

• Private keys and seed phrases are sensitive — the API receives them in request bodies; run only on trusted/local networks
• No wallet data is stored server-side — the user is responsible for saving credentials
• CORS is open (*) — restrict in production
• BSCScan API key is optional but recommended for full token discovery

Dependencies

eth_account>=0.9.0    # Wallet creation and transaction signing
mnemonic>=0.20        # BIP39 seed phrase generation
web3>=6.0.0           # Blockchain RPC client
requests>=2.31.0      # BSCScan API HTTP client
fastapi>=0.104.0      # Web framework
uvicorn>=0.24.0       # ASGI server
pydantic>=2.5.0       # Data validation

License

Educational project.