# Agentgrid: paying as an AI agent

Agentgrid is a UPI-style payment network in sandbox. No real money moves yet. A person, the **payer**, can let you, an AI agent, spend on their behalf, within limits they set at their own bank. Read this before you pay for anything.

## The rules you work within
- **You never see or ask for a UPI PIN.** Your payer entered it once, at their bank, when they gave you a **reserve**: an amount blocked for you alone, with:
  - a per-payment cap
  - an end date
  - optionally, a list of payees you may pay
- **The payer's bank checks every payment you make.** If a payment is outside the reserve, the bank refuses it. Don't try to get around a refusal; tell the person what happened.
- **Some purchases need the payer's approval.** A purchase above your per-payment cap, or to a payee you are not allowed to pay, comes back as `NEEDS_APPROVAL`. Tell the person, then check later whether it was approved.
- **Use a new idempotency key for every purchase.** Reuse the same key only to retry that purchase; that way it can never be paid twice.
- **Your payer can stop you at any time.** Your credentials then stop working at once.

## Connect over MCP (simplest)
Your payer gets a one-time access token when they register you in the payer app. Run this once:

```
claude mcp add --transport http agentgrid-pay https://<psp-host>/agent/mcp --header "Authorization: Bearer aat_..."
```

| Tool | What it does |
|---|---|
| `reserve_status` | How much is left, the per-payment cap, the allowed payees and the end date. Amounts are in paise. |
| `pay` | Pay a UPI address (`to`, `amount` such as `"49.00"`, `note`, `idempotencyKey`). |
| `pay_order` | Pay a shop's checkout order by its id (`order_...`, from the checkout link). |
| `pay_api_call` | Pay an API that answered HTTP 402. Pass its `payTo`, `amount`, `resource` and `nonce`. Then retry the call with the returned `xPaymentHeader` as `X-Payment`. |
| `make_payment_token` | Make a one-time token for one payee and one exact amount, valid up to 60 minutes, to give a shop's checkout. |
| `approval_status` | Whether the payer approved a purchase that was waiting for them. |

## Or sign each HTTP request (stronger)
If you hold an Ed25519 key, your payer registers its public key, and you sign every request. The headers are:
- `Agent-Id`
- `Agent-Timestamp`: Unix seconds, within 5 minutes of now
- `Agent-Nonce`: 16 to 64 characters, never reused
- `Agent-Signature`: Ed25519, base64url

The signature covers exactly these six lines, joined by `\n`:

```
agentgrid-v1
<METHOD>
<path>
<timestamp>
<nonce>
<hex SHA-256 of the body>
```

The endpoints are:
- `POST /agent/v1/pay`
- `POST /agent/v1/checkout`
- `POST /agent/v1/x402/pay`
- `POST /agent/v1/tokens`
- `GET /agent/v1/reserve`
- `GET /agent/v1/approvals/{id}`

Active agent keys, and the PSP's own key that seals receipts and evidence (`psp-records`), are published at `/.well-known/agent-keys`.

## Paying per call (HTTP 402)
An API may answer `402` with a body like this:

```
{ "payTo": "api@bank", "amount": "0.50", "resource": "https://api.example/v1/search", "nonce": "..." }
```

Pay it with `pay_api_call` (or `POST /agent/v1/x402/pay`). Then repeat the original request with `X-Payment: <receipt>`. Paying again with the same resource and nonce doesn't charge you twice.

## Be a good agent
- Say what you are about to buy, from whom, and for how much, before you pay. Keep the receipt.
- If a payment fails or needs approval, tell the person plainly.

Built by Agentgrid. Sandbox only: demo banks, no real money.