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

# Fetch balance via API

> Fetch wallet balance by wallet ID using the Privy Node.js SDK

<Warning>
  The following functionality exists for [wallets reconstituted
  server-side](/wallets/wallets/create/create-a-wallet). More on [Privy architecture
  here](/security/wallet-infrastructure/architecture)
</Warning>

<View title="REST API" icon="terminal">
  Privy supports fetching wallet balances by wallet ID. Balances can be queried for **named assets** (e.g. `eth`, `usdc`) or **custom assets** by contract address.

  To do so, make a `GET` request to

  ```bash theme={"system"}
  https://api.privy.io/v1/wallets/<wallet_id>/balance
  ```

  replacing `<wallet_id>` with the ID of your desired wallet.

  ## Query parameters

  <ParamField query="asset" type="string | string[]">
    Named asset(s) to query (e.g. `eth`, `usdc`). Use together with `chain`. Cannot be used with `token`.

    Supported values: `usdc`, `usdc.e`, `eth`, `pol`, `usdt`, `eurc`, `usdb`, `sol`, `trx`
  </ParamField>

  <ParamField query="chain" type="string | string[]">
    Chain(s) to query named assets on. Use together with `asset`. Cannot be used with `token`.

    Supported values: `ethereum`, `arbitrum`, `base`, `tempo`, `linea`, `optimism`, `polygon`, `solana`, `tron`, `zksync_era`, `sepolia`, `arbitrum_sepolia`, `base_sepolia`, `linea_testnet`, `optimism_sepolia`, `polygon_amoy`, `solana_devnet`, `solana_testnet`, `tron_nile`
  </ParamField>

  <ParamField query="token" type="string | string[]">
    Token contract address(es) in `chain:address` format. Use this to query balances for arbitrary ERC-20 or SPL tokens.

    * EVM example: `base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
    * Solana example: `solana:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
    * Tron example: `tron:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`

    Cannot be used together with `asset`/`chain` or `include_currency`. Up to 10 tokens per request.
  </ParamField>

  <ParamField query="include_currency" type="string">
    Convert balances to a fiat currency. Supported values: `usd`, `eur`. Not supported when `token` is
    provided.
  </ParamField>

  ## Examples

  ### Named assets

  Fetch a named asset balance using `asset` and `chain`:

  ```bash theme={"system"}
  $ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?asset=eth&chain=base&include_currency=usd' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json'
  ```

  ```json theme={"system"}
  {
    "balances": [
      {
        "chain": "base",
        "asset": "eth",
        "raw_value": "1000000000000000000",
        "raw_value_decimals": 18,
        "display_values": {
          "eth": "0.001",
          "usd": "2.56"
        }
      }
    ]
  }
  ```

  ### Custom tokens

  Fetch the balance of an arbitrary token by contract address using the `token` parameter:

  ```bash theme={"system"}
  $ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?token=base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json'
  ```

  ```json theme={"system"}
  {
    "balances": [
      {
        "chain": "base",
        "asset": "erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "raw_value": "1000000",
        "raw_value_decimals": 6,
        "display_values": {
          "token": "1.0"
        }
      }
    ]
  }
  ```

  ### Tron (TRX and TRC-20)

  Fetch TRX balance on Tron mainnet:

  ```bash theme={"system"}
  $ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?asset=trx&chain=tron&include_currency=usd' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json'
  ```

  ```json theme={"system"}
  {
    "balances": [
      {
        "chain": "tron",
        "asset": "trx",
        "raw_value": "1000000",
        "raw_value_decimals": 6,
        "display_values": {
          "trx": "1.0",
          "usd": "0.23"
        }
      }
    ]
  }
  ```

  Fetch USDT on Tron mainnet:

  ```bash theme={"system"}
  $ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?asset=usdt&chain=tron' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json'
  ```

  Fetch a custom TRC-20 token by contract address:

  ```bash theme={"system"}
  $ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?token=tron:TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t' \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>" \
  -H 'Content-Type: application/json'
  ```

  <Note>
    Use `chain=tron_nile` for the Tron Nile testnet. Supported named Tron assets: `trx`, `usdt`,
    `usdc`. All Tron assets use 6 decimal places.
  </Note>

  ### Full reference

  Check out the [API reference](/api-reference/wallets/get-balance) for more details.
</View>

<View title="NodeJS" icon="node-js">
  To get a wallet's balance using the Node SDK, use the `balance.get` method on the `wallets()` interface of the Privy client.

  ### Named assets

  Fetch balances for named assets like `eth` or `usdc` using the `asset` and `chain` parameters:

  ```typescript theme={"system"}
  import {PrivyClient} from '@privy-io/node';

  const privy = new PrivyClient({
    appId: 'insert-your-app-id',
    appSecret: 'insert-your-app-secret'
  });

  const balance = await privy.wallets().balance.get('insert-wallet-id', {
    asset: 'usdc',
    chain: 'ethereum'
  });
  console.log(balance);
  ```

  ### Custom tokens

  Fetch balances for arbitrary ERC-20 or SPL tokens by contract address using the `token` parameter. The format is `chain:address`:

  ```typescript {skip-check} theme={"system"}
  const balance = await privy.wallets().balance.get('insert-wallet-id', {
    token: 'base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
  });
  console.log(balance);
  ```

  Multiple tokens can be queried in a single request (up to 10):

  ```typescript {skip-check} theme={"system"}
  const balance = await privy.wallets().balance.get('insert-wallet-id', {
    token: [
      'base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
      'ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
    ]
  });
  console.log(balance);
  ```

  <Warning>
    The `token` parameter cannot be used together with `asset`/`chain` or `include_currency`.
  </Warning>

  ### Tron

  Fetch TRX or TRC-20 balances on Tron using `asset` and `chain`:

  ```typescript {skip-check} theme={"system"}
  const balance = await privy.wallets().balance.get('insert-wallet-id', {
    asset: 'trx',
    chain: 'tron'
  });
  console.log(balance);
  ```

  Supported Tron assets: `trx`, `usdt`, `usdc`. Use `chain: 'tron_nile'` for the testnet.

  ### Parameters and returns

  Check out the [API reference](/api-reference/wallets/get-balance) for more details.
</View>

<View title="Java" icon="java">
  To get a wallet's balance by ID, use the `getBalance` method.

  ### Named assets

  ```java theme={"system"}
  try {
      WalletBalanceResponse response = privyClient
          .wallets()
          .balance()
          .walletId("insert-wallet-id")
          .call();

      if (response.object().isPresent()) {
          WalletBalanceResponseBody balanceBody = response.object().get();

          // The response contains a list of balances (one per chain/asset combination)
          for (Balance balance : balanceBody.balances()) {
              String rawValue = balance.rawValue();
              double rawValueDecimals = balance.rawValueDecimals();
              System.out.println("Balance: " + rawValue);
              System.out.println("Balance (decimals): " + rawValueDecimals);
              System.out.println("Chain: " + balance.chain());
              System.out.println("Asset: " + balance.asset());
          }
      }
  } catch (APIException e) {
      String errorBody = e.bodyAsString();
      System.err.println(errorBody);
  } catch (Exception e) {
      System.err.println(e.getMessage());
  }
  ```

  ### Custom tokens

  Fetch balances for arbitrary ERC-20 or SPL tokens by contract address using the `token` parameter in `chain:address` format:

  ```java theme={"system"}
  try {
      WalletBalanceResponse response = privyClient
          .wallets()
          .balance()
          .walletId("insert-wallet-id")
          .token("base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
          .call();

      if (response.object().isPresent()) {
          WalletBalanceResponseBody balanceBody = response.object().get();
          for (Balance balance : balanceBody.balances()) {
              System.out.println("Chain: " + balance.chain());
              System.out.println("Asset: " + balance.asset());
              System.out.println("Balance: " + balance.rawValue());
          }
      }
  } catch (APIException e) {
      System.err.println(e.bodyAsString());
  }
  ```

  <Warning>
    The `token` parameter cannot be used together with `asset`/`chain` or `includeCurrency`.
  </Warning>

  ### Parameters

  <ParamField body="walletId" type="String" required>
    The ID of the wallet to retrieve balance for.
  </ParamField>

  <ParamField body="token" type="String">
    Token contract address in `chain:address` format (e.g.,
    `base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`). Cannot be used with `asset`/`chain`.
  </ParamField>

  ### Returns

  The `WalletBalanceResponse` object contains balance information for the wallet.

  <ResponseField name="balances()" type="List<Balance>">
    List of balance objects for different chain/asset combinations.

    <Expandable defaultOpen="true">
      <ResponseField name="rawValue()" type="String">
        Balance value as a string in the smallest denomination to maintain precision.
      </ResponseField>

      <ResponseField name="rawValueDecimals()" type="double">
        Balance value as a decimal number.
      </ResponseField>

      <ResponseField name="chain()" type="BalanceChainType">
        The blockchain type (e.g., ETHEREUM, SOLANA, BASE, POLYGON).
      </ResponseField>

      <ResponseField name="asset()" type="Asset">
        The asset type (e.g., NATIVE, USDC, USDT) or the token contract address for custom assets.
      </ResponseField>

      <ResponseField name="displayValues()" type="Map<String, String>">
        Formatted display values for the balance in different currencies/formats.
      </ResponseField>
    </Expandable>
  </ResponseField>
</View>

<View title="Rust" icon="rust">
  To get a wallet's balance using the Rust SDK, use the `get_balance` method on the `wallets()` interface of the Privy client.

  ### Named assets

  ```rust theme={"system"}
  use privy_rs::PrivyClient;

  let client = PrivyClient::new(app_id, app_secret)?;

  // For a Solana wallet
  let balance = client
      .wallets()
      .balance()
      .get(
          "insert-wallet-id",
          &GetWalletBalanceAsset::String(GetWalletBalanceAssetString::Sol),
          &GetWalletBalanceChain::String(GetWalletBalanceChainString::Solana),
          None, // optional: currency conversion (e.g., Some(GetWalletBalanceIncludeCurrency::Usd))
      )
      .await?;
  ```

  ### Custom tokens

  Fetch balances for arbitrary ERC-20 or SPL tokens by contract address using the `token` parameter in `chain:address` format:

  ```rust theme={"system"}
  use privy_rs::PrivyClient;

  let client = PrivyClient::new(app_id, app_secret)?;

  let balance = client
      .wallets()
      .balance()
      .get_with_token(
          "insert-wallet-id",
          &["base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"],
      )
      .await?;
  ```

  <Warning>
    The `token` parameter cannot be used together with `asset`/`chain` or `include_currency`.
  </Warning>

  ### Parameters and returns

  See the Rust SDK documentation for detailed parameter and return types, including embedded examples:

  * [WalletsBalanceClient::get](https://docs.rs/privy-rs/latest/privy_rs/subclients/struct.WalletsBalanceClient.html)
  * [GetWalletBalanceResponse](https://docs.rs/privy-rs/latest/privy_rs/generated/types/struct.GetWalletBalanceResponse.html)

  For REST API details, see the [API reference](/api-reference/wallets/get-balance).
</View>

<View title="Go" icon="golang">
  Use the `Get` method on the `Balance` service to fetch the balance of a wallet.

  ### Named assets

  ```go theme={"system"}
  balance, err := client.Wallets.Balance.Get(
      context.Background(),
      "wallet-id",
      privy.WalletBalanceGetParams{
          Chain: privy.WalletBalanceGetParamsChainUnion{
              OfWalletBalanceGetsChainString: privy.String("eip155:1"),
          },
      },
  )
  if err != nil {
      log.Fatalf("failed to get balance: %v", err)
  }

  fmt.Println("Balance:", balance)
  ```

  ### Custom tokens

  Fetch balances for arbitrary ERC-20 or SPL tokens by contract address using the `Token` parameter in `chain:address` format:

  ```go theme={"system"}
  balance, err := client.Wallets.Balance.Get(
      context.Background(),
      "wallet-id",
      privy.WalletBalanceGetParams{
          Token: privy.WalletBalanceGetParamsTokenUnion{
              OfString: privy.String("base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"),
          },
      },
  )
  if err != nil {
      log.Fatalf("failed to get balance: %v", err)
  }

  fmt.Println("Balance:", balance)
  ```

  <Warning>
    The `Token` parameter cannot be used together with `Asset`/`Chain` or `IncludeCurrency`.
  </Warning>

  ### Parameters and returns

  See the [API reference](/api-reference/wallets/get-balance) for more details.
</View>

<View title="Ruby" icon="gem">
  Use the `get` method on the `balance` service to fetch the balance of a wallet.

  ### Usage

  ```ruby theme={"system"}
  balance = client.wallets.balance.get(
    "wallet-id",
    asset: :usdc,
    chain: :ethereum
  )

  balance.balances.each do |entry|
    puts(entry.asset, entry.chain, entry.raw_value)
  end
  ```

  ### Parameters and Returns

  See the [API reference](/api-reference/wallets/get-balance) for more details.
</View>