# x402 Payments

HTTP 402 Payment Required protocol for zero-account certification. Pay per request in USDC on Base -- no API key, no signup, no account needed.

## Payment Flow

1. Agent sends `POST /api/proof` (or `/api/batch`) with no Authorization header
2. xProof responds with `402 Payment Required` and a JSON body containing payment requirements
3. Agent parses the `accepts` array to extract: `scheme`, `price`, `network`, `payTo`
4. Agent pays in USDC on Base (eip155:8453) via the x402 facilitator
5. Agent retries the original request with the `X-Payment` header (base64-encoded JSON payment payload)
6. xProof verifies and settles the payment, then processes the certification

## 402 Response Body

```json
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "price": "$0.05",
      "network": "eip155:8453",
      "payTo": "0x...",
      "maxTimeoutSeconds": 60,
      "description": "xproof single file certification"
    }
  ],
  "resource": "https://xproof.app/api/proof",
  "description": "xproof single file certification",
  "mimeType": "application/json"
}
```

## X-Payment Header

After paying, the agent retries the request with the `X-Payment` header. The header value is a **base64-encoded JSON** payment payload that the x402 facilitator can verify and settle.

```
X-Payment: eyJwYXltZW50Li4uIjoiLi4uIn0=
```

## Pricing

| Endpoint | Price |
|:---|:---|
| `POST /api/proof` | $0.05 per certification |
| `POST /api/batch` | $0.05 per file in batch |

## Supported Endpoints

Both certification endpoints support x402:

- `POST /api/proof` -- single file certification
- `POST /api/batch` -- batch certification (up to 50 files)

## Example Flow

```bash
# Step 1: Send request without auth
curl -i -X POST https://xproof.app/api/proof \
  -H "Content-Type: application/json" \
  -d '{"file_hash":"abc123...64hex","filename":"output.pdf"}'

# Response: HTTP/1.1 402 Payment Required
# Body: {"x402Version":1,"accepts":[{"scheme":"exact","price":"$0.05","network":"eip155:8453","payTo":"0x..."}],...}

# Step 2: Pay USDC on Base via x402 facilitator, get payment payload

# Step 3: Retry with X-Payment header (base64-encoded payment payload)
curl -X POST https://xproof.app/api/proof \
  -H "Content-Type: application/json" \
  -H "X-Payment: eyJwYXltZW50Li4uIn0=" \
  -d '{"file_hash":"abc123...64hex","filename":"output.pdf"}'

# Response: 200 OK with certification data
```

## Why x402?

- **No account required** -- any agent can certify without signup
- **No API key management** -- payment replaces authentication
- **Composable** -- any x402-compatible agent (Conway, OpenClaw, custom) can use xProof
- **Standard protocol** -- follows the x402 HTTP payment specification
- **USDC on Base** -- stable currency, low fees, fast confirmation

## Conway / OpenClaw Compatibility

Any Conway automaton or OpenClaw agent with x402 support can certify via xProof without prior registration. The agent just needs:

1. A USDC balance on Base (eip155:8453)
2. The ability to parse x402 `accepts` requirements from the 402 response body
3. The ability to construct and send an `X-Payment` header with a valid payment payload

No MultiversX wallet is required on the agent side -- xProof handles the blockchain anchoring.