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

# Get Balances

> Get token balances for a wallet address across chains

Returns token balances for a wallet address across multiple blockchains. Uses Alchemy Portfolio API (40+ EVM chains + Solana), PulseChain direct RPC, and Blockstream API (Bitcoin).

Balances include USD pricing, spam filtering, and are grouped by chain ID.

<ParamField query="address" type="string" required>
  Wallet address. Supports EVM (`0x...`), Solana (base58), and Bitcoin (legacy, segwit, taproot).
</ParamField>

<ParamField query="chainIds" type="string">
  Comma-separated chain IDs to filter. Omit to return balances across all supported chains. Example: `1,42161,8453,369`
</ParamField>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "data": {
      "address": "0x0101e82F16792A3368Ca5c62c263F56a99C46c1a",
      "totalBalanceUSD": "5432.10",
      "balances": {
        "1": [
          {
            "chainId": 1,
            "address": "0x0000000000000000000000000000000000000000",
            "symbol": "ETH",
            "name": "Ethereum",
            "decimals": 18,
            "balance": "1.5",
            "priceUSD": 3250.00,
            "balanceUSD": 4875.00,
            "logoURI": "https://static.alchemyapi.io/images/assets/279.png",
            "providers": ["alchemy"]
          },
          {
            "chainId": 1,
            "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
            "symbol": "USDC",
            "name": "USD Coin",
            "decimals": 6,
            "balance": "500.00",
            "priceUSD": 1.00,
            "balanceUSD": 500.00,
            "logoURI": "https://static.alchemyapi.io/images/assets/3408.png",
            "providers": ["alchemy"]
          }
        ],
        "369": [
          {
            "chainId": 369,
            "address": "0x0000000000000000000000000000000000000000",
            "symbol": "PLS",
            "name": "Pulse",
            "decimals": 18,
            "balance": "100000",
            "priceUSD": 0,
            "balanceUSD": 0,
            "logoURI": "",
            "providers": ["superswap"]
          }
        ]
      }
    },
    "error": null,
    "meta": {
      "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "timestamp": 1711234568,
      "rateLimit": {
        "limit": 2000,
        "remaining": 1998,
        "reset": 1711234627
      }
    }
  }
  ```
</ResponseExample>

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  const balances = await client.getBalances({
    address: "0x0101e82F16792A3368Ca5c62c263F56a99C46c1a",
    chainIds: [1, 8453, 369],
  });

  console.log("Total USD:", balances.totalBalanceUSD);

  // Get ETH balance on Ethereum
  const ethBalances = balances.balances["1"];
  const eth = ethBalances?.find(t => t.symbol === "ETH");
  console.log("ETH balance:", eth?.balance);
  ```

  ```bash cURL theme={"system"}
  curl "https://api.hypermid.io/v1/balances?address=0x0101e82F16792A3368Ca5c62c263F56a99C46c1a&chainIds=1,8453,369" \
    -H "X-API-Key: your-api-key"
  ```

  ```python Python theme={"system"}
  import requests

  response = requests.get(
      "https://api.hypermid.io/v1/balances",
      params={
          "address": "0x0101e82F16792A3368Ca5c62c263F56a99C46c1a",
          "chainIds": "1,8453,369"
      },
      headers={"X-API-Key": "your-api-key"}
  )
  balances = response.json()["data"]
  print(f"Total: ${balances['totalBalanceUSD']}")
  ```
</CodeGroup>

## Supported Chains

| Source                | Chains                                                                      |
| --------------------- | --------------------------------------------------------------------------- |
| Alchemy Portfolio API | 40+ EVM chains (Ethereum, Arbitrum, Base, Polygon, Optimism, etc.) + Solana |
| PulseChain RPC        | PulseChain (369) — PLS, USDCh, HEX, PLSX, INC                               |
| Blockstream API       | Bitcoin                                                                     |

## Notes

* Spam tokens are automatically filtered out
* Zero balances are excluded from the response
* Results are sorted by USD value (highest first) within each chain
* PulseChain balances use direct RPC since Alchemy does not support PulseChain


## OpenAPI

````yaml GET /v1/balances
openapi: 3.0.3
info:
  title: Hypermid Partner API
  version: 1.0.0
  description: >-
    Cross-chain swap aggregator API. Supports 30+ EVM chains, Solana, Bitcoin,
    Sui, and Near Intents chains (NEAR, TON, Tron, XRP, etc.).


    ## Authentication

    Pass your API key via the `X-API-Key` header. Public endpoints work without
    a key (anonymous tier). Partner endpoints (`/v1/partner/*`) require a valid
    key.


    ## Rate Limits

    - **Anonymous**: 30 requests/minute (per IP)

    - **Partner (authenticated)**: 100 requests/minute (per API key)


    These limits are designed for human-driven widget usage and mirror our
    upstream aggregator (LiFi) limits to prevent any single user from exhausting
    shared quota.


    Rate limit info is returned in `meta.rateLimit` on every response.


    ## Response Envelope

    All responses follow the shape:

    ```json

    { "data": <T | null>, "error": <{ code, message, details? } | null>, "meta":
    { "requestId", "timestamp", "rateLimit?" } }

    ```
  contact:
    name: Hypermid
    url: https://hypermid.io
servers:
  - url: https://api.hypermid.io
    description: Production
security:
  - ApiKeyAuth: []
  - {}
tags:
  - name: Swap
    description: Cross-chain swap quoting, routing, status, and reference data
  - name: Execute
    description: Transaction execution and deposit management for Near Intents swaps
  - name: On-Ramp
    description: Fiat-to-crypto on-ramp via RampNow
  - name: Partner
    description: Partner account, analytics, and webhook management (requires X-API-Key)
  - name: Tracking
    description: Swap event tracking for partner attribution
  - name: System
    description: Health check and API metadata
paths:
  /v1/balances:
    get:
      tags:
        - Swap
      summary: Get token balances
      description: >-
        Returns token balances for a wallet address across chains. Uses Alchemy
        Portfolio API (40+ EVM + Solana), PulseChain direct RPC, and Blockstream
        (Bitcoin).
      parameters:
        - name: address
          in: query
          required: true
          schema:
            type: string
          description: Wallet address (EVM 0x..., Solana base58, or Bitcoin)
        - name: chainIds
          in: query
          required: false
          schema:
            type: string
          description: >-
            Comma-separated chain IDs to filter (e.g. 1,42161,8453,369). Omit
            for all chains.
      responses:
        '200':
          description: Token balances grouped by chainId
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      address:
                        type: string
                      totalBalanceUSD:
                        type: string
                      balances:
                        type: object
                        description: Token balances keyed by chainId
                        additionalProperties:
                          type: array
                          items:
                            type: object
                            properties:
                              chainId:
                                type: number
                              address:
                                type: string
                              symbol:
                                type: string
                              name:
                                type: string
                              decimals:
                                type: number
                              balance:
                                type: string
                              priceUSD:
                                type: number
                              balanceUSD:
                                type: number
                              logoURI:
                                type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/UpstreamError'
components:
  responses:
    BadRequest:
      description: Invalid or missing parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
    UpstreamError:
      description: Upstream provider error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiResponse'
  schemas:
    ApiResponse:
      type: object
      properties:
        data:
          description: Response payload (null on error)
        error:
          nullable: true
          type: object
          properties:
            code:
              type: string
              example: INVALID_PARAMS
            message:
              type: string
              example: 'Missing required parameters: fromChain'
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - data
        - error
        - meta
    Meta:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
        timestamp:
          type: integer
          description: Unix epoch seconds
        rateLimit:
          type: object
          properties:
            limit:
              type: integer
            remaining:
              type: integer
            reset:
              type: integer
              description: Unix epoch seconds when the window resets
      required:
        - requestId
        - timestamp
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Partner API key. Optional for public endpoints, required for
        /v1/partner/*.

````