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

```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"])
```

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

## 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)

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.