Withdraw assets

Redeem vault shares and return assets — plus any accrued yield — to the wallet using the withdraw endpoint. The returned amount reflects the original deposit plus yield earned.

View the full API reference for the withdraw endpoint.

If your app has gas sponsorship configured, usage of the /earn/ethereum/withdraw endpoint will be gas-sponsored by default. There is no need to specify additional parameters for sponsorship.

Withdrawal amount

Your app can withdraw any amount up to the wallet’s current assets_in_vault balance. To withdraw everything, query the wallet’s position first and pass the full assets_in_vault value as the raw_amount. Because yield accrues continuously, the redeemable balance may be slightly higher at withdrawal time than when the position was last queried.

For a full withdrawal, your app can read the wallet’s assets_in_vault from the position endpoint and pass that value directly. Any additional yield accrued between the query and the withdrawal will remain in the vault as residual shares.

Liquidity considerations

Withdrawals depend on available liquidity in the underlying vault. Your app should check the vault’s available_liquidity_usd from the get vault details endpoint before initiating large withdrawals.

Usage

Node SDK
REST API

Use the withdraw convenience method on the earn ethereum service to withdraw assets from a vault.

const response = await privy.wallets().earn().ethereum().withdraw('insert-wallet-id', {
  vault_id: '<your-vault-id>',
  amount: '1.05',
  authorization_context: {
    authorization_private_keys: ['<authorization-private-key>'],
  },
});

The method returns an EarnWithdrawActionResponse with the pending wallet action. Poll the status with get wallet action, or listen for the wallet_action.earn_withdraw.succeeded webhook.

To withdraw funds via REST API, make a POST request to:

https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/withdraw

Parameters

string

required

The unique identifier for the vault.

string

Human-readable decimal amount to withdraw (e.g. "1.5" for 1.5 USDC). Exactly one of amount or raw_amount must be provided.

string

Amount to withdraw in the token’s smallest unit (e.g. "1500000" for 1.5 USDC with 6 decimals). Exactly one of amount or raw_amount must be provided.

Wallets with owner_id present must provide an authorization signature as a request header for withdraw operations.

Returns

string

The wallet action ID. Use this to poll status with get wallet action.

string

The ID of the wallet receiving the withdrawn funds.

string

The action type. Always "earn_withdraw" for this endpoint.

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

The current status of the withdrawal action.

string

CAIP-2 chain identifier for the withdrawal (e.g. "eip155:8453").

string

The ID of the vault being withdrawn from.

string

The ERC-4626 vault contract address.

string

The address of the underlying asset token.

string

Amount withdrawn in the token’s smallest unit.

string | undefined

Human-readable decimal amount (e.g. "1.5"). Only present when the token is known in the asset registry.

string | undefined

Asset identifier (e.g. "usdc"). Only present when the token is known in the asset registry.

number | undefined

Number of decimals for the underlying asset. Only present when the token is known in the asset registry.

Vault shares redeemed in base units. null until the action succeeds.

string

ISO 8601 timestamp of when the action was created.

array | undefined

The execution steps. Only returned if ?include=steps is provided on a GET request.

Example

curl -X POST https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/withdraw \
  -H "privy-app-id: <your-app-id>" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "vault_id": "<your-vault-id>",
    "amount": "1.05"
  }'

Example response

{
  "id": "<action-id>",
  "wallet_id": "<your-wallet-id>",
  "type": "earn_withdraw",
  "status": "pending",
  "caip2": "eip155:8453",
  "vault_id": "<your-vault-id>",
  "vault_address": "0x5224d0c05698eD4a97C771B62095929F293f1D60",
  "asset_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "raw_amount": "1050000",
  "amount": "1.05",
  "asset": "usdc",
  "decimals": 6,
  "share_amount": null,
  "created_at": "2025-04-01T12:00:00.000Z"
}

Track the withdrawal by polling get wallet action or listening for the wallet_action.earn_withdraw.succeeded webhook.

Claim reward incentives

Some vaults distribute additional token incentives on top of base yield. Collect these with the claim endpoint. Claims operate at the chain level — pass a chain name rather than a vault ID. For apps with multiple vaults on the same chain, a single claim collects rewards across all vaults.

Usage

Node SDK
REST API

Use the claim convenience method on the earn ethereum incentive service to claim reward incentives.

const response = await privy.wallets().earn().ethereum().incentive().claim('insert-wallet-id', {
  chain: 'base',
  authorization_context: {
    authorization_private_keys: ['<authorization-private-key>'],
  },
});

The method returns an EarnIncentiveClaimActionResponse with the pending wallet action. Claims operate at the chain level and collect rewards across all vaults on the specified chain.

To claim rewards via REST API, make a POST request to:

https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/incentive/claim

Parameters

string

required

The blockchain network on which to perform the incentive claim (e.g. "base", "ethereum", "arbitrum"). Claims collect rewards across all vaults on the specified chain.

Wallets with owner_id present must provide an authorization signature as a request header for claim operations.

Returns

string

The wallet action ID. Use this to poll status with get wallet action.

string

The ID of the wallet claiming rewards.

string

The action type. Always "earn_incentive_claim" for this endpoint.

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

The current status of the claim action.

string

The chain name for the claim.

array | null

List of rewards claimed, each with token_address, token_symbol, token_decimals, and amount. Populated after the preparation step fetches claimable rewards.

string

ISO 8601 timestamp of when the action was created.

array | undefined

The execution steps. Only returned if ?include=steps is provided on a GET request.

Example

curl -X POST https://api.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/incentive/claim \
  -H "privy-app-id: <your-app-id>" \
  -H "Authorization: Basic <credentials>" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "base"
  }'

Example response

{
  "id": "<action-id>",
  "wallet_id": "<your-wallet-id>",
  "type": "earn_incentive_claim",
  "status": "pending",
  "chain": "base",
  "rewards": [
    {
      "token_address": "0x1234567890abcdef1234567890abcdef12345678",
      "token_symbol": "MORPHO",
      "token_decimals": 18,
      "amount": "115631364898103632676"
    }
  ],
  "created_at": "2025-04-01T12:00:00.000Z"
}

A rejected status means the action failed before any transaction was signed or broadcast — for example, due to insufficient balance or a policy violation. Your app can safely retry the request. A failed status means a transaction was broadcast but reverted onchain. Inspect the action’s steps for details.

Next steps

Claim rewards

Collect additional token incentives distributed by the vault.

Wallet actions

Transfer

Swap

Earn

Withdrawal amount

Liquidity considerations

Usage

Parameters

Returns

Example

Claim reward incentives

Usage

Parameters

Returns

Example

Next steps

Claim rewards

​Withdrawal amount

​Liquidity considerations

​Usage

​Parameters

​Returns

​Example

​Claim reward incentives

​Usage

​Parameters

​Returns

​Example

​Next steps

Claim rewards

Withdrawal amount

Liquidity considerations

Usage

Parameters

Returns

Example

Claim reward incentives

Usage

Parameters

Returns

Example

Next steps