Wallet actions

Privy’s API provides abstractions for common actions taken by a wallet, including transfers, swaps, interactions with DeFi vaults, and more. These are called wallet action APIs. At a high-level, wallet action APIs abstract away the complexity of constructing blockchain transactions from scratch, managing blockchain state, and facilitating actions that may require multiple transactions or steps. Your service just integrates a simple API for wallet actions, and Privy handles the onchain complexity.

​

Taking actions with a wallet

To take an action (such as a transfer or swap) with a wallet in Privy, there are two approaches. Generally, we recommend using the abstracted wallet action APIs, which are listed below.

​

Available actions

The current set of abstracted wallet actions APIs includes the endpoints below. All endpoints begin with the route /v1/wallets/{wallet_id}/, followed by the slug.

​

Wallet action lifecycle

When your application executes a wallet action via one of the endpoints listed above, Privy creates a wallet action resource to model the action and returns it in the API response. Your application can inspect the wallet action resource to get the action’s type, status, and steps. For a detailed breakdown of action statuses, step types, and step-specific statuses, see the wallet action lifecycle page. Your application can fetch the wallet action resource for a given action or subscribe to webhooks on wallet action status updates.

​

Authorization signatures

For wallets with an owner and/or signers, requests to wallet actions APIs require an authorization signature over the request. This signature is verified by the Privy TEE to authorize request execution.

​

Gas management

Wallet action APIs support two gas payment modes: App pays (default): Privy will optimistically sponsor gas for transactions if your application has gas sponsorship enabled with sufficient credits. If gas sponsorship is not enabled, the wallet must pay gas from its own native token balance. User pays: Gas fees are paid directly from the wallet’s USDC or USDT balance, with no ETH required. Once enabled in the dashboard, any Transfer API transaction using a supported token on a supported chain will automatically use that token to cover gas fees. This mode is currently only available on the transfer API.

​

Policies

Each wallet action API has its own method in Privy’s policy language. For example, to enforce policies on the /transfer API, include a rule in the policy with method: 'transfer' to apply a rule to the API. Note that when a wallet action API is invoked, Privy does not enforce policy rules for RPC methods that may internally be used implicitly by the wallet action. As an example, when calling the /transfer API, policy rules with methods eth_sendTransaction and signAndSendTransaction are not enforced on those those API calls. Only policy rules with method: 'transfer' are enforced.