THthirdweb
Gateway

Get Wallet Tokens

Changed on

Retrieves token balances for a specific wallet address on one blockchain network. Pass exactly one chainId per request; to cover several chains, send one request per chain. 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.

get/v1/wallets/{address}/tokens

Request

  • Base URL
    https://api.thirdweb.com
  • Auth
    API key in header x-client-id

Path parameters

addressstring required

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

Query parameters

chainIdinteger[] required

Chain ID to request token data for. One chain per request: to get tokens on several chains, send one request per chain. Example: ?chainId=1

tokenAddressesstring[]

Token addresses to filter by. If provided, only tokens with these addresses will be returned.

limitinteger

The number of tokens to return per chain (default: 20, max: 500).

pageinteger

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

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.

Changes