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

# Get Token Balance

> Get the balance of a specific token for a wallet

<RequestExample url="https://api.chipipay.com/v1/chipi-wallets/token-balance" method="GET">
  ```bash cURL theme={null}
  curl -X GET "https://api.chipipay.com/v1/chipi-wallets/token-balance?externalUserId=user_123&chainToken=USDC&chain=STARKNET" \
    -H "Authorization: Bearer sk_prod_xxxx" \
    -H "x-api-key: pk_xxxx"
  ```

  ```typescript TypeScript theme={null}
  const params = new URLSearchParams({
    externalUserId: "user_123",
    chainToken: "USDC",
    chain: "STARKNET"
  });

  const response = await fetch(
    `https://api.chipipay.com/v1/chipi-wallets/token-balance?${params}`,
    {
      headers: {
        "Authorization": "Bearer sk_prod_xxxx",
        "x-api-key": "pk_xxxx",
      }
    }
  );

  const balance = await response.json();
  // balance.balance is a raw integer string — use BigInt for precision
  const raw = BigInt(balance.balance);
  const scale = 10n ** BigInt(balance.decimals);
  const whole = raw / scale;
  const fraction = (raw % scale).toString().padStart(balance.decimals, "0").replace(/0+$/, "");
  const humanReadable = fraction ? `${whole}.${fraction}` : `${whole}`;
  ```

  ```python Python theme={null}
  import requests
  from decimal import Decimal

  response = requests.get(
      "https://api.chipipay.com/v1/chipi-wallets/token-balance",
      params={
          "externalUserId": "user_123",
          "chainToken": "USDC",
          "chain": "STARKNET"
      },
      headers={
          "Authorization": "Bearer sk_prod_xxxx",
          "x-api-key": "pk_xxxx",
      }
  )

  balance = response.json()
  human_readable = Decimal(balance["balance"]) / (Decimal(10) ** balance["decimals"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Response theme={null}
  {
    "chain": "STARKNET",
    "chainToken": "USDC",
    "chainTokenAddress": "0x033068F6539f8e6e6b131e6B2B814e6c34A5224bC66947c47DaB9dFeE93b35fb",
    "decimals": 6,
    "balance": "15000000"
  }
  ```
</ResponseExample>

## Notes

* The `balance` field is a raw integer string. Divide by `10^decimals` to get the human-readable amount. In the example above, `15000000 / 10^6 = 15.0 USDC`.
* You can identify the wallet by either `externalUserId` or `walletPublicKey`. At least one is required.


## OpenAPI

````yaml GET /chipi-wallets/token-balance
openapi: 3.1.0
info:
  title: Chipi Pay API
  description: >-
    REST API for creating self-custodial wallets, executing gasless
    transactions, and purchasing services on Starknet.
  version: 14.0.0
  license:
    name: MIT
servers:
  - url: https://api.chipipay.com/v1
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Wallets
    description: Create and manage self-custodial Starknet wallets
  - name: Transactions
    description: Record and query blockchain transactions
  - name: SKUs
    description: Browse available services for purchase
  - name: SKU Purchases
    description: Purchase services using blockchain payments
  - name: Exchanges
    description: Currency conversion rates
paths:
  /chipi-wallets/token-balance:
    get:
      tags:
        - Wallets
      summary: Get Token Balance
      description: >-
        Get the balance of a specific token for a wallet. Provide either
        `externalUserId` or `walletPublicKey` to identify the wallet.
      operationId: getTokenBalance
      parameters:
        - name: externalUserId
          in: query
          description: Your application's user identifier (provide this or walletPublicKey)
          schema:
            type: string
        - name: walletPublicKey
          in: query
          description: The wallet's public key / address (provide this or externalUserId)
          schema:
            type: string
        - name: chainToken
          in: query
          required: true
          description: The token to query
          schema:
            $ref: '#/components/schemas/ChainToken'
        - name: chain
          in: query
          required: true
          description: The blockchain network
          schema:
            $ref: '#/components/schemas/Chain'
      responses:
        '200':
          description: Token balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenBalanceResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ChainToken:
      type: string
      enum:
        - USDC
        - USDC_E
        - USDT
        - DAI
        - ETH
        - STRK
        - SLINK
        - ALF
        - BROTHER
        - ARB
        - DOC
        - MXNB
        - WLD
        - WBTC
        - OTHER
      description: Token identifier
    Chain:
      type: string
      enum:
        - STARKNET
        - BASE
        - ARBITRUM
        - OPTIMISM
        - ROOTSTOCK
        - SCROLL
        - WORLDCHAIN
      description: Blockchain network identifier
    TokenBalanceResponse:
      type: object
      properties:
        chain:
          $ref: '#/components/schemas/Chain'
        chainToken:
          $ref: '#/components/schemas/ChainToken'
        chainTokenAddress:
          type: string
          description: The token's contract address on the chain
        decimals:
          type: integer
          description: Number of decimal places for the token
        balance:
          type: string
          description: The raw balance (divide by 10^decimals for human-readable amount)
      required:
        - chain
        - chainToken
        - chainTokenAddress
        - decimals
        - balance
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
      required:
        - error
        - message
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized — invalid or missing API key / bearer token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded (100 requests/minute per API key)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token — use your secret key (sk_prod_xxx) for server-side calls,
        or the user's JWT for client-side calls
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your Chipi public API key (pk_xxx)

````