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

# Get token balances for specified addresses

> Returns the current available balance of each specified address across different domains where that address is valid



## OpenAPI

````yaml openapi/gateway.yaml post /v1/balances
openapi: 3.0.3
info:
  title: Circle Gateway
  version: 1.0.0
  description: >
    Circle Gateway allows you to create a chain-abstracted USDC balance and
    transfer it instantly to any supported destination chain.
servers:
  - url: https://gateway-api-testnet.circle.com
  - url: https://gateway-api.circle.com
security: []
tags:
  - name: Gateway
    description: >-
      Endpoints for getting a unified USDC balance and creating attestations for
      transfer
  - name: Gateway Batch
    description: Endpoints for batch processing of EIP-3009 authorizations
  - name: Gateway x402
    description: Endpoints for x402 payment protocol integration
  - name: Webhook Subscriptions
    description: Manage webhook subscriptions for Gateway event notifications.
paths:
  /v1/balances:
    post:
      tags:
        - Gateway
      summary: Get token balances for specified addresses
      description: >-
        Returns the current available balance of each specified address across
        different domains where that address is valid
      operationId: GetTokenBalances
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetBalancesRequest'
      responses:
        '200':
          description: Successfully retrieved balances
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalancesResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    GetBalancesRequest:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/Token'
          description: Token type to query balances for
        sources:
          type: array
          description: >-
            List of sources to query balances from. If domain is omitted from
            any source, the balances from all domains for that depositor will be
            returned.
          items:
            type: object
            properties:
              domain:
                $ref: '#/components/schemas/Domain'
                description: >-
                  Domain to query balance from. The depositor address must be
                  valid on the given domain.
              depositor:
                type: string
                description: Address of the depositor to query balance for
            required:
              - depositor
      required:
        - token
        - sources
    BalancesResponse:
      type: object
      description: Response containing token balances for specified sources
      properties:
        token:
          $ref: '#/components/schemas/Token'
          description: Token type that was queried
        balances:
          type: array
          description: List of balance responses for each source
          items:
            type: object
            properties:
              domain:
                $ref: '#/components/schemas/Domain'
                description: Domain where the balance was queried
              depositor:
                type: string
                description: Address of the depositor
              balance:
                type: string
                pattern: ^\d+(\.\d+)?$
                description: Current available balance for the depositor
            required:
              - domain
              - depositor
              - balance
      required:
        - token
        - balances
    Token:
      type: string
      description: Supported tokens for Gateway
      enum:
        - USDC
    Domain:
      type: integer
      enum:
        - 0
        - 1
        - 2
        - 3
        - 5
        - 6
        - 7
        - 10
        - 13
        - 14
        - 16
        - 19
        - 26
      description: |
        Circle domain identifiers for supported chains:

        - 0 - Ethereum
        - 1 - Avalanche
        - 2 - OP
        - 3 - Arbitrum
        - 5 - Solana
        - 6 - Base
        - 7 - Polygon PoS
        - 10 - Unichain
        - 13 - Sonic
        - 14 - World Chain
        - 16 - Sei
        - 19 - HyperEVM
        - 26 - Arc
    XRequestId:
      type: string
      format: uuid
      description: >-
        A unique identifier, which can be helpful for identifying a request when
        communicating with Circle support.
      example: 2adba88e-9d63-44bc-b975-9b6ae3440dde
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            type: object
            title: BadRequestResponse
            required:
              - code
              - message
            properties:
              code:
                type: integer
                description: Code that corresponds to the error.
              message:
                type: string
                description: Message that describes the error.
            example:
              code: 400
              message: Bad request.
      description: Request cannot be processed due to a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
    NotFound:
      content:
        application/json:
          schema:
            type: object
            title: NotFoundResponse
            required:
              - code
              - message
            properties:
              code:
                type: integer
                description: Code that corresponds to the error.
              message:
                type: string
                description: Message that describes the error.
            example:
              code: 404
              message: Not found.
      description: Specified resource was not found.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
  headers:
    XRequestId:
      description: >
        Developer-provided header parameter or Circle-generated universally
        unique identifier (UUID v4). Useful for identifying a specific request
        when communicating with Circle Support.
      schema:
        $ref: '#/components/schemas/XRequestId'

````