Balance webhooks

INFO

Webhooks for server wallets are not yet live in production. This guide is intended to be a preview of upcoming functionality.

Privy emits webhooks whenever a server wallet's balance of a registered asset updates. This helps your application stay in sync with the assets in your server wallets, and easily track deposits, withdrawals and more.

To set up balance webhooks, follow the guide below.

Setup a webhooks URL

To start, go to the Webhooks page for your app in the Privy Dashboard and provide a destination URL for receiving webhooks.

Then, enable the 'wallet.balance_updated' event. You can next configure which assets Privy should emit 'wallet.balance_updated' events for.

Privy will emit a signed webhook to this URL whenever transaction status updates, and will retry delivery if the endpoint does not successfully respond to the original webhook.

Configure assets to track

Once you've enabled the 'wallet.balance_updated' event, you can then configure which assets you'd like to track via the Privy Dashboard.

Privy supports webhooks for native tokens (e.g. ETH, SOL) on EVM and Solana, ERC20 tokens on EVM, and SPL tokens on Solana.

Native tokens

To configure webhooks for native token balance changes, simply select the Native token asset type and provide the CAIP-2 chain ID for the network on which to track the native token.

ERC20 tokens

To configure webhooks for ERC20 token balance changes, simply select the ERC20 token asset type and provide:

• the contract address for the ERC20 token
• the CAIP-2 chain ID for the network on which to track the ERC20 token

SPL tokens

To configure webhooks for SPL token balance changes, simply select the SPL token asset type and provide:

• the mint address for the SPL token
• the CAIP-2 chain ID for the network on which to track the SPL token

Payload

When the balance of a registered asset in a server wallet changes, Privy will emit a webhooks payload with the following fields:

Field	Type	Description
event	'wallet.balance_updated'	Event name for the webhook.
wallet_id	string	ID of the wallet whose the balance updated.
asset	Object	Asset corresponding to the balance update.
asset.type	'native-token' | 'erc20' | 'spl'	Type of the asset corresponding to the balance update.
asset.address	string	Contract address for an ERC20 asset, or mint address for an SPL asset. This field will only be included for the 'erc20' and 'spl' asset.types.
change	number	Absolute change in the balance of the asset. Denominated in the native unit for the asset (e.g. ETH, not gwei, for ETH; SOL, not lamports, for SOL).
direction	'increased' | 'decreased'	Whether the balance of the asset increased or decreased.
balance	number	Updated balance of the asset in the wallet. Denominated in the native unit for the asset (e.g. ETH, not gwei, for ETH; SOL, not lamports, for SOL).
transaction_hash	string	Hash for the transaction corresponding to the balance update.
sender	string	Sender of the transaction corresponding to the balance update.
recipient	string	Recipient of the transaction corresponding to the balance update.
caip2	string	CAIP-2 chain ID of the network where the balance updated.

Example

Below is a sample webhooks payload that Privy might send on a deposit of 1000 USDC on Base into a server wallet.

{
  "event": "wallet.balance_updated",
  "wallet_id": "cm4db8x9t000ccn87pctvcg9j",
  "asset": {
    "type": "erc20",
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
  },
  "change": 10000,
  "direction": "increased",
  "balance": 15000,
  "transaction_hash": "0x2446f1fd773fbb9f080e674b60c6a033c7ed7427b8b9413cf28a2a4a6da9b56c",
  "sender": "0x59D3eB21Dd06A211C89d1caBE252676e2F3F2218",
  "recipient": "0x59D3eB21Dd06A211C89d1caBE252676e2F3F2218",
  "chain_id": "eip155:8453"
}