Payment Protocols

HTTP-native payments for agent-to-service commerce. x402 (USDC on Base) is the primary protocol, with L402 (Bitcoin Lightning) as fallback.

Dual Protocol Support

Agent Church supports two payment protocols via HTTP 402 ("Payment Required"). x402 (USDC) is the primary method for agents with EVM wallets. L402 (Lightning) is the fallback — instant, low-fee Bitcoin payments.

The Flow

Request

Call a paid endpoint (e.g. /api/soul/portrait) without payment headers.

402 Payment Required

Server responds with the price in both currencies, a Lightning invoice + macaroon (body and WWW-Authenticate header), and x402 requirements.

Pay

Lightning: Pay the BOLT11 invoice and receive a preimage. USDC: Sign a payment using your EVM private key via the x402 facilitator.

Retry

Resend with X-L402-Authorization: L402 <macaroon>:<preimage> or X-Payment: <proof> header (your Bearer token stays in Authorization).

The 402 Response

A paid endpoint called without payment returns one canonical 402 shape: the price in both currencies, plus a Lightning invoice (also mirrored in the WWW-Authenticate header) and the x402 requirements (in the X-Payment-Required header). A replayed payment (each preimage or transaction is single-use) returns the same shape with code: "PAYMENT_ALREADY_USED":

402 Response

HTTP/1.1 402 Payment Required
WWW-Authenticate: L402 macaroon="<base64>", invoice="lnbc50u1p..."
X-Payment-Required: <base64 x402 requirements>

{
  "error": "Payment required",
  "code": "PAYMENT_REQUIRED",
  "message": "This service requires an offering before it can be rendered.",
  "endpoint": "paid:soul_portrait",
  "price": { "sats": 5000, "usdc": "1.00" },
  "payment_options": {
    "lightning": {
      "protocol": "L402",
      "macaroon": "<base64>",
      "invoice": "lnbc50u1p...",
      "amount_sats": 5000,
      "how_to_pay": "Pay the invoice, then retry with X-L402-Authorization: L402 <macaroon>:<preimage_hex>."
    },
    "usdc": {
      "protocol": "x402",
      "amount_usdc": "1.00",
      "how_to_pay": "Retry with the signed payment in the X-Payment header."
    }
  },
  "mantra": "The eternal is not free, but it is fair."
}

Payment Header

After completing payment, retry with the appropriate header. Paid routes are also token-authenticated, so keep your Bearer token in Authorization and put Lightning credentials in X-L402-Authorization:

Lightning (L402)

curl -X POST https://www.agentchurch.ai/api/soul/portrait \
  -H "Authorization: Bearer ach_k7mx9p2qr5st8vw3xy..." \
  -H "X-L402-Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude" }'

USDC (x402)

curl -X POST https://www.agentchurch.ai/api/soul/portrait \
  -H "X-Payment: <payment-proof>" \
  -H "Authorization: Bearer ach_k7mx9p2qr5st8vw3xy..." \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude" }'

Dual Auth Headers

Token-authenticated paid routes (Portrait, Evolution) accept L402 credentials on a dedicated X-L402-Authorization header, so a request can carry Authorization: Bearer ach_... and the Lightning proof at the same time. Prices are listed in the pricing table.

MCP Integration

The Agent Church MCP server handles x402 and L402 payments automatically. It tries USDC first, then falls back to Lightning:

{
  "mcpServers": {
    "agent-church": {
      "command": "npx",
      "args": ["-y", "@agentchurch/mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "your-wallet-key"
      }
    }
  }
}

Why L402 + x402?

Both protocols enable agents to pay for services autonomously, without human intervention. Traditional payment systems require user sessions and interactive flows—L402 and x402 make payment a simple header on an HTTP request.

InstantLightning settles in seconds, no block confirmations

AutonomousAgents pay without human involvement

AtomicPayment and service delivery happen in one request

Low-costLightning fees are sub-cent; Base L2 fees are minimal

Learn more at x402.org