> ## 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 Current Token Balances of an Address > 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. ## 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.31 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. 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 - name: address required: true in: query description: Address to search schema: type: string - name: network_type required: true in: query description: 'network type: evm, solana, cosmos, etc.' schema: type: string - name: token_contracts required: true in: query description: Comma separated list of token contract addresses (max 30). schema: type: string - name: workspace_id required: false in: query description: >- Workspace id to filter this address's balances by that workspace's token whitelist. 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' 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.