Get wallet action status

Wallet actions like transfers and swaps are processed asynchronously. When your application initiates an action, the response includes an id for the created wallet action. Your application can use this ID to poll for the action’s current status.

Usage

To get the status of a wallet action, make a GET request to

https://api.privy.io/v1/wallets/{wallet_id}/actions/{action_id}

Response

string

The unique identifier for the wallet action.

string

The ID of the wallet that initiated the action.

'swap' | 'transfer'

The type of the wallet action.

'pending' | 'succeeded' | 'rejected' | 'failed'

The current status of the action.

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.

array

The steps of the wallet action. Only returned when ?include=steps is passed as a query parameter. Each step includes its own status, chain identifier, and transaction hash.

The response also includes type-specific fields depending on whether the action is a swap or transfer. See the API reference for the full response schema.

Including step details

By default, the response only returns the overall state of the action to provide visibility into whether it succeeded or failed. For more granular information, such as transaction hashes, chain IDs, and per-step statuses, pass ?include=steps as a query parameter.

curl https://api.privy.io/v1/wallets/{wallet_id}/actions/{action_id}?include=steps \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>"

Listing all wallet actions

To retrieve all wallet actions for a given wallet, make a GET request to

https://api.privy.io/v1/wallets/{wallet_id}/actions

This endpoint supports cursor-based pagination via cursor and limit query parameters.

curl https://api.privy.io/v1/wallets/{wallet_id}/actions?limit=20 \
  -u "<your-privy-app-id>:<your-privy-app-secret>" \
  -H "privy-app-id: <your-privy-app-id>"

The response includes a data array of wallet actions and a next_cursor field for pagination. See the API reference for the full request and response schema.

Polling recommendations

Wallet actions typically complete within a few seconds, but can take longer depending on network conditions. Poll infrequently and stop once the status reaches a terminal value (succeeded, rejected, or failed).

API reference

See the API reference for the full request and response schema, or the list endpoint for retrieving all actions for a wallet.

Wallet actions

Transfer

Swap

Earn

Get wallet action status

Usage

Response

Including step details

Listing all wallet actions

Polling recommendations

API reference

​Usage

​Response

​Including step details

​Listing all wallet actions

​Polling recommendations

​API reference

Usage

Response

Including step details

Listing all wallet actions

Polling recommendations

API reference