Redeem MicroVault shares

Execute an instant redemption or request underlying liquidation.

Preview immediately before asking the shareholder to sign. The preview returns either an instant transaction or a requested redemption.

Parameter	Meaning
owner	Share owner whose MicroVault shares will be redeemed and who submits the transaction returned by the preview.
receiver	Receiving wallet for the redeemed base asset. This is usually the same address as the share owner, but it may differ.
shares	Share amount in the share token’s 18-decimal base units.
minAssetsOut	Minimum base-asset amount accepted for an instant redemption, expressed using the base asset’s decimals.

The receiver is fixed when a requested redemption is created. A later claim always sends the proceeds to that receiving wallet, even if another wallet submits the claim transaction.

Prerequisites

• An active VAULT_ID and vault contract address
• A connected shareholder wallet on Ethereum Sepolia
• The share amount in 18-decimal base units
• A Viem publicClient and walletClient

1. Preview the redemption

const response = await fetch(
  `${process.env.GROUND_API}/v2/microvaults/vaults/${vaultId}/redemptions/preview`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GROUND_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ owner, receiver: owner, shares, minAssetsOut: "990000" }),
  },
);
if (!response.ok) throw new Error(await response.text());
const { plan } = await response.json();

minAssetsOut protects only the instant route. A requested redemption settles at the USDC and source proceeds attributable to that request; the preview is an estimate, not a guarantee.

Preview mode	What the wallet signs	When the receiver gets the base asset
instant	One redemption transaction	In that transaction
requested	A request transaction, followed later by a claim transaction	When the claim transaction confirms

2. Submit the wallet transaction

const hash = await walletClient.sendTransaction({
  to: plan.directTransaction.to,
  data: plan.directTransaction.data,
  value: BigInt(plan.directTransaction.value ?? "0"),
});
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("Redemption transaction reverted");

An instant redemption transfers USDC in this transaction. A requested redemption escrows the shares while Ground exits the underlying sources.

3. Track a requested redemption

curl -sS \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/redemptions/$REQUEST_ID" \
  -H "$AUTH" | jq

Poll until status is claimable. Use the source progress and expected timing in the response to explain what remains.

4. Claim actual proceeds

const claimHash = await walletClient.writeContract({
  address: vaultAddress,
  abi: microVaultAbi,
  functionName: "claimRedeemRequest",
  args: [BigInt(requestId)],
});
await publicClient.waitForTransactionReceipt({ hash: claimHash });

Confirm the redemption

An instant redemption completes with its first receipt. A requested redemption completes after the claim receipt succeeds and the redemption endpoint reports claimed.