Get wallet action status

Check the status of asynchronous wallet actions like transfers and swaps

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

Use the getAction method from the useWalletActions hook to fetch the current status of a wallet action.

import {useWalletActions} from '@privy-io/react-auth';

const {getAction} = useWalletActions();

const action = await getAction('insert-wallet-id', 'insert-action-id');

Response

id · string

The unique identifier for the wallet action.

wallet_id · string

The ID of the wallet that initiated the action.

type · 'swap' | 'transfer'

The type of the wallet action.

status · '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.

steps · 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>"

The getAction method on the React and React Native useWalletActions hook does not yet support the include=steps query parameter. Use the REST API directly if you need step-level detail from a client-side app.

Listing all wallet actions

Use the listActions method from the useWalletActions hook to list wallet actions for a wallet.

import {useWalletActions} from '@privy-io/react-auth';

const {listActions} = useWalletActions();

const {data, next_cursor} = await listActions('insert-wallet-id', {limit: 20});

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.