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 executing a signature, transfer, or other transaction), there are four 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: Privy automatically sponsors gas when the app has gas sponsorship enabled for the source chain, with funded prepaid credits or postpaid billing. User pays: For transfers using supported tokens and chains, gas can be paid from the wallet’s stablecoin balance. Enable this mode in the Dashboard. This mode is currently only available for the transfer API. Without a configured gas payment mode, the wallet pays network fees using the chain’s gas token. Paying gas through Privy’s user-pays mode requires configuring that mode.

​

Gas and fee sponsorship

Gas sponsorship and swap provider fee sponsorship cover different costs. Configure them separately on the app’s Fee sponsorship page in the Privy Dashboard. Without swap provider fee sponsorship, provider fees are paid from the transferred or swapped amount. Provider fee sponsorship is configured per app and applies to all supported routes, rather than individual users or executions. Sponsorship does not expand supported assets, chains, or routes. Sponsored costs use the account’s shared prepaid credit balance or postpaid billing. Postpaid billing is available on the Enterprise plan. Crypto deposit addresses require app-pays gas sponsorship on every source chain. Transfers can use other gas payment modes. Swap provider fee sponsorship is optional for both.

​

Fees and pricing

Same-chain, same-asset transfers have no exchange fees, but network gas still applies. Cross-chain transfers and swaps can incur exchange fees. For current pricing and expected output, use the crypto deposit quote API, transfer quote API, or swap quote API for the requested route and amount.

​

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.