> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Redeem MicroVault shares

> Plan and execute an immediate or asynchronous share redemption.

Always request a redemption plan immediately before asking the shareholder to sign. The plan uses current vault liquidity to return either an immediate redemption or an asynchronous request-and-claim flow.

## Prerequisites

* An active MicroVault `VAULT_ID` and contract address
* A shareholder wallet connected to Ethereum Sepolia
* The wallet's share balance, expressed in 18-decimal base units
* A minimum acceptable USDC amount, expressed in six-decimal base units
* A Viem `publicClient` and `walletClient`

## 1. Request a current redemption plan

Request the plan immediately before constructing the wallet transaction.

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
export async function planRedemption({ vaultId, owner, shares, minAssetsOut }) {
  const response = await fetch(
    `${process.env.GROUND_API}/v2/microvaults/vaults/${vaultId}/redemption-plan`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GROUND_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ owner, receiver: owner, shares, minAssetsOut }),
    },
  );
  if (!response.ok) throw new Error(await response.text());
  return (await response.json()).plan;
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "owner": "0x3333333333333333333333333333333333333333",
  "receiver": "0x3333333333333333333333333333333333333333",
  "shares": "1000000000000000000",
  "minAssetsOut": "990000"
}
```

Use `plan.mode` to tell the shareholder what will happen:

* `instant` settles USDC in the signed transaction.
* `requested` escrows the shares while the listed `asyncLegs` are liquidated. Display `timing.expectedSeconds` and `timing.maximumSeconds` when present.

## 2. Submit the planned transaction

The plan contains the exact transaction for the connected wallet. Do not rebuild its calldata in the browser.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import type { Address, Hex } from "viem";

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

For an `instant` plan, a successful receipt is the terminal wallet transaction. Refresh the vault and activity to show the USDC received and shares burned.

For a `requested` plan, the receipt creates a redemption request. Read the resulting redemption activity to obtain its `requestId`, then show the underlying source exits and estimated completion time.

## 3. Wait for an asynchronous request

Poll the vault activity endpoint until the request becomes claimable. Do not mark the redemption complete while source exits are still processing.

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function waitUntilClaimable(vaultId, requestId) {
  for (;;) {
    const response = await fetch(
      `${process.env.GROUND_API}/v2/microvaults/vaults/${vaultId}/activity`,
      { headers: { Authorization: `Bearer ${process.env.GROUND_API_KEY}` } },
    );
    if (!response.ok) throw new Error(await response.text());
    const { items } = await response.json();
    const redemption = items.find((item) => String(item.requestId) === String(requestId));
    if (redemption?.status === "claimable") return redemption;
    if (["failed", "cancelled"].includes(redemption?.status)) {
      throw new Error(`Redemption ended with ${redemption.status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}
```

## 4. Claim the USDC

Once claimable, the shareholder calls `claimRedeemRequest` from its wallet.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const microVaultAbi = [{
  type: "function",
  name: "claimRedeemRequest",
  stateMutability: "nonpayable",
  inputs: [{ name: "requestId", type: "uint256" }],
  outputs: [{ name: "assets", type: "uint256" }],
}] as const;

const claimHash = await walletClient.writeContract({
  address: vaultAddress as Address,
  abi: microVaultAbi,
  functionName: "claimRedeemRequest",
  args: [BigInt(requestId)],
});
const claimReceipt = await publicClient.waitForTransactionReceipt({ hash: claimHash });
if (claimReceipt.status !== "success") throw new Error("Redemption claim reverted");
```

## Confirm the redemption

An immediate redemption is complete after its successful receipt. An asynchronous redemption is complete only after the claim receipt succeeds and activity reports the request as completed. At that point the share balance and vault assets should reflect the redemption and the receiver should hold the claimed USDC.

If planning returns `requested` because an instant simulation failed, follow the returned request flow rather than submitting stale instant calldata. If the available payout falls below the authorized minimum, the request requires a new minimum acceptance before it can become claimable.