> ## 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 - Token Balance (Beta)

> Retrieve the balance of a token in a wallet.

<Tabs>
  <Tab title="Usage Note">
    <p><strong>Current balance of one token in one wallet.</strong></p>

    <ul>
      <li>Provide one wallet address and one token mint address.</li>
      <li>Response is a current balance snapshot, not a historical balance series.</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 token balance in base units. <code>amount</code> is the decimal-adjusted balance, or the scaled UI amount when requested and supported. <code>price</code> is the latest token price in USD, and <code>value</code> is the wallet position 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>This endpoint consumes <code>20 CU</code> per request.</li>
  </ul>
</Accordion>

<Accordion title="Use Cases 💡" icon="fa-lightbulb">
  <ul>
    <li>Show the exact balance of one token in one wallet.</li>
    <li>Build portfolio widgets, treasury views, or token-position popovers.</li>
    <li>Check current exposure before deeper PnL or transfer analysis.</li>
  </ul>
</Accordion>

<Accordion title="How to Use 🛠️" icon="fa-book-open">
  <ul>
    <li>Set <code>x-chain=solana</code>.</li>
    <li>Pass the wallet in <code>wallet</code> and the mint in <code>token\_address</code>.</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>Use this endpoint for single-token checks; use <code>Wallet - Tokens Balance</code> when you already have a list of many mints.</li>
    <li>Keep <code>ui\_amount\_mode</code> consistent across token balance, holder, and transfer analysis for scaled UI tokens.</li>
    <li>Cache responses briefly if multiple views in the same screen need the same balance snapshot.</li>
  </ul>
</Accordion>

<Accordion title="Limitations ⚠️" icon="fa-exclamation-triangle">
  <ul>
    <li>Robinhood returns raw balances as decimal strings and may return <code>null</code> when price enrichment is unavailable.</li>
    <li>Beta endpoint.</li>
    <li>Returns the current balance only, not balance history.</li>
  </ul>
</Accordion>

<br />


## OpenAPI

````yaml openapi/data/openapi_docs.json GET /v1/wallet/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:
  /v1/wallet/token_balance:
    get:
      tags:
        - Balance & Transfer
      summary: Wallet - Token Balance (Beta)
      description: >-
        Retrieve one token balance on Solana or Robinhood. Robinhood reads the
        native/ERC-20 balance from RPC and returns the raw balance as a decimal
        string; a confirmed non-holder returns success=true with data=null.
        priceUsd is the market price; valuation_price is the effective per-unit
        price used for valueUsd and may be lower under a liquidity-based
        portfolio guard. When price data is unavailable, priceUsd,
        valuation_price and valueUsd may be null; an actual zero price is
        returned as 0. Zero/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee native
        aliases are supported. NFT token IDs are not supported by this V1 route.
        ui_amount_mode applies to Solana only.
      operationId: get-v1-wallet-token_balance
      parameters:
        - $ref: '#/components/parameters/xSolanaRobinhoodChainParam'
        - $ref: '#/components/parameters/walletApiWalletParam'
        - $ref: '#/components/parameters/walletApiTokenAddressParam'
        - $ref: '#/components/parameters/uiAmountModeSplitParam'
      responses:
        '200':
          $ref: '#/components/responses/WalletTokenBalance'
        '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
    walletApiWalletParam:
      name: wallet
      description: The address of a wallet.
      in: query
      required: true
      schema:
        type: string
      examples:
        solana:
          value: Gt4RRcMg2mzEN9SDtSUjEjezC9b1nXjEGDQyEVbrc7Sk
        ethereum:
          value: '0xE76aDA2ADE5585859789b3500DDE494e5479fb75'
    walletApiTokenAddressParam:
      name: token_address
      description: Token mint address.
      in: query
      required: true
      schema:
        type: string
      examples:
        wsol:
          value: So11111111111111111111111111111111111111112
        solana:
          value: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
        ethereum:
          value: '0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce'
        solana_scaled_ui:
          value: Xsc9qvGR1efVDFGLrVsmkzv3qi45LTBjeUKSPmx9qEh
    uiAmountModeSplitParam:
      name: ui_amount_mode
      description: >-
        Indicate whether to use the scaled amount for scaled ui amount tokens.
        Only support solana
      in: query
      required: false
      schema:
        type: string
        enum:
          - raw
          - scaled
        default: scaled
  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
    WalletTokenBalance:
      description: >-
        JSON object containing the balance and USD value for a single token
        holding.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/WalletTokenSingleResponseSchema'
          examples:
            RobinhoodAdjusted:
              summary: >-
                Illustrative liquidity-adjusted holding: 10 × 200 = 2000, while
                market price stays 500
              value:
                success: true
                data:
                  address: '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
                  decimals: 9
                  balance: '10000000000'
                  uiAmount: 10
                  chainId: robinhood
                  name: Staked NET
                  symbol: SNET
                  logoURI: ''
                  priceUsd: 500
                  valuation_price: 200
                  valueUsd: 2000
            RobinhoodNonHolder:
              value:
                success: true
                data: null
            RobinhoodUnknownPrice:
              summary: Balance exists but price enrichment is unavailable
              value:
                success: true
                data:
                  address: '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
                  decimals: 9
                  balance: '10000000000'
                  uiAmount: 10
                  chainId: robinhood
                  name: Staked NET
                  symbol: SNET
                  logoURI: ''
                  priceUsd: null
                  valuation_price: null
                  valueUsd: null
            RobinhoodZeroPrice:
              summary: Actual zero price is 0, not null
              value:
                success: true
                data:
                  address: '0xb773ec2c326b7f98a5a83fc098825492f020a4c7'
                  decimals: 9
                  balance: '10000000000'
                  uiAmount: 10
                  chainId: robinhood
                  name: Staked NET
                  symbol: SNET
                  logoURI: ''
                  priceUsd: 0
                  valuation_price: 0
                  valueUsd: 0
            SolanaScaledUIAmount:
              value:
                success: true
                data:
                  address: So11111111111111111111111111111111111111112
                  decimals: 9
                  balance: 130718
                  uiAmount: 0.000130718
                  chainId: solana-mainnet
                  logoURI: >-
                    https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/So11111111111111111111111111111111111111112/logo.png
                  name: Wrapped SOL
                  symbol: SOL
                  priceUsd: 186.17611361160655
                  valueUsd: 0.024336569219081984
                  isScaledUiToken: false
                  multiplier: null
            Solana:
              value:
                success: true
                data:
                  address: Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB
                  decimals: 6
                  balance: 1177780977972721
                  uiAmount: 1177780977.972721
                  chainId: solana-mainnet
                  logoURI: >-
                    https://img.fotofolio.xyz/?w=30&h=30&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolana-labs%2Ftoken-list%2Fmain%2Fassets%2Fmainnet%2FEs9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB%2Flogo.svg
                  name: USDT
                  symbol: USDT
                  priceUsd: 0.9999915198446391
                  valueUsd: 1177770990.2070467
            EVM:
              value:
                success: true
                data:
                  address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
                  name: Tether USD
                  symbol: USDT
                  decimals: 6
                  balance: 94149341656019
                  uiAmount: 94149341.656019
                  chainId: eth-mainnet
                  priceUsd: 0.9999915198446391
                  valueUsd: 94149341656019.2
  schemas:
    WalletTokenSingleResponseSchema:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          description: Whether the request succeeded.
        data:
          oneOf:
            - $ref: '#/components/schemas/WalletTokenHolding'
            - type: 'null'
          description: Token holding, or null for a confirmed non-holder.
    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.