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

# Wallet - Tokens Balance

> Retrieve the balances of a list of tokens in a wallet.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Batch token-balance lookup for one Solana wallet.</strong></p>

    <ul>
      <li>Maximum request size is <code>500</code> token addresses.</li>
      <li>Response is ordered by the submitted token list and returns one balance snapshot per requested token.</li>
      <li><code>ui\_amount\_mode=scaled</code> applies Solana Token-2022 scaled UI amount when the token supports the scaled UI extension.</li>
    </ul>

    <p><strong>Reading the numbers.</strong> <code>balance</code> is the raw balance in base units. <code>amount</code> is the decimal-adjusted balance, or scaled UI amount when requested and supported. <code>price</code> is the latest token price in USD, and <code>value</code> is the wallet holding value in USD.</p>
  </Tab>

  <Tab title="Accessibility">
    <ul>
      <li>Lite</li>
      <li>Starter</li>
      <li>Premium</li>
      <li>Business</li>
      <li>Enterprise</li>
    </ul>
  </Tab>

  <Tab title="Chain Supported">
    <p><strong>Solana, Robinhood</strong></p>
  </Tab>
</Tabs>

<Accordion title="Compute Unit ⚙️" icon="fa-gauge-high">
  <ul>
    <li>Batch CU is calculated as <code>ceil(10 \* wallet\_count^0.8)</code>.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Load many token balances for one wallet in one request.</li>
    <li>Power portfolio pages, treasury views, and token-watch grids.</li>
    <li>Join wallet balances with prices for fast position-value displays.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Set <code>x-chain=solana</code>.</li>
    <li>Send the wallet address and up to <code>50</code> token mints in the POST body.</li>
    <li>Use <code>ui\_amount\_mode=raw</code> for raw-decimal output or <code>ui\_amount\_mode=scaled</code> for Token-2022 scaled UI amounts when supported.</li>
  </ul>
</Accordion>

<Accordion title="Best Practices ✅" icon="fa-check-circle">
  <ul>
    <li>Deduplicate token mints before sending the batch.</li>
    <li>Use this batch endpoint for known token sets; use broader wallet portfolio endpoints when discovery matters more than exact token selection.</li>
    <li>Reuse one batch response across multiple UI components during the same refresh cycle.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Robinhood returns raw balances as decimal strings; missing holdings may be returned as <code>null</code> entries.</li>
    <li>Maximum <code>50</code> tokens per request.</li>
  </ul>
</Accordion>


## OpenAPI

````yaml openapi/data/openapi_docs.json POST /wallet/v2/token-balance
openapi: 3.1.0
info:
  version: 1.1.0
  title: Birdeye Data API
  description: >-
    Birdeye Data API is a full-spectrum blockchain and DEX data platform for
    teams that need production-grade crypto market intelligence across tokens,
    pairs, wallets, traders, protocols, and chains.


    From real-time prices, OHLCV, liquidity, and transaction flow to holder
    analytics, token and pair overviews, wallet portfolio and PnL, smart money,
    discovery, security, and blockchain-level utilities, Birdeye gives you a
    unified data layer for building serious crypto products at scale.


    Use it to power exchange interfaces, trading terminals, bots, market-making
    systems, quant research, alpha screeners, portfolio apps, wallet
    intelligence tools, alerting systems, analytics dashboards, and back-office
    data pipelines. Whether your users are retail traders, pro desks, analysts,
    or infrastructure teams, Birdeye helps you ship faster with broad market
    coverage and API surfaces that support both lightweight integrations and
    data-heavy workflows.


    To start, create an account at [bds.birdeye.so](https://bds.birdeye.so),
    generate an API key from the `Security` tab, and send it in the `X-API-KEY`
    header on every request.
servers:
  - url: https://public-api.birdeye.so
security:
  - apiKeyAuth: []
tags:
  - name: Price & OHLCV
  - name: Stats
  - name: Token/Market List
  - name: Transactions
  - name: Wallet, Networth & PnL
  - name: Balance & Transfer
  - name: Holder
  - name: Alltime & History
  - name: Blockchain
  - name: Account
  - name: Token
  - name: Transaction
  - name: Creation & Trending
  - name: Meme
  - name: Security
  - name: Search & Utils
  - name: Smart Money
  - name: Global Fees Paid
  - name: DEX & Protocol
  - name: Wallet Identity
paths:
  /wallet/v2/token-balance:
    post:
      tags:
        - Balance & Transfer
      summary: Wallet - Tokens Balance
      description: >-
        Retrieve requested token balances on Solana or Robinhood using wallet
        and token_addresses. Robinhood raw balances are decimal strings; value =
        amount × valuation_price, with price retained as the market price. A
        liquidity-based portfolio guard may lower valuation_price; otherwise it
        equals price. An actual zero price has valuation_price=0. Missing
        holdings may be null entries; when no requested holding exists data may
        be null. NFT tokens/token_id request entries are not supported by this
        release.
      operationId: post-wallet-v2-token-balance
      parameters:
        - $ref: '#/components/parameters/xSolanaRobinhoodChainParam'
      requestBody:
        $ref: '#/components/requestBodies/walletTokenBalance'
      responses:
        '200':
          $ref: '#/components/responses/WalletTokenBalanceResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
components:
  parameters:
    xSolanaRobinhoodChainParam:
      name: x-chain
      description: >-
        Solana or Robinhood. Robinhood support is limited to current-net-worth,
        V1/V2 token balance and /defi/v3/token/holder; historical balance-change
        remains Solana-only.
      in: header
      required: false
      schema:
        type: string
        enum:
          - solana
          - robinhood
        default: solana
  requestBodies:
    walletTokenBalance:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletTokenBalanceBody'
          examples:
            robinhood:
              value:
                wallet: '0x63C12667638f2Ae6fC6ae09B43D98Ec84a8586eA'
                token_addresses:
                  - '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
            solana:
              value:
                wallet: GbrNi5tsbViArzsiE2WX94rMCCGz87w9cVVWVqcPEyx6
                token_addresses:
                  - 8i42ZVsjEGVhZ6spj4Z5aB36Msh9Vq4nnBaw5kq4pump
  responses:
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Bad request
    '401':
      description: Unauthorized. API key is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Unauthorized
    '403':
      description: Forbidden. Request is blacklisted or not whitelisted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Access Denied
    '429':
      description: Too Many Requests. Rate limit reached
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Too many requests
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            message: Internal Server Error
    WalletTokenBalanceResponse:
      description: JSON object containing a wallet token balance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletTokenBalanceListResponseSchema'
          examples:
            RobinhoodAdjusted:
              value:
                success: true
                data:
                  - address: '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
                    decimals: 9
                    balance: '10000000000'
                    amount: 10
                    price: 500
                    valuation_price: 200
                    value: '2000'
                    network: robinhood
                    name: Staked NET
                    symbol: SNET
                    logo_uri: ''
            RobinhoodUnadjusted:
              value:
                success: true
                data:
                  - address: '0x08E91b659a545Bfb52F1a5e588Bf6Dc2FA85DE7A'
                    decimals: 18
                    balance: '1000000000000000000'
                    amount: 1
                    price: 263
                    valuation_price: 263
                    value: '263'
                    network: robinhood
                    name: McDonald's • Robinhood Token
                    symbol: MCD
                    logo_uri: ''
            RobinhoodNonHolder:
              value:
                success: true
                data: null
            RobinhoodMixedHoldings:
              value:
                success: true
                data:
                  - address: '0x08E91b659a545Bfb52F1a5e588Bf6Dc2FA85DE7A'
                    decimals: 18
                    balance: '1000000000000000000'
                    amount: 1
                    price: 263
                    valuation_price: 263
                    value: '263'
                    network: robinhood
                    name: McDonald's • Robinhood Token
                    symbol: MCD
                    logo_uri: ''
                  - null
            RobinhoodZeroPrice:
              value:
                success: true
                data:
                  - address: '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
                    decimals: 9
                    balance: '10000000000'
                    amount: 10
                    price: 0
                    valuation_price: 0
                    value: '0'
                    network: robinhood
                    name: Staked NET
                    symbol: SNET
                    logo_uri: ''
            Solana:
              value:
                success: true
                data:
                  - address: 8i42ZVsjEGVhZ6spj4Z5aB36Msh9Vq4nnBaw5kq4pump
                    decimals: 9
                    price: 0.0020303701828560256
                    balance: '4998929789571623824'
                    amount: 4998929789.571624
                    network: solana
                    name: BIGIFTRUE
                    symbol: BIGIFTRUE
                    logo_uri: >-
                      https://ipfs.io/ipfs/bafkreihgbhs4sumfhvdcquud7mvggjjbidfuoisytxqnpafrx6ukrh4hlm
                    value: '10149677.99093697'
  schemas:
    WalletTokenBalanceBody:
      required:
        - wallet
        - token_addresses
      type: object
      properties:
        wallet:
          type: string
          example: GbrNi5tsbViArzsiE2WX94rMCCGz87w9cVVWVqcPEyx6
        token_addresses:
          type: array
          minItems: 1
          maxItems: 500
          description: >-
            Token mint/contract addresses; use x-chain to select Solana or
            Robinhood. This release does not accept tokens/token_id entries.
          items:
            type: string
          example:
            - 8i42ZVsjEGVhZ6spj4Z5aB36Msh9Vq4nnBaw5kq4pump
    WalletTokenBalanceListResponseSchema:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          type:
            - array
            - 'null'
          description: >-
            Requested token holdings. Missing holdings may be null entries; data
            may be null when no requested holding exists.
          items:
            oneOf:
              - $ref: '#/components/schemas/WalletTokenHolding'
              - type: 'null'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    WalletTokenHolding:
      type: object
      additionalProperties: true
      properties:
        address:
          type: string
          description: Token mint or contract address.
        decimals:
          type: integer
          description: Number of token decimals.
        balance:
          type:
            - number
            - string
          description: >-
            Raw token balance before decimal scaling. Robinhood returns a
            decimal string to preserve UInt256 precision.
        uiAmount:
          type: number
          description: Human-readable token amount after decimals are applied.
        chainId:
          type: string
          description: Network identifier for the token balance.
        network:
          type: string
          description: Network name when the response uses `network` instead of `chainId`.
        name:
          type: string
          description: Token display name.
        symbol:
          type: string
          description: Token symbol.
        icon:
          type: string
          description: Icon URL for the token when returned.
        logoURI:
          type: string
          description: Logo URL for the token when using camelCase fields.
        logo_uri:
          type: string
          description: Logo URL for the token when using snake_case fields.
        priceUsd:
          type:
            - number
            - 'null'
          description: >-
            Market price in USD. Robinhood V1 may return null when price
            enrichment is unavailable; an actual zero remains 0.
        price:
          type: number
          description: Latest token price in USD when the response uses `price`.
        valuation_price:
          type:
            - number
            - 'null'
          description: >-
            Robinhood effective per-unit price used for portfolio valuation.
            value = amount × valuation_price (V1: valueUsd = uiAmount ×
            valuation_price). It equals the market price when unadjusted and may
            be lower under a liquidity guard. It is position-dependent, not a
            market/sell quote. V1 may return null without price enrichment;
            actual zero price returns 0.
        valueUsd:
          type:
            - number
            - 'null'
          description: >-
            Current USD portfolio value. On Robinhood V1, uiAmount ×
            valuation_price; may be null when price enrichment is unavailable.
        value:
          type:
            - number
            - string
          description: >-
            Current USD portfolio value when using `value`. On Robinhood, amount
            × valuation_price; not necessarily amount × market price.
        amount:
          type: number
          description: Human-readable token amount when the response uses `amount`.
        isScaledUiToken:
          type: boolean
          description: Whether the token uses Solana Token-2022 scaled UI amounts.
        multiplier:
          type:
            - number
            - 'null'
          description: Scaled UI multiplier for Token-2022 assets when available.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: API key for authentication

````

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