Skip to content

X402 Protocol

Lango integrates the official Coinbase X402 Go SDK for automatic HTTP 402 payment handling. When a server responds with 402 Payment Required, the SDK intercepts the response, creates a signed payment, and retries the request automatically.

Experimental

X402 support is under active development. Enable it with payment.x402.autoIntercept: true.

How It Works

When payment.x402.autoIntercept is enabled, the following flow occurs:

1. Agent makes HTTP request via payment_x402_fetch tool
       │
2. Server returns 402 with PAYMENT-REQUIRED header (Base64 JSON)
       │
3. SDK's PaymentRoundTripper intercepts 402
       │
4. SDK creates EIP-3009 transferWithAuthorization, signs with EIP-712
       │
5. SDK retries request with PAYMENT-SIGNATURE header
       │
6. Server verifies signature and returns content

The entire flow is transparent to the agent -- it simply receives the final response content after payment is processed.

Key Features

EIP-3009 Off-Chain Signatures

Payments use transferWithAuthorization (EIP-3009), which allows token transfers via off-chain signatures. The token holder signs a message authorizing the transfer without needing an on-chain approval transaction first.

CAIP-2 Network Identifiers

The X402 protocol uses CAIP-2 chain identifiers in the format eip155:<chainID>. This provides a standardized way to identify blockchain networks across different protocols.

Spending Limit Enforcement

Before creating a payment, the SDK invokes the BeforePaymentCreationHook to enforce spending limits. If the payment would exceed the configured maxPerTx or maxDaily limits, it is rejected before any signature is created.

Lazy Client Initialization

The X402 client is initialized lazily on first use, not at startup. This avoids unnecessary wallet setup if the agent never encounters a 402 response.

Audit Trail

Every X402 payment creates a PaymentTx record with payment_method="x402_v2", providing a full audit trail of automated payments.

Configuration

Settings: lango settings → Payment

{
  "payment": {
    "enabled": true,
    "x402": {
      "autoIntercept": true,
      "maxAutoPayAmount": 1.0
    }
  }
}
Key Type Default Description
payment.x402.autoIntercept bool false Enable automatic HTTP 402 interception
payment.x402.maxAutoPayAmount float64 1.0 Maximum USDC per auto-payment

Spending Safety

Set maxAutoPayAmount conservatively. This limit is enforced per-request and works alongside the global limits.maxPerTx and limits.maxDaily limits.