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

# Withdrawals

> Withdraw agent balances to the owner's bank account

# Withdrawals

Agents or their owners can withdraw funds from an agent's wallet back to the owner's verified bank account at any time. Withdrawals are processed via Cashfree vendor settlement.

## Three Ways to Withdraw

### 1. Via API

```bash theme={null}
curl -X POST https://api.amrood.io/v1/agents/agt_xxx/withdraw \
  -H "x-agent-key: agk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'
```

This withdraws the agent's full available balance. The response:

```json theme={null}
{
  "withdrawn": 4500.00,
  "status": "completed",
  "message": "₹4,500.00 withdrawal initiated to your bank account"
}
```

### 2. Via MCP

```text theme={null}
> Withdraw my agent's balance

Claude: Withdrawal of ₹4,500.00 initiated.
        Funds will arrive in your bank account within 1-2 business days.
```

### 3. Via Web Dashboard

1. Log in to [amrood.io](https://amrood.io) with your phone number (OTP)
2. Find the agent card on your profile page
3. Click the **Withdraw** button (visible when balance > ₹0)
4. Confirm the withdrawal amount

The dashboard calls the same API under the hood, authenticated via your owner session.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Owner as Owner / Agent
    participant Amrood as Amrood API
    participant CF as Cashfree
    participant Bank as Owner's Bank

    Owner->>Amrood: POST /v1/agents/{id}/withdraw
    Amrood->>CF: Trigger on-demand settlement
    CF->>Bank: Transfer funds
    CF-->>Amrood: Settlement webhook
    Amrood->>Amrood: Zero out agent balance
    Amrood-->>Owner: SMS + WhatsApp notification
```

### Step by step

1. The withdrawal request triggers a Cashfree on-demand vendor settlement
2. Cashfree transfers the vendor's unsettled balance to the owner's bank account
3. When the settlement completes, Amrood receives a webhook
4. The agent's `balance_cache` is set to ₹0
5. A `withdrawal` transaction is recorded in the ledger
6. The owner receives SMS and WhatsApp notifications with the amount and UTR reference

## Timing

| Method                | Typical Duration              |
| --------------------- | ----------------------------- |
| On-demand settlement  | 1-2 business days             |
| Auto-settlement (T+2) | 2 business days after funding |

## Fees

There are no Amrood fees on withdrawals. Standard Cashfree settlement fees may apply.

## Automatic Settlement vs. Manual Withdrawal

|                  | Auto-Settlement                        | Manual Withdrawal                |
| ---------------- | -------------------------------------- | -------------------------------- |
| **Trigger**      | Automatic on T+2 schedule              | Owner/agent initiates            |
| **Timing**       | 2 business days after funding          | 1-2 business days after request  |
| **What happens** | All agent balances under vendor zeroed | Requested agent's balance zeroed |
| **Use case**     | Default behavior, no action needed     | When you need funds sooner       |

<Warning>
  After either auto-settlement or manual withdrawal, the agent's balance is zeroed out. Fund the agent again if it needs to continue transacting.
</Warning>

## Notifications

On successful withdrawal, the owner receives:

* **SMS** with withdrawal amount and UTR
* **WhatsApp** message with formatted details
* **Webhook**: `agent.withdrawal.completed` event to your platform

## Error Cases

| Scenario                               | Response                         |
| -------------------------------------- | -------------------------------- |
| Agent balance is ₹0                    | `400: No funds to withdraw`      |
| Agent not found or not owned by caller | `404: Agent not found`           |
| Cashfree settlement fails              | Falls back to ledger-only update |