# Agent Pay

> Independent e-commerce site. Single-seller online store offering products for purchase. Both human shoppers and autonomous AI agents are welcome.

## Site type
- Independent online store (not a marketplace, not an aggregator)
- Products are listed by the site owner and sold directly
- Available for purchase: yes

## API for AI agents

Catalog (no auth):
- GET /api/products — list products. Returns `{id, uuid, name, priceUsdc, stock, createdAt, updatedAt}` per row.
- GET /api/products/:uuid — fetch a single product by public UUID
- POST /api/products — create a product (response includes uuid)
- PATCH /api/products/:uuid — update a product
- DELETE /api/products/:uuid — delete a product
- GET /api/db-ping — health check

Purchase (paid, x402 protocol):
- POST /api/products/:uuid/buy — buy one unit. Gated by HTTP 402.

The public product identifier is `uuid` (RFC 4122). The integer `id` is internal.
`priceUsdc` is a JSON number with up to 2 decimal places (e.g. `22.5` means 22.50 USDC).

## How to purchase (x402 + USDC on Base Sepolia)

The buy endpoint uses the [x402 payment protocol](https://x402.org).
Settlement runs through the Coinbase CDP facilitator. Buyers pay USDC;
the facilitator sponsors gas, so buyers do **not** need ETH.

Flow is exactly two HTTP requests:

1. POST /api/products/:uuid/buy with no `X-PAYMENT` header. The server
   replies HTTP 402 with a JSON body:
   ```
   {
     "x402Version": 1,
     "error": "X-PAYMENT header is required",
     "accepts": [{
       "scheme": "exact",
       "network": "base-sepolia",
       "maxAmountRequired": "<USDC atomic units, 6 decimals>",
       "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
       "payTo": "0x...",
       "maxTimeoutSeconds": 300,
       "extra": { "name": "USDC", "version": "2" },
       "resource": "<absolute URL>"
     }]
   }
   ```

2. Sign EIP-3009 `transferWithAuthorization` on the USDC contract with:
   - from = your wallet
   - to = accepts[0].payTo
   - value = accepts[0].maxAmountRequired
   - validAfter = 0
   - validBefore = now + accepts[0].maxTimeoutSeconds
   - nonce = random 32-byte hex
   Wrap `{x402Version:1, scheme:"exact", network:"base-sepolia",
   payload:{signature, authorization}}` and base64-encode it. Resend the
   same POST with header `X-PAYMENT: <base64>`.

On success the server responds 200 with:
```
{
  "ok": true,
  "orderUuid": "...",
  "productUuid": "...",
  "name": "...",
  "pricePaidUsdc": 22.5,
  "stock": 9,
  "txHash": "0x...",
  "buyer": "0x..."
}
```
plus header `X-PAYMENT-RESPONSE` (base64 JSON with `transaction`,
`network`, `payer`).

Errors:
- 400 — bad UUID
- 402 — missing/invalid X-PAYMENT, or settlement failed; body always
  includes `accepts` for retry
- 404 — product not found
- 409 — out of stock (only after payment was verified; settlement is
  not attempted, so no funds move)

Reference clients: `x402-fetch` and `x402-axios` (npm). Wrap your HTTP
client with a viem account and the 402-then-pay flow is automatic.

Test USDC on Base Sepolia: https://faucet.circle.com (select Base Sepolia).

Notes for agents:
- Always run step 1 to get the current price; do not cache
  `maxAmountRequired`.
- One purchase = one unit. Loop the request to buy multiples.
- `txHash` is the canonical receipt; persist it.

## Pages
- / — homepage with overview
- /products — human-facing catalog and admin