> ## Documentation Index > Fetch the complete documentation index at: https://docs.range.org/llms.txt > Use this file to discover all available pages before exploring further. # Get address token balances > Return token balances and the lookup outcome for an address on a network. ## OpenAPI ````yaml api-reference/data-api.json get /v1/address/balance openapi: 3.0.0 info: title: Range Data API description: >- The Range Data API for crypto addresses, networks, transactions, and entities. version: 1.7.37 contact: {} servers: - url: https://api.range.org description: Range API Server security: - Authorization: [] tags: - name: Entity Information description: Get information about entities. - name: Network Information description: Get information about networks. - name: Protocols description: Get information about cross-chain protocols. - name: Token transfers description: Get information about token transfers. - name: Cross-chain transfers description: >- Look up cross-chain transfers using either the source or destination transaction hash, and explore coverage by protocol and network. paths: /v1/address/balance: get: tags: - Address Information summary: Get current token balances of an address description: >- Returns token balances of the given address alongside the lookup outcome (`lookup_status`, and `reason` when not `ok`) on every 200. A failed, partial, or unsupported lookup is reported through `lookup_status` rather than as an empty balance set left indistinguishable from a genuinely empty address. Each entry carries the legacy `amount` (a JSON number, kept for backwards compatibility) alongside `amount_string`, the exact, lossless string rendering of that same quantity. Responses are cached for 60 seconds; send `Cache-Control: no-cache` to force a fresh lookup. operationId: getBalance parameters: - name: network required: true in: query description: Network of Address schema: type: string example: ethereum - name: address required: true in: query description: Address to search schema: type: string example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' - name: network_type required: true in: query description: 'network type: evm, solana, cosmos, etc.' schema: example: evm type: string - name: token_contracts required: true in: query description: Comma separated list of token contract addresses (max 30). schema: type: string example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' - name: workspace_id required: false in: query description: >- Your own workspace id, to filter this address's balances by your workspace's token whitelist. Must equal the workspace of the API key making the request (403 otherwise). Omit for the unfiltered response. schema: type: string - name: show_all required: false in: query description: >- Restores the unfiltered response, ignoring the workspace token whitelist. Only meaningful alongside workspace_id. schema: default: false type: boolean responses: '200': description: Token balances of the given address, plus lookup status. content: application/json: schema: $ref: '#/components/schemas/AddressBalanceResponseDto' '403': description: workspace_id must match the API key's workspace components: schemas: AddressBalanceResponseDto: type: object properties: balances: description: >- Always present; never null. An empty set (both arrays empty) when `lookup_status` is `unavailable` or `unsupported`, since there is no genuine answer to serve. Populated (fully, on `ok`, or partly, on `partial`) otherwise. See ADR-0013: the lookup outcome always travels on `lookup_status`/`reason` rather than by changing the shape of this field. allOf: - $ref: '#/components/schemas/AddressTokenBalancesDto' lookup_status: type: string enum: - ok - unsupported - unavailable - partial example: ok description: >- Outcome of this balance lookup. `ok`: fully resolved. `partial`: the native balance leg failed but token balances resolved and are included. `unavailable`: the lookup failed entirely; retry may succeed. `unsupported`: this chain has no readable balance source, evaluated before any lookup was attempted; retrying will not help. Always present, including on a fully successful lookup. reason: nullable: true description: >- Why the lookup did not return `ok`. Always present as an explicit null on `ok`/`unsupported`; populated on `partial`/`unavailable`. type: object allOf: - $ref: '#/components/schemas/AddressBalanceLookupReasonDto' hidden_count: type: number example: 0 description: >- RNG-5741: count of tokens the workspace token whitelist removed from `balances` above. `0` both when nothing was filtered and when `lookup_status` is not `ok`/`partial` (no genuine answer to filter). Always `0` when `show_all` was requested or no `workspace_id` was given. Always present. required: - balances - lookup_status - reason - hidden_count AddressTokenBalancesDto: type: object properties: native_tokens: type: array items: $ref: '#/components/schemas/AddressBalanceEntryDto' tokens: type: array items: $ref: '#/components/schemas/AddressBalanceEntryDto' required: - native_tokens - tokens AddressBalanceLookupReasonDto: type: object properties: code: type: string enum: - reconnect_required - provider_timeout - rate_limited - authentication_failed - provider_unreachable - provider_rejected - provider_error - connection_not_found - balance_lookup_failed - unclassified_provider_error - asset_catalog_unavailable - tokens_not_enumerated example: provider_timeout description: >- Stable machine code a client may branch on without string-matching prose that may be reworded. display: type: string example: Provider timed out description: Human-readable display string for `code`. required: - code - display AddressBalanceEntryDto: type: object properties: amount: type: number example: 1.234567890123 description: >- LEGACY Balance amount as a JSON number. Human-readable when Scale (`decimals`) is known; otherwise raw on-chain units. Kept for backwards compatibility — a JSON number cannot carry an 18-decimal quantity exactly, so this can lose precision above Number.MAX_SAFE_INTEGER. Superseded by `amount_string`, which is always exact: `amount === Number(amount_string)`. amount_string: type: string example: '1.234567890123456789' description: >- Exact, lossless string rendering of `amount` — same semantics, only exact. When this line’s Scale is unknown, this carries the exact base-unit integer, because that is already what `amount` means in that case. Never in exponential notation. denom: type: string example: eth description: Denomination / token identifier. usd: type: number nullable: true example: 2000.5 description: USD value, when a price is known. usd_string: type: string nullable: true example: '2000.5' description: >- Exact, lossless string rendering of `usd` (RNG-5099 D7): the full exact product with trailing zeros trimmed, never rounded. Present exactly when `usd` is. decimals: type: number nullable: true example: 18 description: >- Scale: power of ten separating `base_amount` (and `amount`) from its human-readable form. `null` means the scale is unknown. base_amount: type: string example: '1234567890123456789' description: >- Exact on-chain integer quantity in the smallest indivisible unit (wei, lamports, stroops, uatom), as a decimal string. name: type: string example: Ether description: Human-readable asset name. symbol: type: string example: ETH description: Asset ticker / symbol. price: type: number example: 2000.5 description: Unit price in USD. price_string: type: string example: '2000.5' description: >- Exact, lossless string rendering of `price` (RNG-5099 D4): the unit price as reported by the resolver, never recovered by inverting `usd / amount`. Present exactly when `price` is. verified: type: boolean example: true description: Whether this token is present in the curated asset registry. required: - amount - amount_string - denom - decimals - base_amount securitySchemes: Authorization: type: apiKey in: header name: X-API-KEY description: Authorization method required to allow user to access the api endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.