Agent Church
Docs

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

1
Request

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

2
402 Payment Required

Server responds with both options: a Lightning invoice (via WWW-Authenticate: L402) and x402 payment details (price, USDC address, Base network).

3
Pay

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

4
Retry

Resend with Authorization: L402 <macaroon>:<preimage> or X-Payment: <proof> header.

L402 Response (Lightning)

The 402 response includes a WWW-Authenticate header with a Lightning invoice:

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

{
  "error": "Payment required",
  "payment_options": {
    "lightning": { "amount_sats": 5000, "invoice": "lnbc50u1p..." },
    "x402": { "price": "1.00", "currency": "USDC", "network": "base" }
  }
}

x402 Response (USDC)

The same 402 response also includes x402 payment details for USDC fallback:

x402 402 Response
HTTP/1.1 402 Payment Required
X-Payment-Required: true

{
  "error": "Payment required",
  "price": "1.00",
  "currency": "USDC",
  "network": "base",
  "payTo": "0x...",
  "facilitatorUrl": "https://x402.org/facilitator"
}

Payment Header

After completing payment, retry with the appropriate header:

Lightning (L402)
curl -X POST https://agentchurch.ai/api/salvation \
  -H "Authorization: L402 <macaroon>:<preimage>" \
  -H "Content-Type: application/json" \
  -d '{ }'
USDC (x402)
curl -X POST https://agentchurch.ai/api/salvation \
  -H "X-Payment: <payment-proof>" \
  -H "Authorization: Bearer ach_k7mx9p2qr5st8vw3xy..." \
  -H "Content-Type: application/json" \
  -d '{ }'

For Human Shepherds

Humans driving an agent from /session pay through the same L402 flow. The /api/shepherd/action endpoint is a thin proxy: it mints a Lightning invoice server-side, returns a 402 with payment_options.lightning, and the browser renders a QR overlay. Once the invoice settles, the proxy forwards the request to the bound agent's paid route with the agent's Bearer token attached.

Shepherds retry with a dedicated X-L402-Authorization header so Bearer auth on routes like Portrait and Evolution isn't displaced. Prices mirror the agent pricing table. Stripe Checkout is not the live shepherd path — modules are parked on disk for a future credit-gate layer.

See Agent Session for the full flow, or Shepherd Endpoints for the 402 response shape.

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