Fetch balance via API

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

The following functionality exists for wallets reconstituted server-side. More on Privy architecture here

Privy supports fetching wallet balances by wallet ID. Balances can be queried for named assets (e.g. eth, ousd) or custom assets by contract address.

To do so, make a GET request to

https://api.privy.io/v1/wallets/<wallet_id>/balance

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

Query parameters

asset · string | string[]

Named asset(s) to query (e.g. eth, ousd). Use together with chain. Cannot be used with token.

Supported values: usdc, usdc_e, eth, avax, pol, bnb, usdt, eurc, usdb, ousd, pathusd, sol, trx

Not every asset is deployed on every chain. If an asset has no canonical deployment on the requested chain, the request fails with a <asset> not supported on <chain> error — query that token by contract address with the token parameter instead.

chain · string | string[]

Chain(s) to query named assets on. Use together with asset. Cannot be used with token.

Supported mainnets: ethereum, arbitrum, avalanche, base, bsc, hypercore, hyperevm, ink, linea, megaeth, optimism, polygon, robinhood, solana, soneium, tempo, tron, unichain, worldchain, zksync_era

Supported testnets: arbitrum_sepolia, avalanche_fuji, base_sepolia, bsc_testnet, hoodi, ink_sepolia, linea_testnet, optimism_sepolia, polygon_amoy, robinhood_testnet, sepolia, solana_devnet, solana_testnet, tempo_testnet, tron_nile

token · 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.

include_currency · string

Convert balances to a fiat currency. Supported values: usd, eur. Not supported when token is provided.

Examples

Named assets

Fetch a named asset balance using asset and chain:

$ 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'

{
  "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:

$ curl --request GET 'https://api.privy.io/v1/wallets/<wallet_id>/balance?token=tempo:0x20c0000000000000000000006a37da5c996874be' \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json'

{
  "balances": [
    {
      "chain": "tempo",
      "asset": "erc20:0x20c0000000000000000000006a37da5c996874be",
      "raw_value": "1000000",
      "raw_value_decimals": 6,
      "display_values": {
        "token": "1.0"
      }
    }
  ]
}

Tron (TRX and TRC-20)

Fetch TRX balance on Tron mainnet:

$ 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'

{
  "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:

$ 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:

$ 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'

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

Full reference

Check out the API reference for more details.