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://auth.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/withdraw

Parameters

vault_id

string

required

The unique identifier for the vault.

amount

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.

raw_amount

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.

wallet_id

string

The ID of the wallet receiving the withdrawn funds.

type

string

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

status

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

The current status of the withdrawal action.

caip2

string

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

vault_id

string

The ID of the vault being withdrawn from.

vault_address

string

The ERC-4626 vault contract address.

asset_address

string

The address of the underlying asset token.

raw_amount

string

Amount withdrawn in the token’s smallest unit.

amount

string | undefined

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

asset

string | undefined

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

decimals

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.

created_at

string

ISO 8601 timestamp of when the action was created.

steps

array | undefined

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

Example

curl -X POST https://auth.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://auth.privy.io/api/v1/wallets/{wallet_id}/earn/ethereum/incentive/claim

Parameters

chain

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.

wallet_id

string

The ID of the wallet claiming rewards.

type

string

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

status

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

The current status of the claim action.

chain

string

The chain name for the claim.

rewards

array | null

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

created_at

string

ISO 8601 timestamp of when the action was created.

steps

array | undefined

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

Example

curl -X POST https://auth.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",
      "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

Wallet actions

Transfer

Swap

Earn

Documentation Index

​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