Skip to main content

​
Withdraw funds

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.

​
Partial and full withdrawals

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. If the vault’s lending markets are fully utilized, a withdrawal may partially fill or fail. Your app should check the vault’s available_liquidity_usd from the get vault details endpoint before initiating large withdrawals.

​
Usage

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

​
id
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.
​
share_amount
string | null
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

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

​
id
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"
}
Claiming rewards is separate from withdrawing yield. To realize deposit earnings, use the withdraw endpoint. Claiming does not affect withdrawals or ongoing earnings.

​
Next steps

Setup

Deploy a fee wrapper and configure a vault.

Deposit funds

Deposit assets from a wallet into a yield vault.

Manage positions

Query vault positions and track activity with webhooks.