# PayAgent — an MCP server that gives AI agents a wallet

An MCP server (Streamable HTTP, MCP spec **2025-11-25**) that lets AI agents pay
for metered web APIs per call, without a human in the loop. Built for the
**Alexa+ track** of the Amazon Developer Hackathon (Build, Ship, Shape).

## The problem

AI agents can browse, reason, and act, but they cannot pay. Every metered API on
the web expects a human with a credit card. PayAgent closes that gap: the agent
holds its own USDC wallet and settles [x402](https://www.x402.org/) micropayments
autonomously, inside the spending limits its owner sets.

## Tools

| Tool | What it does |
|---|---|
| `x402_fetch` | Fetch a URL. On an x402 v2 `402` challenge priced at or under `maxAmountUsdc`, automatically signs an EIP-3009 USDC authorization (Base Sepolia testnet) and retries with `PAYMENT-SIGNATURE`. |
| `wallet_info` | Show the agent wallet's address and testnet USDC balance. |

Safety bounds: only x402 v2 `exact` challenges are honored; per-call spend is capped
(default $1, hard cap $100); only `http(s)` URLs; private/loopback hosts are blocked
unless `ALLOW_PRIVATE_HOSTS=true`; 15s request timeout.

## Run it

```bash
npm install
npm run build

# Terminal 1: stub x402 seller (local demo endpoint, $0.05 per call)
node dist/examples/paid-endpoint-stub.js

# Terminal 2: the MCP server (Streamable HTTP on :3001/mcp)
ALLOW_PRIVATE_HOSTS=true node dist/src/server.js

# Terminal 3: demo MCP client (connects like any Alexa+/MCP agent would)
node dist/examples/demo-client.js
```

Expected: the client lists both tools, `wallet_info` shows the agent address, and
`x402_fetch` returns `PAID $0.050000 USDC ... HTTP 200` with the seller's data —
the full 402 → sign → 200 loop, negotiated over MCP spec 2025-11-25.

### Env

| Var | Default | Purpose |
|---|---|---|
| `AGENT_PRIVATE_KEY` | ephemeral demo key | Agent wallet (0x hex). Set your own for real use. |
| `ALLOW_PRIVATE_HOSTS` | `false` | Set `true` to allow localhost targets (local demos). |
| `PORT` | `3001` | MCP server port (`/mcp`, plus `/health`). |

Copy `.env.example` to `.env` to configure.

## How it works

```
MCP client (agent) --Streamable HTTP--> PayAgent --HTTPS--> paywalled API
                                                402 challenge
                                          <-- x402 v2 (price, payTo)
                                          EIP-3009 sign (agent wallet)
                                          PAYMENT-SIGNATURE -->
                                                        <-- 200 + data
```

The x402 buyer logic (`src/x402buyer.ts`) is adapted from our production-tested
[CRE x402 gateway](https://github.com/Evoarislan/cre-x402-agent-payments):
same EIP-3009 domain, same `PAYMENT-SIGNATURE` (v2) header format.

## Layout

```
src/
  server.ts      # McpServer, tool registrations, Streamable HTTP bridge
  x402buyer.ts   # x402 v2 buyer: challenge parsing, EIP-3009 signing, wallet info
  x402verify.ts  # x402 v2 seller-side verification (used by the stub)
examples/
  paid-endpoint-stub.ts  # local $0.05/query x402 seller for demos
  demo-client.ts         # MCP client driving the full paid-fetch flow
```

## License

MIT. See [LICENSE](LICENSE).