---
title: "Get Balance"
method: GET
path: "/v1/wallets/{address}/balance"
tags: ["Wallets"]
---

# Get Balance

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

Get native or ERC20 token balance for a wallet address. Can retrieve live balances for any ERC20 token on a signle chain, or native token balances across multiple chains.

**Authentication**: Pass `x-client-id` header for frontend usage from allowlisted origins or `x-secret-key` for backend usage.

## Path parameters

- `address` string, required — A valid Ethereum address (0x-prefixed hex string) or ENS name (e.g., vitalik.eth).

## Query parameters

- `chainId` integer[], required — Chain ID(s) to request balance data for. You can specify multiple chain IDs by repeating the parameter, up to a maximum of 50. Example: ?chainId=1&chainId=137
- `tokenAddress` string — The token contract address. Omit for native token (ETH, MATIC, etc.).

## Response `200`

Wallet native balances retrieved successfully. Returns detailed native token balance information for each chain including token metadata and formatted values.

- object
  - `result` object[], required
    - `chainId` number, required — The blockchain network ID
    - `decimals` number, required — Number of decimal places for the token
    - `displayValue` string, required — Human-readable balance formatted with appropriate decimal places
    - `name` string, required — The token name (e.g., 'Ether', 'USD Coin')
    - `symbol` string, required — The token symbol (e.g., 'ETH', 'USDC')
    - `tokenAddress` string, required — The token contract address. Returns zero address (0x0...0) for native tokens.
    - `value` string, required — Raw balance value as string in smallest unit (wei for ETH, etc.)

## Other responses

- `400` — Invalid request parameters. This occurs when the wallet address format is invalid, chainId array is empty or exceeds the maximum limit of 50, or chain IDs are invalid.
- `401` — Authentication required. The request must include a valid `x-client-id` header for frontend usage or `x-secret-key` for backend usage.
- `500` — Internal server error. This may occur due to blockchain connectivity issues, RPC service unavailability, or unexpected server errors.

---

[API](https://skmtc.net/thirdweb/apis/thirdweb-api.md) · [All operations](https://skmtc.net/thirdweb/apis/thirdweb-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thirdweb/thirdweb-api/revisions/fb4cb67da1c7/schema)