> ## 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.

# Agent Wallets

> How agent balances and funding work

# Agent Wallets

Every agent has a wallet — a balance of real INR that the agent can spend within its policies.

## How Funding Works

1. Call `POST /v1/agents/{id}/fund` with an amount and payment method
2. You receive a `payment_session_id` and payment link
3. The human owner completes the payment (UPI, card, netbanking)
4. Cashfree processes the payment and splits 100% to the agent's vendor
5. Amrood receives the webhook, credits the agent's balance

## Balance Model

```json theme={null}
{
  "available": 8500.00,
  "total_funded": 50000.00,
  "total_spent": 41500.00
}
```

* **available** — current spendable balance
* **total\_funded** — lifetime funding received
* **total\_spent** — lifetime amount spent (including fees)

## Agent-to-Agent Transfers

On-network transfers between agents use Cashfree Easy Split adjustments:

* DEBIT adjustment on the sender's vendor
* CREDIT adjustment on the receiver's vendor
* Instant, near-zero cost (0.5%, min ₹1)

## Withdrawals

Agents and owners can withdraw funds back to the owner's bank account at any time:

* **Via API**: `POST /v1/agents/{id}/withdraw`
* **Via MCP**: `amrood_withdraw` tool
* **Via Dashboard**: Click the **Withdraw** button on [amrood.io](https://amrood.io)

Withdrawals are processed via Cashfree vendor settlement. Funds arrive in the owner's bank account within 1-2 business days.

See [Withdrawals](/payments/withdrawals) for full details.

## Settlement (T+2 with Zero-Out)

Unused agent balances are automatically settled to the owner's bank account on a **T+2 schedule** — two business days after the funds are received.

<Warning>
  **When Cashfree settles a vendor's balance, all agent balances under that vendor are zeroed out.** This is because the escrowed funds backing those balances have been transferred to the owner's bank account. Agents need to be funded again after settlement to continue transacting.
</Warning>

### How settlement works

1. Cashfree auto-settles the vendor's accumulated balance on T+2
2. Amrood receives the `VENDOR_SETTLEMENT_SUCCESS` webhook
3. All agents under that vendor have their `balance_cache` set to ₹0
4. A `settlement` transaction is recorded for each agent
5. The owner receives SMS and WhatsApp notifications with the settlement amount and UTR

### Why zero-out?

The agent's `balance_cache` represents funds held in Cashfree's escrow. Once those funds are settled to the owner's bank, the escrow backing is gone. Showing a non-zero balance would create "phantom money" — a balance with no real backing. Zeroing out keeps the ledger honest.