---
title: "Get Wallet Tokens"
method: GET
path: "/v1/wallets/{address}/tokens"
tags: ["Gateway"]
---

# Get Wallet Tokens

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

Retrieves token balances for a specific wallet address across one or more blockchain networks. This endpoint provides comprehensive token data including ERC-20 tokens with their balances, metadata, and price information. Results can be filtered by chain, sorted by balance or USD value, and customized to include/exclude spam tokens, native tokens, and tokens without price data. Supports pagination and metadata resolution options.

**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 token data for. You can specify multiple chain IDs by repeating the parameter, up to a maximum of 50. Example: ?chainId=1&chainId=137
- `tokenAddresses` string[] — Token addresses to filter by. If provided, only tokens with these addresses will be returned.
- `limit` integer — The number of tokens to return per chain (default: 20, max: 500).
- `page` integer — The page number for pagination (default: 1, max: 20).
- `metadata` 'true' | 'false' — Whether to include token metadata (default: true).
- `resolveMetadataLinks` 'true' | 'false' — Whether to resolve metadata links to fetch additional token information (default: true).
- `includeSpam` 'true' | 'false' — Whether to include tokens marked as spam (default: false).
- `includeNative` 'true' | 'false' — Whether to include native tokens (e.g., ETH, MATIC) in the results (default: true).
- `sortBy` 'balance' | 'token_address' | 'token_price' | 'usd_value' — Field to sort tokens by: 'balance' for token balance, 'token_address' for token address, 'token_price' for token price, 'usd_value' for USD value (default: usd_value).
- `sortOrder` 'asc' | 'desc' — Sort order: 'asc' for ascending, 'desc' for descending (default: desc).
- `includeWithoutPrice` 'true' | 'false' — Whether to include tokens without price data (default: true).

## Response `200`

Wallet tokens retrieved successfully. Returns token data with metadata including pagination information and chain details. Includes token balances, metadata, and price information when available. Results are sorted by the specified criteria (default: USD value descending) and filtered according to the provided parameters.

- object
  - `result` object, required
    - `pagination` object, required
      - `hasMore` boolean — Whether there are more items available
      - `limit` number, nullable — Number of items per page
      - `page` number, nullable — Current page number
      - `totalCount` number, nullable — Total number of items available
    - `tokens` object[], required — Array of wallet tokens.
      - `balance` string, required — The token balance as a string
      - `chain_id` number, required — The chain ID of the token
      - `decimals` number — The number of decimal places
      - `name` string — The token name
      - `icon_uri` string — The token icon URI
      - `prices` object — Price data
      - `price_data` object — Price data for the token
        - `circulating_supply` number — The circulating supply of the token
        - `market_cap_usd` number — The market cap of the token in USD
        - `percent_change_24h` number — The percentage change of the token in the last 24 hours
        - `price_timestamp` string — The timestamp of the latest price update
        - `price_usd` number — The price of the token in USD
        - `total_supply` number — The total supply of the token
        - `usd_value` number — The value of the token balance in USD
        - `volume_24h_usd` number — The volume of the token in USD
      - `symbol` string — The token symbol
      - `token_address` string, required — The contract address of the token

## 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 pagination parameters are out of range.
- `401` — Authentication required. The request must include a valid `x-client-id` header for frontend usage or `x-secret-key` for backend usage.
- `404` — Wallet not found or no tokens available for the specified wallet address on the given blockchain networks.
- `500` — Internal server error. This may occur due to network connectivity issues, external 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)