Skip to main content
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

Use the withdraw method from useEarn to return vault assets to a user’s embedded wallet.
useEarn is supported starting in @privy-io/react-auth@3.51.4.
The withdraw method rejects its Promise if signing or request submission fails. If signing takes longer than the request expiry window, it throws a PrivyClientError with code embedded_wallet_request_expired. Prompt the user to retry; the expired request is not submitted.
Track the withdrawal by polling get wallet action or listening for the wallet_action.earn_withdraw.succeeded webhook.

Parameters

In React and React Native, withdraw(walletId, params) accepts the embedded wallet’s ID, not its blockchain address, and an object with the fields below. Privy routes the request to the vault’s configured EVM chain; no chain parameter is needed. The hook signs the request with the user’s signer. Never include app secrets or authorization private keys in client-side code. The same fields apply to the REST request body:
string
required
The unique identifier for the vault. Copy this from vault setup.
string
Human-readable decimal amount to withdraw (e.g. "1.5" for 1.5 OUSD). 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 OUSD on Tempo with 6 decimals). Exactly one of amount or raw_amount must be provided.

Returns

The SDK methods return a Promise for an EarnWithdrawActionResponse with status: 'pending', not onchain confirmation. In React and React Native, use action.id with getAction from useWalletActions to track completion.
string
The wallet action ID. Use this to poll status with get wallet action.
string
The ID of the wallet receiving the withdrawn funds.
'earn_withdraw'
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:4217" for Tempo).
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. "ousd"). 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.
string | null
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.

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

Use the claim convenience method on the earn ethereum incentive service to claim reward incentives.
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.
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.