Fetching balances

Privy supports fetching the wallet balance given the address and chain ID.

Individual wallet balance

Privy allows you to query the balance of a native asset or any other tokens in an individual wallet.

To do so, make a POST request to:

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

Body

In the request body, include the following:

Field	Type	Description
chain_id	string	A CAIP-2 chain ID for the blockchain to query balances on.
token_addresses	string[]	An array of token addresses for tokens whose balance you’d like to fetch.

Response

In the response, Privy will return the following:

Field	Type	Description
native_balance	string	Balance of the native token (e.g. ETH or SOL) in the wallet as a decimal string. Balances are denominated directly in the native token (e.g. 0.1 SOL is “0.1”).
token_balances	{address: string; balance: string}[]	Array of {address, balance} for the balances of the requested tokenAddresses. Balances are denominated in the base unit of the token (e.g. 1 USDC will be “1.0”).

Example

For example, you might send the following cURL request to get the balance for a wallet.

$ curl --request POST https://api.privy.io/v1/wallets/<wallet_id>/balance \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "privy-authorization-signature: <authorization-signature-for-request>" \
-H 'Content-Type: application/json' \
-d '{
  "chain_id": "eip155:1",
  "token_addresses" : ["0x3371B68e1FDfc48159b4834BEC8E29d0F485995A", "0x12c4bB91308ed306d1330C303AA0aad3D22c4158"]
}'

The request would receive the following response.

{
  "native_balance": "1",
  "token_balances": [
    {
      "address": "0x3371B68e1FDfc48159b4834BEC8E29d0F485995A",
      "balance": "0.5"
    },
    {
      "address": "0x12c4bB91308ed306d1330C303AA0aad3D22c4158",
      "balance": "0.5"
    }
  ]
}

Aggregated balances

Privy also supports fetching aggregated balances for a batch of wallets in a single network call.

To do so, make a POST request to

https://api.privy.io/v1/balance

Body

In the request body, include the following:

Field	Type	Description
wallet_ids	string[]	An array of wallet IDs to fetch balances for.
chain_id	string	A CAIP-2 chain ID for the blockchain to query balances on.

Response

In the response, Privy will return the following:

Field	Type	Description
balance	string	An a decimal string for the aggregated balance across all requested wallets of the requested token. Balances are denominated in the base unit of the token (e.g. 1 USDC will be “1.0”).

Example

For example, you might send the following cURL request to get the balance for a batch of wallets.

$ curl --request POST https://api.privy.io/v1/wallets/balance/batch \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "privy-authorization-signature: <authorization-signature-for-request>" \
-H 'Content-Type: application/json' \
-d '{
  "tag": "12345"
  "chain_id": "eip155:1",
}'

The request would receive the following response, representing the native token balance accross all the wallets with the specified tag.

{
  "balance": "10"
}