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.
Privy emits webhooks when wallet actions change status, allowing your app to react to swaps, transfers, and earn activity in real time without polling.
Setup
Subscribe to wallet action events from the Configuration > Webhooks page in the Privy Dashboard.
For general webhook setup instructions, payload verification, and retry behavior, see the webhooks overview.
Webhooks can be tested at no cost in development environments. To enable webhooks in production,
upgrade to the Enterprise plan in the Privy Dashboard.
Statuses
Every wallet action moves through a predictable status lifecycle. Privy emits a webhook at each status update.
| Status | Description |
|---|
'created' | Wallet action has been queued for execution and resource ID has been returned to the caller. |
'succeeded' | All steps of the wallet action have successfully executed. This is a terminal state. |
'rejected' | The wallet action was rejected prior to executing any steps, e.g. due to a policy violation. This is a terminal state and safe to retry. |
'failed' | The wallet action failed during execution of one of its steps. Use the get wallet action endpoint with ?include=steps to inspect what went wrong at the step level. |
Action-specific payloads
All wallet action webhook payloads include a type (event name), status, and action id. Beyond these fields, payloads will include the fields present in that wallet action’s resource.
For example, the payloads for wallet_action.transfer.* webhooks include the fields when calling
fetching the transfer action resource via GET /v1/actions/{action_id} where action_id
corresponds to a transfer.
Transfer
| Event | Description |
|---|
wallet_action.transfer.created | A transfer action is created and queued |
wallet_action.transfer.succeeded | The transfer transaction confirms onchain |
wallet_action.transfer.rejected | The transfer is rejected before broadcast |
wallet_action.transfer.failed | The transfer transaction fails after broadcast |
Swap
| Event | Description |
|---|
wallet_action.swap.created | A swap action is created and queued |
wallet_action.swap.succeeded | The swap transaction confirms onchain |
wallet_action.swap.rejected | The swap is rejected before broadcast |
wallet_action.swap.failed | The swap transaction fails after broadcast |
Earn
Deposit
| Event | Description |
|---|
wallet_action.earn_deposit.created | A deposit action is created and queued |
wallet_action.earn_deposit.succeeded | The deposit transaction confirms onchain |
wallet_action.earn_deposit.rejected | The deposit is rejected before broadcast |
wallet_action.earn_deposit.failed | The deposit transaction fails after broadcast |
Withdraw
| Event | Description |
|---|
wallet_action.earn_withdraw.created | A withdrawal action is created and queued |
wallet_action.earn_withdraw.succeeded | The withdrawal transaction confirms onchain |
wallet_action.earn_withdraw.rejected | The withdrawal is rejected before broadcast |
wallet_action.earn_withdraw.failed | The withdrawal transaction fails after broadcast |
Claim incentive
| Event | Description |
|---|
wallet_action.earn_incentive_claim.created | A claim action is created and queued |
wallet_action.earn_incentive_claim.succeeded | The claim transaction confirms onchain |
wallet_action.earn_incentive_claim.rejected | The claim is rejected before broadcast |
wallet_action.earn_incentive_claim.failed | The claim transaction fails after broadcast |
