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

# Withdrawals Guide

> Integrate withdrawal authorization and order submission

Withdrawals are routed through the WithdrawQueue flow.

<Warning>
  **Breaking change in v0.5.0**: All withdrawal functions now identify accounts by
  `vaultName` instead of `yieldType`. See the [migration guide](/v0.5.3/intro/products/earn/developers/changelog#migration-guide).
</Warning>

<Info>
  Recommended sequence: `getVaultsByConfig()` →
  `prepareWithdrawalAuthorization()` → `prepareWithdrawal()`.
</Info>

## Step 0: Discover the Account

Before making any withdrawal calls, discover your account and record its name:

```typescript theme={null}
import { getVaultsByConfig, YieldType } from '@paxoslabs/amplify-sdk'

const [vault] = await getVaultsByConfig({
  yieldType: YieldType.CORE,
  chainId: 1,
})

// vault.name is used in all subsequent calls
```

## Step 1: Check Authorization

```typescript theme={null}
import {
  prepareWithdrawalAuthorization,
  isWithdrawApprovalAuth,
} from '@paxoslabs/amplify-sdk'

const auth = await prepareWithdrawalAuthorization({
  vaultName: vault.name,
  wantAsset: USDC,
  withdrawAmount: '10.0',
  userAddress,
  chainId: 1,
})

if (isWithdrawApprovalAuth(auth)) {
  const approvalHash = await walletClient.writeContract(auth.txData)
  await publicClient.waitForTransactionReceipt({ hash: approvalHash })
}
```

## Step 2: Submit Withdrawal Order

```typescript theme={null}
import { prepareWithdrawal } from '@paxoslabs/amplify-sdk'

const txData = await prepareWithdrawal({
  vaultName: vault.name,
  wantAsset: USDC,
  withdrawAmount: '10.0',
  userAddress,
  chainId: 1,
})

const hash = await walletClient.writeContract(txData)
```

## Optional Low-Level APIs

* [`prepareWithdrawOrderTxData`](/v0.5.3/intro/products/earn/developers/api/prepareWithdrawOrderTxData) for manual order construction
* [`prepareApproveWithdrawOrderTxData`](/v0.5.3/intro/products/earn/developers/api/prepareApproveWithdrawOrderTxData) for manual approval construction
* [`prepareCancelWithdrawOrderTxData`](/v0.5.3/intro/products/earn/developers/api/prepareCancelWithdrawOrderTxData) for order cancellation flows

## Checking Withdrawal Status

After submitting a withdrawal order, use `getWithdrawalRequests` to poll for status updates:

```typescript theme={null}
import { getWithdrawalRequests } from '@paxoslabs/amplify-sdk'

const { withdrawalRequests } = await getWithdrawalRequests({
  userAddress,
  chainId: 1,
  status: 'PENDING',
})

for (const request of withdrawalRequests) {
  console.log(`${request.id}: ${request.status} — ${request.orderAmount}`)
}
```

### Withdrawal Request Statuses

| Status           | Description                                               |
| ---------------- | --------------------------------------------------------- |
| `PENDING`        | Order submitted, awaiting fulfillment by account operator |
| `COMPLETE`       | Order fulfilled, stablecoins sent to user                 |
| `PENDING_REFUND` | Order is being refunded                                   |
| `REFUNDED`       | Account shares returned to user                           |

<Info>
  Withdrawal orders are fulfilled by the account operator, typically within 24
  hours of submission. Use `getWithdrawalRequests` to display current status to
  users.
</Info>

## Canceling a Withdrawal

Withdrawal requests with a `PENDING` status can be canceled and refunded to the user in a specified asset. This uses a two-step process: retrieve the withdrawal requests, then submit the cancellation.

### Step 1: Retrieve Withdrawal Requests

Use `getWithdrawalRequests` to fetch pending requests for a given user address:

```typescript theme={null}
import {
  getWithdrawalRequests,
  prepareCancelWithdrawOrderTxData,
} from '@paxoslabs/amplify-sdk'

const { withdrawalRequests } = await getWithdrawalRequests({
  userAddress,
  chainId: 1,
  status: 'PENDING',
})
```

### Step 2: Submit Cancellation

Prepare and send the transaction to cancel a specific pending withdrawal request:

```typescript theme={null}
const requestToCancel = withdrawalRequests[0];

const txData = await prepareCancelWithdrawOrderTxData({
  vaultName: vault.name,
  wantAsset: refundTokenAddress,
  chainId: requestToCancel.chainId,
  orderIndex: BigInt(requestToCancel.orderIndex),
});

const hash = await walletClient.writeContract(txData);
```

<Info>
  Only the order owner can cancel their withdrawal request. The `wantAsset`
  specifies the token the user will receive as a refund.
</Info>

## Smart Wallet Behavior

In auto mode, smart wallets are routed to approval mode so approve + withdraw can
be batched atomically.

## Related

* [getVaultsByConfig](/v0.5.3/intro/products/earn/developers/api/getVaultsByConfig) - Discover account names
* [Withdrawals API](/v0.5.3/intro/products/earn/developers/api/prepareWithdrawal)
* [Smart Wallets Guide](/v0.5.3/intro/products/earn/developers/guides/smart-wallets)