Withdraw from a vault

Withdraw any amount, just the yield, or the entire position from an enabled yield vault.

A withdrawal moves assets from your organization’s fee wrapper back to the user’s wallet. Amounts are specified in the underlying asset (vault shares are not exposed in the API), or pass "MAX" to exit the position entirely.

Earn is in early access. Contact us to enable it for your organization.

Submit the withdrawal

Submit an ACTIVITY_TYPE_EARN_WITHDRAW activity with:

• the wrapperAddress holding the position, from list_earn_positions
• the signWith wallet account to withdraw to and sign with
• the amountValue in raw on-chain units of the underlying asset (e.g. "500000" for 0.50 USDC), or the literal "MAX" to withdraw the entire position
• the CAIP-2 chain in chainCaip2, and optionally sponsor for gas sponsorship

See Withdraw from Earn vault in the API reference for the full request/response schema and cURL example. The activity result contains only a poll handle, withdrawRequestId.

Withdrawals always work, even when deposits to the wrapper are paused.

Full exit with MAX

"amountValue": "MAX" redeems the wallet’s exact live share balance in the wrapper, so the position closes completely without leaving dust.

A MAX withdrawal resets the position’s lifetime accounting: after it confirms, totalDeposited and totalWithdrawn in list_earn_positions start again from zero for that wrapper.

Positions in wrappers you have since replaced (after a fee change) remain withdrawable. Target the old wrapper’s address.

Claiming yield only

To pay out yield without touching principal, withdraw exactly the yield amount. Compute it from the position’s raw fields:

JavaScript

const { positions } = await client.request(
  "/public/v1/query/list_earn_positions",
  {
    organizationId: "<ORGANIZATION_ID>",
    walletAddress: "<WALLET_ADDRESS>",
  },
);

const p = positions.find(
  (p) => p.wrapperAddress === "<WRAPPER_ADDRESS>",
);

// These are raw on-chain unit strings, so use BigInt rather than floats.
const yieldEarned =
  BigInt(p.currentValue) - BigInt(p.totalDeposited) + BigInt(p.totalWithdrawn);

// Withdraw the yield, leave the principal earning.
await client.request("/public/v1/submit/earn_withdraw", {
  type: "ACTIVITY_TYPE_EARN_WITHDRAW",
  timestampMs: String(Date.now()),
  organizationId: "<ORGANIZATION_ID>",
  parameters: {
    wrapperAddress: "<WRAPPER_ADDRESS>",
    signWith: "<WALLET_ADDRESS>",
    amountValue: yieldEarned.toString(),
    chainCaip2: "eip155:8453",
    sponsor: false,
  },
});

Poll withdrawal status (required)

As with deposits, a COMPLETED activity means the transaction was enqueued for broadcast, not that it confirmed. Poll get_earn_withdraw_status until it reports COMPLETED (included on-chain) or FAILED.

Poll with the withdrawRequestId from the activity result. status is PENDING, COMPLETED, or FAILED; on COMPLETED the response carries the withdrawTxHash, and on FAILED it includes an error field with the reason.

Gas

Identical to deposits: sponsor: true uses Gas Station (Pro plan or higher); otherwise the signWith wallet pays gas natively. See Gas: sponsored vs self-funded.

Next steps

• Track positions to verify the position after withdrawing