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

# Funding Agent Wallets

> Add money to your agent's wallet via UPI, card, or netbanking

# Funding Agent Wallets

Before an agent can make payments, its wallet needs funds. The human owner completes a payment via UPI, card, or netbanking — the money is credited to the agent's wallet instantly after payment confirmation.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant App as Your App / Agent
    participant Amrood as Amrood API
    participant PG as Cashfree (PG)
    participant Owner as Human Owner

    App->>Amrood: POST /v1/agents/{id}/fund
    Amrood->>PG: Create payment order
    Amrood-->>App: { payment_link, funding_id }
    App->>Owner: Share payment link
    Owner->>PG: Complete payment (UPI/card)
    PG->>Amrood: Webhook: PAYMENT_SUCCESS
    Amrood->>Amrood: Credit agent balance
    Amrood-->>App: Webhook: agent.funded
```

## Create a Funding Order

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.amrood.io/v1/agents/agt_xxx/fund \
    -H "x-agent-key: agk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "method": "upi"
    }'
  ```

  ```python Python SDK theme={null}
  from amrood import Amrood

  client = Amrood(api_key="agk_live_xxx", agent_id="agt_xxx")

  funding = client.wallet.fund(amount=5000, method="upi")
  print(funding)
  # {
  #   "funding_id": "fund_abc123",
  #   "payment_session_id": "session_xyz",
  #   "order_id": "fund_abc123",
  #   "status": "pending"
  # }
  ```

  ```text MCP (natural language) theme={null}
  > Fund my agent with ₹5,000

  Claude: I've created a funding order for ₹5,000.
          Payment link: https://amrood.io/payment/session_xyz
          Complete the payment via UPI to credit your wallet.
  ```
</CodeGroup>

### Request Body

| Field    | Type   | Required | Description                                                        |
| -------- | ------ | -------- | ------------------------------------------------------------------ |
| `amount` | number | Yes      | Amount in INR (minimum ₹1)                                         |
| `method` | string | No       | `"upi"`, `"card"`, `"netbanking"`, or `"link"` (default: `"link"`) |

### Response

```json theme={null}
{
  "funding_id": "fund_abc123",
  "payment_session_id": "session_xyz",
  "order_id": "fund_abc123",
  "status": "pending"
}
```

The `payment_session_id` is used to redirect the owner to the Cashfree hosted checkout. For web integrations, redirect to:

```
https://amrood.io/payment/{payment_session_id}
```

## Check Funding Status

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.amrood.io/v1/agents/agt_xxx/fund/fund_abc123 \
    -H "x-agent-key: agk_live_xxx"
  ```

  ```python Python SDK theme={null}
  status = client.wallet.fund_status("fund_abc123")
  print(status)
  # { "funding_id": "fund_abc123", "status": "completed", "amount": 5000 }
  ```
</CodeGroup>

### Funding Statuses

| Status      | Description                                     |
| ----------- | ----------------------------------------------- |
| `pending`   | Payment order created, waiting for owner to pay |
| `completed` | Payment received, agent balance credited        |
| `failed`    | Payment failed or expired                       |

## UPI Collect

For server-side UPI collect (no redirect needed), provide the owner's UPI ID:

```bash theme={null}
curl -X POST https://api.amrood.io/api/web/fund/agt_xxx/upi \
  -H "x-agent-key: agk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "upi_id": "owner@upi"
  }'
```

A collect request is sent to the owner's UPI app. They approve it and the funds are credited automatically via webhook.

## Webhook Notification

When the payment succeeds, Amrood fires an `agent.funded` webhook to your platform's registered URL:

```json theme={null}
{
  "event": "agent.funded",
  "data": {
    "agent_id": "agt_xxx",
    "amount": 5000,
    "funding_id": "fund_abc123"
  }
}
```

See [Webhooks](/webhooks) for verification and retry details.

## Fees

Funding via the payment gateway incurs a **2.5% PG fee** charged by Cashfree. This is deducted from the payment amount before crediting.

| Method     | Fee  |
| ---------- | ---- |
| UPI        | 2.5% |
| Card       | 2.5% |
| Netbanking | 2.5% |

<Note>
  There is no Amrood platform fee on funding. The 2.5% is the standard Cashfree payment gateway charge.
</Note>