> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sonarx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Token Balances

> Get all token balances for an EVM wallet address with optional point-in-time queries



## OpenAPI

````yaml GET /api/v1/customer/{chain}/token-balances/address/{address}
openapi: 3.1.0
info:
  title: SonarX EVM API - Balances
  description: >-
    Query token balances for EVM wallet addresses with optional historical
    point-in-time queries.
  version: 1.0.0
servers:
  - url: https://api-gateway.sonarx.com
    description: Production API
security:
  - apiKey: []
tags:
  - name: Balances
    description: Query token balances for EVM wallets
paths:
  /api/v1/customer/{chain}/token-balances/address/{address}:
    get:
      tags:
        - Balances
      summary: Get Token Balances
      description: >-
        Get all token balances for an EVM wallet address. Supports both current
        balances and historical point-in-time queries by block number.
      operationId: getWalletHoldings
      parameters:
        - $ref: '#/components/parameters/ChainPath'
        - name: address
          in: path
          description: The EVM wallet address (0x-prefixed, 42 characters)
          required: true
          schema:
            type: string
            pattern: ^0x[a-fA-F0-9]{40}$
            example: '0xC288Cdb9785dbAd66a47A668A0B18E55466d3127'
        - name: block_number
          in: query
          description: >-
            Optional block number for point-in-time historical balance. If
            omitted, returns the latest known balance.
          required: false
          schema:
            type: integer
            minimum: 0
            example: 23525000
        - name: offset
          in: query
          description: Number of results to skip for pagination (0-indexed)
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: limit
          in: query
          description: Number of records per page (max 100)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: Token balances for the wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletHoldingsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ChainPath:
      name: chain
      in: path
      description: The blockchain network to query
      required: true
      schema:
        type: string
        enum:
          - apechain
          - arbitrum
          - base
          - berachain
          - binance
          - bittorrent
          - blast
          - celo
          - chiliz
          - cronos
          - educhain
          - ethereum
          - fantom
          - gnosis
          - kaia
          - mantle
          - optimism
          - polygon
          - polygon_zkevm
          - sonic
          - story
          - unichain
        example: ethereum
  schemas:
    WalletHoldingsResponse:
      type: object
      properties:
        offset:
          type: integer
          description: Number of results skipped
        limit:
          type: integer
          description: Number of results per page
        result:
          type: array
          items:
            $ref: '#/components/schemas/TokenBalance'
        count:
          type: integer
          description: Number of token balances returned
      example:
        offset: 0
        limit: 50
        result:
          - token_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
            token_symbol: USDC
            token_name: USD Coin
            current_price: 1
            price_last_updated: '2025-12-16T16:29:51.223000'
            balance: 17.545786
            datetime_last_updated: '2025-12-16T08:55:35'
            block_number_last_updated: 24026500
          - token_address: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'
            token_symbol: ETH
            token_name: Ethereum
            current_price: 2951.94
            price_last_updated: '2025-12-16T16:29:31.464000'
            balance: 0.002420673959646303
            datetime_last_updated: '2025-12-16T08:55:35'
            block_number_last_updated: 24026500
        count: 2
    TokenBalance:
      type: object
      properties:
        token_address:
          type: string
          description: Contract address of the token
        token_symbol:
          type: string
          description: Token symbol (e.g., USDT, ETH)
        token_name:
          type: string
          description: Full token name
        current_price:
          type: number
          nullable: true
          description: Current token price in USD
        price_last_updated:
          type: string
          format: date-time
          nullable: true
          description: ISO timestamp of last price update
        balance:
          type: number
          description: Token balance for the wallet
        datetime_last_updated:
          type: string
          format: date-time
          description: Timestamp when this balance was last updated
        block_number_last_updated:
          type: integer
          description: Block number when this balance was last updated
      example:
        token_address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
        token_symbol: USDC
        token_name: USD Coin
        current_price: 1
        price_last_updated: '2025-12-16T16:29:51.223000'
        balance: 17.545786
        datetime_last_updated: '2025-12-16T08:55:35'
        block_number_last_updated: 24026500
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: API key for authentication

````