> For the complete documentation index, see [llms.txt](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/api/balance.md).

# 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:

```bash
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:

```bash
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

```json
{
  "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.