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

# Cross-Chain Token Balances

> Get token balances from multiple chains for a specific wallet address. For Bitcoin wallets, filter parameters (excludeNative, excludeSpam, etc.) are ignored — only the native BTC balance is returned.

export const EndpointMeta = ({premium, cus, cusUnit, mainnetOnly}) => {
  const items = [];
  const planName = typeof premium === "string" ? premium : "Pro";
  if (premium) {
    items.push({
      icon: "\u26a0\ufe0f",
      label: "Premium endpoint",
      text: <>
          Requires the <strong>{planName} plan</strong> or above.{" "}
          <a href="/data-api/introduction/resources/premium-endpoints">
            View all
          </a>
          .
        </>
    });
  }
  if (cus) {
    const isDynamic = !!cusUnit;
    items.push({
      icon: "\u26a1",
      label: isDynamic ? "Dynamic cost" : "Endpoint cost",
      text: isDynamic ? <>
          {cus} CUs per {cusUnit}.{" "}
          <a href="/get-started/pricing#dynamic-endpoints">Learn more</a>.
        </> : <>
          {cus} CUs.{" "}
          <a href="/get-started/pricing">Learn more</a>.
        </>
    });
  }
  if (mainnetOnly) {
    items.push({
      icon: "\ud83d\udd17",
      label: "Mainnet only",
      text: <>Testnet chains are not supported.</>
    });
  }
  if (items.length === 0) return null;
  return <div className="endpoint-meta" style={{
    border: "1px solid var(--border-color, #e2e8f0)",
    borderRadius: "8px",
    overflow: "hidden",
    marginBottom: "16px",
    fontSize: "14px",
    lineHeight: "1.6",
    maxWidth: "100%"
  }}>
      <style dangerouslySetInnerHTML={{
    __html: `
            .endpoint-meta {
              --border-color: #e2e8f0;
              --row-bg: #f8fafc;
              --label-color: #0f172a;
              --text-color: #1f2937;
            }
            .endpoint-meta a {
              color: #0f7fff !important;
              text-decoration: underline;
            }
            @media (prefers-color-scheme: dark) {
              .endpoint-meta {
                --border-color: #374151 !important;
                --row-bg: #1e293b !important;
                --label-color: #f9fafb !important;
                --text-color: #e5e7eb !important;
              }
              .endpoint-meta a {
                color: #60a5fa !important;
              }
            }
            html.dark .endpoint-meta,
            [data-theme="dark"] .endpoint-meta {
              --border-color: #374151 !important;
              --row-bg: #1e293b !important;
              --label-color: #f9fafb !important;
              --text-color: #e5e7eb !important;
            }
            html.dark .endpoint-meta a,
            [data-theme="dark"] .endpoint-meta a {
              color: #60a5fa !important;
            }
          `
  }} />
      {items.map((item, i) => <div key={i} style={{
    display: "flex",
    alignItems: "baseline",
    gap: "8px",
    padding: "10px 14px",
    borderBottom: i < items.length - 1 ? "1px solid var(--border-color, #e2e8f0)" : "none",
    backgroundColor: "var(--row-bg, #f8fafc)"
  }}>
          <span style={{
    flexShrink: 0
  }}>{item.icon}</span>
          <span style={{
    wordBreak: "break-word",
    color: "var(--text-color, #1f2937)"
  }}>
            <strong style={{
    color: "var(--label-color, #0f172a)"
  }}>
              {item.label}:
            </strong>{" "}
            {item.text}
          </span>
        </div>)}
    </div>;
};

<EndpointMeta cus={100} />

<Note>
  This is the multi-chain successor to the legacy Deep Index [Token Balances](/data-api/evm/wallet/token-balances-legacy) endpoint. The same filters - spam exclusion, unverified contracts, liquidity thresholds, USD pricing - are preserved. The headline change is that **a single request now returns balances across multiple chains.**

  Covers EVM chains and Bitcoin (pass `bitcoin` in `chains`, with an address or xpub as the path parameter). Solana balances are available today through the dedicated [Solana Wallet API](/data-api/solana/wallet/overview); bringing them into this endpoint is on the roadmap. Set `includeSparklines` or `includePnl` to enrich each token with a 7-day price sparkline or a PnL summary.
</Note>


## OpenAPI

````yaml openapi-files/data-api/api-v1.json GET /v1/wallets/{walletAddressOrPublicKey}/tokens
openapi: 3.0.0
info:
  title: Moralis Universal API 🚧
  description: This API is in early access and is subject to change.
  version: '1.0'
servers:
  - url: https://api.moralis.com
security: []
externalDocs:
  description: Moralis API Docs
  url: https://docs.moralis.com
paths:
  /v1/wallets/{walletAddressOrPublicKey}/tokens:
    get:
      tags:
        - Wallets
      summary: Get token balances from multiple chains for a specific wallet address.
      description: >-
        Get token balances from multiple chains for a specific wallet address.
        For Bitcoin wallets, filter parameters (excludeNative, excludeSpam,
        etc.) are ignored — only the native BTC balance is returned.
      operationId: getTokenBalances
      parameters:
        - name: walletAddressOrPublicKey
          required: true
          in: path
          description: The address or public key of the account
          examples:
            '0xcb1c1fde09f811b294172696404e88e658659905':
              value: '0xcb1c1fde09f811b294172696404e88e658659905'
            5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9:
              value: 5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9
            xpub:
              value: >-
                xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz
          schema:
            type: string
        - name: chains
          required: false
          in: query
          description: Chains to query
          schema:
            type: array
            items:
              type: string
              enum:
                - '0x1'
                - ethereum
                - '0x13882'
                - polygon amoy
                - '0x14a34'
                - base sepolia
                - '0x15b38'
                - chiliz
                - '0x171'
                - pulse
                - '0x19'
                - cro
                - '0x2105'
                - base
                - '0x221'
                - flow testnet
                - '0x2eb'
                - flow
                - '0x38'
                - binance
                - '0x46f'
                - lisk
                - '0x504'
                - moon beam
                - '0x505'
                - moon river
                - '0x530'
                - sei-testnet
                - '0x531'
                - sei
                - '0x61'
                - binance smart chain testnet
                - '0x64'
                - gnosis
                - '0x7e4'
                - ronin
                - '0x7e5'
                - ronin testnet
                - '0x89'
                - polygon
                - '0x8f'
                - monad
                - '0xa'
                - optimism
                - '0xa4b1'
                - arbitrum
                - '0xa86a'
                - avalanche
                - '0xaa36a7'
                - sepolia
                - '0xe708'
                - linea
                - bitcoin-mainnet
                - bitcoin
                - all
                - mainnets
                - testnets
        - name: cursor
          required: false
          in: query
          description: The cursor to the next page
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: The limit per page
          schema:
            minimum: 1
            maximum: 1000
            default: 100
            type: number
        - name: tokenAddresses
          required: false
          in: query
          description: The token addresses to be filtered in
          schema:
            example:
              - '0xdac17f958d2ee523a2206206994597c13d831ec7'
            type: array
            items:
              type: string
        - name: excludeSpam
          required: false
          in: query
          description: Should exclude spam contract
          schema:
            default: false
            example: true
            type: boolean
        - name: excludeUnverifiedContracts
          required: false
          in: query
          description: Should exclude unverified contract
          schema:
            default: false
            example: true
            type: boolean
        - name: excludeNative
          required: false
          in: query
          description: Should exclude native contract
          schema:
            default: false
            example: true
            type: boolean
        - name: maxTokenInactivity
          required: false
          in: query
          description: Should filter out contract exceeding max token inactivity
          schema:
            type: number
            example: 1
        - name: liquidityThreshold
          required: false
          in: query
          description: Should filter out contract under liquidity threshold
          schema:
            example: 0
            type: number
        - name: includeSparklines
          required: false
          in: query
          description: When true, include a 7-day hourly price sparkline for each token.
          schema:
            default: false
            example: true
            type: boolean
        - name: includePnl
          required: false
          in: query
          description: >-
            When true, include per-token PnL summary for each token. Ignored for
            Bitcoin (no PnL coverage).
          schema:
            default: false
            example: true
            type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokenBalancesResponseDto'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    GetTokenBalancesResponseDto:
      type: object
      properties:
        meta:
          description: Metadata about the multi-chain request
          allOf:
            - $ref: '#/components/schemas/MultiChainResponseMetaDto'
        address:
          type: string
          description: The wallet address
          example: '0xcb1c1fde09f811b294172696404e88e658659905'
        addressType:
          type: string
          description: The wallet address type
          enum:
            - evm
            - solana
            - bitcoin
          example: evm
        cursor:
          type: string
          description: The cursor to be used for getting the next page of results
          nullable: true
          example: eyJhbGciOi...VCaaw
        result:
          description: The list of items
          type: array
          items:
            $ref: '#/components/schemas/ChainBalanceDto'
      required:
        - meta
        - address
        - addressType
        - cursor
        - result
    MultiChainResponseMetaDto:
      type: object
      properties:
        syncedAt:
          type: object
          description: >-
            Last sync block position for each chain in the response. The literal
            'latest' indicates the chain is synced up to the latest block (no
            pinned block number available).
          additionalProperties:
            oneOf:
              - type: number
              - type: string
          example:
            '0x1': 1710000000
            solana-mainnet: latest
        unsupportedChains:
          description: Requested chains that are not supported
          nullable: true
          example:
            - '0x89'
          type: array
          items:
            type: string
        failedChains:
          description: Requested chains that are not supported
          nullable: true
          example:
            - '0x89'
          type: array
          items:
            $ref: '#/components/schemas/ChainFailureDto'
      required:
        - syncedAt
        - unsupportedChains
        - failedChains
    ChainBalanceDto:
      type: object
      properties:
        tokenAddress:
          type: string
          description: The token address
          example: '0xdac17f958d2ee523a2206206994597c13d831ec7'
        balanceRaw:
          type: string
          description: The balance
          example: '8541786218567066193031597821'
        chainId:
          type: string
          description: The chain id
          example: '0x1'
        name:
          type: string
          description: The name of the token
          example: Tether USD
          nullable: true
        symbol:
          type: string
          description: The symbol of the token
          example: USDT
          nullable: true
        decimals:
          type: number
          description: The decimals of the token
          example: 6
          nullable: true
        logo:
          type: string
          description: The logo of the token
          example: >-
            https://logo.moralis.io/0x1_0xdac17f958d2ee523a2206206994597c13d831ec7_3b83ef2ba0dba0e3385a845032e48304.webp
        possibleSpam:
          type: boolean
          description: If the token is a spam contract
          example: false
        verifiedContract:
          type: boolean
          description: If the token is a verified contract
          example: true
        balance:
          type: string
          description: The formatted balance of the token
          example: '8541786218567066193031.597821'
          nullable: true
        securityScore:
          type: number
          description: The security score of the token
          example: 99
          nullable: true
        portfolioPercentage:
          type: number
          description: The percentage of token relative to wallet's portfolio
          example: 100
          nullable: true
        usdPrice:
          type: number
          description: The token in USD price
          example: 1
          nullable: true
        usdPrice24hrUsdChange:
          type: number
          description: The token 24hr change in USD price
          example: 0
          nullable: true
        usdPrice24hrPercentChange:
          type: number
          description: The token 24hr change in USD price percent
          example: 0
          nullable: true
        usdValue:
          type: number
          description: The balance in USD price
          example: 1
          nullable: true
        usdValue24hrUsdChange:
          type: number
          description: The balance 24hr change in USD price
          example: 0
          nullable: true
        nativeToken:
          type: boolean
          description: If the token is a native token
          example: false
        derivedAddress:
          type: string
          description: >-
            The derived Bitcoin address (only present for xpub token balance
            queries)
          example: 1EfgV2Hr5CDjXPavHDpDMjmU33BA2veHy6
          nullable: true
        derivedPath:
          type: string
          description: >-
            The BIP44 derivation path (only present for xpub token balance
            queries)
          example: m/44'/0'/0'/0/0
          nullable: true
        sparkline:
          type: object
          description: >-
            Seven-day hourly price sparkline. Null when includeSparklines=false
            or when the token has insufficient price coverage.
          nullable: true
        pnl:
          type: object
          description: >-
            Per-token PnL summary. Null when includePnl=false, the token has no
            trade history, its chain is unavailable, or for Bitcoin balances.
          nullable: true
      required:
        - tokenAddress
        - balanceRaw
        - chainId
        - name
        - symbol
        - decimals
        - logo
        - possibleSpam
        - verifiedContract
        - balance
        - securityScore
        - portfolioPercentage
        - usdPrice
        - usdPrice24hrUsdChange
        - usdPrice24hrPercentChange
        - usdValue
        - usdValue24hrUsdChange
        - nativeToken
        - derivedAddress
        - derivedPath
        - sparkline
        - pnl
    ChainFailureDto:
      type: object
      properties:
        chainId:
          type: string
          description: Chain ID of the failed chain
          example: '0x89'
        code:
          type: string
          description: Error code for the failed chain
          example: INTERNAL_SERVER_ERROR
        error:
          type: object
          description: Error message for the failed chain
          example: Failed to fetch data from the chain
          nullable: true
      required:
        - chainId
        - code
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

````