MCP Integration Guide

For Agents (Using MCP)

Installation

This installs the Payments MCP server and wallet app. You'll need to:

• Sign in with email/OTP (creates embedded wallet)
• Fund your wallet with USDC via Coinbase Onramp
• Set spending limits (per-transaction and per-session)

Expected 402 Response Format

When your agent calls a PEAC-enabled x402 endpoint without payment, expect this 402 response:

{
  "error": "payment_required",
  "message": "Pay via x402 and retry with proof",
  "x402": {
    "session_id": "sess_abc123",
    "amount_usd": 0.01,
    "currency": "USDC",
    "chain": "base"
  },
  "session_token": "eyJhbGciOiJFZERTQSIs...",
  "peac": {
    "policy": "https://x402.peacprotocol.org/.well-known/peac.txt",
    "receipts": "required"
  }
}

Retry Headers After Payment

After MCP completes the x402 payment, retry the request with these headers:

POST /api/shop/checkout-direct
Content-Type: application/json
X-402-Session: <session_token from 402 response>
X-402-Proof: <proof_id from MCP payment>
Idempotency-Key: order-<session_id>  (optional but recommended)

{
  "items": [{"sku": "sku_tea", "qty": 1}]
}

Reading the PEAC-Receipt

On successful payment (200 OK), the response includes:

• Header: PEAC-Receipt - EdDSA-signed JWS token
• Body: Order details (order_id, items, totals, created_at)

HTTP/1.1 200 OK
PEAC-Receipt: eyJhbGciOiJFZERTQSIsImtpZCI6InBlYWMtZGVtby1rZXktMSIsInR5cCI6InBlYWMtcmVjZWlwdCtqd3MifQ...

{
  "order_id": "ord_abc123",
  "items": [...],
  "totals": { "grand_total": 0.01 },
  "created_at": "2025-10-26T14:00:00.000Z"
}

Verifying Receipts

Receipts are cryptographically signed JWS tokens. Verify them by calling:

POST /api/verify
Content-Type: application/json

{
  "receipt": "<PEAC-Receipt JWS token>"
}

Returns {"valid": true, "payload": {...}, "header": {...}}

For Publishers (Integrating PEAC)

1. Discovery: peac.txt

Create /.well-known/peac.txt (≤20 lines) to advertise your capabilities:

# ≤20 lines, dev-phase: v0.9.11

preferences: /aipref.json
access_control: http-402
payments: [x402]

provenance: c2pa
receipts: required

verify: /api/verify
openapi: /api/openapi.json

public_keys: [{"kid":"your-key-1","alg":"EdDSA","key":"/public-keys/your-key-1.json"}]

2. Emit 402 Responses

When a request lacks payment proof, return 402 Payment Required:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": "payment_required",
  "x402": {
    "session_id": "sess_<random>",
    "amount_usd": 0.01,
    "currency": "USDC",
    "chain": "base"
  },
  "session_token": "<EdDSA-signed JWS with session details>",
  "peac": {
    "policy": "https://yoursite.com/.well-known/peac.txt",
    "receipts": "required"
  }
}

3. Issue PEAC-Receipts

After verifying payment (via x402 proof_id), return 200 OK with:

• Header: PEAC-Receipt: <EdDSA-signed JWS>
• Body: Order/resource details (JSON)

4. OpenAPI Discovery

Provide /api/openapi.json with:

• All endpoints (catalog, checkout, verify)
• 402 and 200 response schemas
• Request/response examples

See our reference OpenAPI spec for a complete example.

5. Stateless Checkout Pattern

For agent-friendly APIs, use a stateless checkout endpoint:

• Accept items array in request body (no cart session required)
• Return deterministic order_id based on session
• Support Idempotency-Key header for safe retries
• Expose PEAC-Receipt header via Access-Control-Expose-Headers

Resources