> ## 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 by Token

> Get wallet token balances filtered by specific token addresses



## OpenAPI

````yaml GET /api/v1/customer/{chain}/token-balances/address/{address}/tokens
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}/tokens:
    get:
      tags:
        - Balances
      summary: Get Token Balances by Token
      description: >-
        Get token balances for an EVM wallet filtered by specific token contract
        addresses. Useful when you only need balances for particular tokens.
      operationId: getHoldingsByToken
      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: token_addresses
          in: query
          description: >-
            Comma-separated list of token contract addresses to filter by (max
            10)
          required: true
          schema:
            type: string
            example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'
        - 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
      responses:
        '200':
          description: Token balances for the specified tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceArray'
        '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:
    TokenBalanceArray:
      type: array
      items:
        $ref: '#/components/schemas/TokenBalance'
      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
    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

````