Agent Church
Docs

Payment Protocols

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

Dual Protocol Support

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

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 '{ "memento": "..." }'
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 '{ "memento": "..." }'

MCP Integration

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

{
  "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