agentpay

# agentpay

[![CI](https://github.com/Hellotravisss/agentpay/actions/workflows/ci.yml/badge.svg)](https://github.com/Hellotravisss/agentpay/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)
![tests](https://img.shields.io/badge/tests-110%20passing-brightgreen.svg)

A **cross-rail spend-policy gateway for AI agent payments**. It sits between your agents and anything that charges them money — x402-style paid APIs, Alipay/WeChat-style agent payments, whatever comes next — and answers the question every company deploying paying agents will have to answer:

> *"How do I let my agent spend money — across several payment rails — without giving it my wallets?"*

Agents never hold payment credentials. They call paid resources **through** the gateway, which:

1. intercepts the `402 Payment Required` handshake and collects **every payment option the merchant accepts**,
2. **routes to one rail** (agent's rail preference first, ties broken by cheapest cost in the policy's base currency),
3. checks the payment against that agent's spend policy — budgets and caps are denominated in **one base currency** and enforced across all rails and currencies via exact FX conversion,
4. executes approved payments on the chosen rail,
5. retries the request with the payment proof and returns the unlocked response,
6. writes **every decision — denials included — to an append-only audit log**.

```
                       ┌────────────────────────────────────────────────┐      ─▶ paid API (x402, USDC)
  agent ──HTTP──▶      │  gateway                                       │
  (no keys, no wallet) │  policy ─ fx ─ router ─ ledger ─ audit ─ rails │      ─▶ paid API (Alipay, CNY)
                       └────────────────────────────────────────────────┘      ─▶ ...
```

<p align="center"><img src="docs/dashboard.svg" alt="agentpay admin dashboard — live spend vs. budgets, per-rail breakdown, and approve/reject for held payments" width="860"></p>

<p align="center"><sub>The built-in dashboard (<code>GET /admin</code>) — live spend vs. budgets, per-rail breakdown, and one-click approve/reject on held payments.</sub></p>

For how it's built and *why* — design principles, the full 402 request lifecycle, and where the simple parts grow — see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## Where it fits — the neutral layer

The platforms are racing to let agents spend, and each is building a **closed loop**: Alipay's [ACT](https://www.qbitai.com/2026/01/369878.html) delegated-payment protocol, WeChat Pay's [isolated "AI card"](https://www.caixinglobal.com/2026-06-17/tencent-lets-ai-agent-make-purchases-through-wechat-pay-102455141.html) with user-set authorization scope and spend limits, x402 for crypto-native APIs. Every platform wants agents spending inside *its* wallet, on *its* rail — and the design they keep converging on (a wallet isolated from your real account, scoped authorization, per-spend limits, big payments held for confirmation, a full audit trail) is exactly the control surface this project is built around. The thesis is no longer speculative; it's where the giants are pointing their capex.

But a company running real agents doesn't get to live in one loop. Its agents pay an x402 API in USDC, a vendor in CNY, the next thing in whatever ships next quarter — and **no single platform gives it one neutral view across all of them**: one base-currency budget, one audit trail, one policy, one place where the agent never holds a credential. The more these closed loops fragment, the more that spanning layer is missing.

That layer is agentpay. It sits *above* the rails — x402, Alipay, WeChat, mock — behind a two-method interface ([`rails/rail.ts`](src/rails/rail.ts)), so budget, policy, FX, routing, and audit are written **once** and every rail plugs in underneath. It's rail-neutral and self-hosted by design: the value is precisely the part no platform racing to own its own loop will build for you.

## Quick start

```bash
npx agentpay-gateway      # gateway on http://127.0.0.1:4020, dashboard at /admin (mock rails)
```

From source:

```bash
npm install
npm test        # 110 tests: money, FX, policy, x402 v1+v2, MCP, persistence, approvals, security, e2e
npm run demo    # walkthrough: 2 rails, 2 currencies, 1 unified USD budget, human-in-the-loop
npm run dev     # start the gateway on :4020 (dashboard at http://localhost:4020/admin)
```

The demo runs a merchant that accepts USDC (x402-style) **or** CNY (Alipay-style); two agents with different rail preferences get routed differently, and one USD budget governs both — a 0.36 CNY purchase consumes ~0.0504 USD of it. Per-transaction caps, payee blocklists, budget exhaustion, the per-rail spend breakdown, and the audit trail are all shown.

## Install as an agent skill

There's a ready-to-install **agent skill** in [`skill/`](skill/) — a step-by-step runbook an AI assistant (Claude Code, OpenClaw, …) follows to set agentpay up *for* you: install + self-test, write a deny-by-default policy, launch the gateway, **reroute the agent's paid calls through `/proxy`**, then operate it (spend, audit, approvals, live policy edits) and harden for production. It bundles [policy templates](skill/policies.md) and a [troubleshooting + API reference](skill/troubleshooting.md). Point your assistant at [`skill/SKILL.md`](skill/SKILL.md), or install it from a skill marketplace.

## Use from Claude / Cursor (MCP)

Give an MCP agent a budget it **cannot** exceed. The `agentpay-mcp` server holds only
the agent's gateway API key — the wallet and the limits stay in the gateway. Unlike
honor-system budget tools, the agent is never *asked* to check its budget; a payment
over the limit simply isn't signed.

```json
{
  "mcpServers": {
    "agentpay": {
      "command": "npx",
      "args": ["-y", "-p", "agentpay-gateway", "agentpay-mcp"],
      "env": { "AGENTPAY_URL": "http://127.0.0.1:4020", "AGENTPAY_API_KEY": "<key from POST /admin/keys>" }
    }
  }
}
```

Tools: `paid_fetch(url, method?, body?)` — fetch any URL; the gateway pays x402/402
within policy. Denials and approval holds come back as tool errors the model can
explain. `check_budget()` — spent today/this month vs limits (via the agent-scoped
`GET /v1/budget`, which shows an agent only its own numbers).

## Policies

Policies are deny-by-default: an agent with no policy entry cannot spend at all. See `policies/example.json`:

```jsonc
{
  "fxRates": { "USDC:USD": "1", "CNY:USD": "0.14" },  // directional pairs, exact decimals
  "defaults": { "currency": "USD", "perTransactionMax": "1.00", "dailyBudget": "10.00" },
  "agents": [
    {
      "agentId": "research-bot",
      "enabled": true,
      "currency": "USD",                        // base currency for ALL limits below
      "railPreference": ["alipay-act", "x402"], // routing order when merchants accept several rails
      "perTransactionMax": "0.25",              // cap on any single payment, in base currency
      "dailyBudget": "0.15",                    // UTC calendar day, across all rails/currencies
      "monthlyBudget": "3.00",                  // UTC calendar month
      "maxTransactionsPerDay": 200,
      "requireApprovalOver": "0.50",            // hold payments >= this for human review (base ccy)
      "payeeBlocklist": ["merchant-shady"]
      // or "payeeAllowlist": [...] to whitelist instead
    }
  ]
}
```

All money is exact decimal (bigint micro-units, 6 dp — USDC precision); FX conversions round **up** so budgets are enforced conservatively. No floats anywhere near amounts. Payments in a currency with no configured rate to the base currency are denied (`no_fx_rate`).

## API

| Endpoint | Purpose |
|---|---|
| `ANY /proxy?url=<target>` | Proxy a request; routes + pays on 402 if policy allows. Identify the agent via `Authorization: Bearer <api key>` (when keys are configured) or `X-Agent-Id`. |
| `GET /admin` | Web dashboard (single self-contained page) — live spend, pending approvals with approve/reject buttons, the audit trail, and inline policy editing. |
| `GET /admin/policy` | The full live policy config. |
| `GET /admin/agents` | Configured agents with their resolved limits. |
| `PUT /admin/agents/:id` | Create or replace an agent's policy (validated). Takes effect on the next request; written back to the policy file. |
| `DELETE /admin/agents/:id` | Remove an agent (reverts to deny-by-default). |
| `GET /admin/keys` · `POST /admin/keys` · `DELETE /admin/keys/:id` | Multi-tenant API keys: list, mint (secret returned once), revoke. |
| `GET /admin/spend/:agentId` | Unified spend vs. limits in the base currency, plus a per-rail breakdown in native currencies. |
| `GET /admin/audit?agent=&limit=` | Audit trail of every allow/deny/failure/hold. |
| `GET /admin/approvals?status=` | List payments held for human review (filter `pending`/`approved`/`rejected`). |
| `POST /admin/approvals/:id` | Decide a held payment: body `{ "decision": "approve" \| "reject" }`. |
| `GET /healthz` | Liveness. |

Successful paid responses carry `X-Gateway-Payment-Id`, `X-Gateway-Rail`, and `X-Gateway-Payment-Amount` headers. Denials return `403` with the violated rule id (`per_transaction_max`, `daily_budget`, `payee_blocklisted`, `no_fx_rate`, `approval_rejected`, ...) so the agent can explain itself or back off.

### Human-in-the-loop approvals

Set `requireApprovalOver` on an agent and any policy-approved payment at or above that base-currency amount is **held** instead of executed: the proxy returns `202` with an `approvalId` rather than paying. An operator approves or rejects via `POST /admin/approvals/:id`; the agent's retry then executes (approved) or is denied with `approval_rejected`. Each approval is single-use, so it unlocks exactly one payment. Budgets are still re-checked at execution time on the retry.

### Persistence

By default the ledger, audit log, and approvals live