Balance

Get Token Balance

Returns the balance of a wallet on a given network. Returns the native token balance by default, or an ERC-20 balance when contractAddress is supplied. Results are cached for 60 seconds.

Endpoint

GET https://api.wallettwo.com/blockchain/v1/api/token/balance

Authentication

This endpoint is authenticated with an API key. Pass it in the x-api-key header.

x-api-key: <YOUR_API_KEY>

If the header is missing or the key fails verification against the WalletTwo auth service, the request is rejected.

Query parameters

Name	Type	Required	Description
address	string	Yes	Wallet address to query.
chainId	string | number	Yes	Decimal chain ID of the network. Must match a network registered in the database.
contractAddress	string	No	ERC-20 contract address. When present, returns that token's balance; when omitted, returns the network's native balance.

Example requests

Native balance:

curl -X GET "https://api.wallettwo.com/blockchain/v1/api/token/balance?address=0xabc...&chainId=1" \
  -H "x-api-key: $WALLETTWO_API_KEY"

ERC-20 balance:

curl -X GET "https://api.wallettwo.com/blockchain/v1/api/token/balance?address=0xabc...&chainId=1&contractAddress=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" \
  -H "x-api-key: $WALLETTWO_API_KEY"

Example response

{
  "networkId": "1",
  "address": "0xabc...",
  "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "balance": "1250000000",
  "decimals": 6,
  "symbol": "USDC"
}

The exact shape is produced by the balance-tracker service. For native balances the contractAddress field is omitted.

Errors

Status	Reason
400	Address is required — missing address query param.
400	Network ID is required — missing chainId query param.
400	Network with chainId <id> not found — chainId is not registered.
401	x-api-key header missing.
401	Invalid API key. — key failed upstream verification.

Caching

Balance responses are cached for 60 seconds per (networkId, address) — or per (networkId, contractAddress, address) for ERC-20 lookups. Subsequent calls within the cache window will return the cached value without hitting the RPC provider.