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

# useDeposit

> Manage the multi-step deposit flow for a settlement leg.

## Import

```tsx theme={null}
import { useDeposit } from '@keystoneos/react';
```

## Usage

```tsx theme={null}
function DepositAction({ settlementId, legIndex }) {
  const { status, depositInfo, txHash, error, fetchInfo, deposit } = useDeposit(
    settlementId,
    legIndex,
  );

  return (
    <div>
      <p>Status: {status}</p>

      {status === 'idle' && (
        <button onClick={deposit}>Deposit</button>
      )}

      {(status === 'fetching_info' || status === 'approving' || status === 'depositing') && (
        <p>Processing: {status.replace('_', ' ')}...</p>
      )}

      {status === 'deposit_confirmed' && txHash && (
        <p>Deposit confirmed. TX: {txHash}</p>
      )}

      {status === 'error' && (
        <p>Error: {error}</p>
      )}
    </div>
  );
}
```

## Parameters

| Parameter      | Type     | Required | Description                                |
| -------------- | -------- | -------- | ------------------------------------------ |
| `settlementId` | `string` | Yes      | The settlement UUID.                       |
| `legIndex`     | `number` | Yes      | The index of the leg to deposit (0-based). |

## Return Type

```typescript theme={null}
interface UseDepositResult {
  status: DepositStatus;
  depositInfo: DepositInfo | null;
  txHash: string | null;
  error: string | null;
  fetchInfo: () => Promise<DepositInfo>;
  deposit: () => Promise<void>;
}
```

| Property      | Type                  | Description                                                   |
| ------------- | --------------------- | ------------------------------------------------------------- |
| `status`      | `DepositStatus`       | Current step in the deposit flow.                             |
| `depositInfo` | `DepositInfo \| null` | Pre-encoded calldata and metadata (available after fetching). |
| `txHash`      | `string \| null`      | Transaction hash (available after deposit confirmation).      |
| `error`       | `string \| null`      | Error message if any step failed.                             |
| `fetchInfo`   | `function`            | Fetch deposit info without executing. Useful for preview.     |
| `deposit`     | `function`            | Execute the full deposit flow (fetch + approve + deposit).    |

### DepositStatus Values

| Status                 | Description                                |
| ---------------------- | ------------------------------------------ |
| `"idle"`               | No deposit in progress.                    |
| `"fetching_info"`      | Fetching deposit calldata from the API.    |
| `"checking_balance"`   | Checking token balance (Tier 3 only).      |
| `"approving"`          | ERC-20 approval transaction in progress.   |
| `"approval_confirmed"` | Approval confirmed, proceeding to deposit. |
| `"depositing"`         | Deposit transaction in progress.           |
| `"deposit_confirmed"`  | Deposit confirmed on-chain.                |
| `"error"`              | A step failed. Check `error` for details.  |

### DepositInfo Object

| Field              | Type     | Description                      |
| ------------------ | -------- | -------------------------------- |
| `calldata`         | `string` | Encoded `depositLeg()` calldata. |
| `escrowAddress`    | `string` | Escrow contract address.         |
| `chainId`          | `number` | Blockchain network.              |
| `tokenAddress`     | `string` | ERC-20 token contract.           |
| `depositAmount`    | `string` | Amount in smallest units.        |
| `approvalCalldata` | `string` | Encoded `approve()` calldata.    |
| `approvalAmount`   | `string` | Amount to approve.               |

## How It Routes

The deposit hook routes based on what's available:

1. **Action delegates configured** (Tier 2) - Calls `onDepositRequired` from the provider
2. **Wagmi context detected** (Tier 3) - Uses connected wallet directly
3. **Neither** - `deposit()` fetches info only; no on-chain execution

## Fetch-Only Mode

Use `fetchInfo` to get the deposit calldata without executing. Useful for showing a preview or building custom deposit UI:

```tsx theme={null}
const { fetchInfo, depositInfo } = useDeposit(settlementId, 0);

useEffect(() => {
  fetchInfo(); // Fetch on mount
}, []);

if (depositInfo) {
  return (
    <div>
      <p>Escrow: {depositInfo.escrowAddress}</p>
      <p>Amount: {depositInfo.depositAmount}</p>
      <p>Chain: {depositInfo.chainId}</p>
      <button onClick={() => yourCustomDepositLogic(depositInfo)}>
        Custom Deposit
      </button>
    </div>
  );
}
```