Skip to main content
When a server returns 402 Payment Required, it can encode payment information in several different ways. BoltzPay runs three protocol adapters in parallel (Promise.allSettled): MppAdapter, X402Adapter, and L402Adapter. Adapter priority: MPP > x402 > L402. When multiple protocols are detected, the SDK prefers MPP (IETF track), then x402 (USDC on-chain), then L402 (Lightning). If the preferred protocol’s wallet is not configured, the SDK falls back silently to the next available protocol.

​
Parallel Detection

​
How It Works

The SDK launches all three adapters in parallel via Promise.allSettled() in the protocol router. Each adapter independently probes the URL, inspects the 402 response, and reports whether it can handle it.

​
MppAdapter Detection

The MppAdapter checks the WWW-Authenticate header for an MPP scheme. MPP uses challenge-response authentication with payment methods (Tempo, Stripe, Visa). 
WWW-Authenticate: MPP method="tempo" amount="1000000" ...  --> MPP
The adapter parses all MPP challenges and selects the best method based on configured wallets and the mppPreferredMethods config.

​
X402Adapter Detection

The X402Adapter checks three locations in cascade: 1. PAYMENT-REQUIRED Header — The standard location for x402 payment data. The adapter first tries to decode it as V2 JSON (the current spec). If that fails, it tries V1 format — some servers send V1-encoded data inside the V2 header. This V1-in-V2 hybrid is rare but exists in the wild (e.g., emc2ai). 
PAYMENT-REQUIRED: {"x402Version":2,"accepts":[...]}   --> V2
PAYMENT-REQUIRED: {"x402Version":1,"payload":"..."}    --> V1-in-V2 hybrid
2. WWW-Authenticate Header (x402 only) — If no PAYMENT-REQUIRED header is found, the adapter checks WWW-Authenticate for an x402 challenge. It only matches the x402 scheme and ignores L402/LSAT challenges. 
WWW-Authenticate: x402 amount="50000" ...              --> x402
3. Response Body (x402 V1) — As a final fallback, the adapter reads the response body and attempts to parse it as x402 V1 JSON. 
{ "x402Version": 1, "payload": "...", "facilitator": "..." }

​
L402Adapter Detection

The L402Adapter checks WWW-Authenticate for an L402 or LSAT challenge with a macaroon and Lightning invoice. It is a separate adapter that runs independently from X402. 
WWW-Authenticate: L402 macaroon="..." invoice="lnbc.." --> L402
WWW-Authenticate: LSAT macaroon="..." invoice="lnbc.." --> LSAT (legacy)

​
Passthrough

If no adapter detects a supported protocol, the SDK treats the response as a regular HTTP 402. No payment is attempted, and the original response is returned to the caller.

​
Supported Formats

FormatAdapterLocationExample Server
MPPMppAdapterWWW-Authenticate headermpp.dev endpoints
x402 V2X402AdapterPAYMENT-REQUIRED headerinvy.bot, polymarket
x402 V1-in-V2X402AdapterPAYMENT-REQUIRED header (V1 payload inside)emc2ai
x402 via WWW-AuthX402AdapterWWW-Authenticate header402payment-test
x402 V1 bodyX402AdapterResponse body JSONnickeljoke (testnet)
L402 / LSATL402AdapterWWW-Authenticate headersatsapi.dev

​
Why Parallel?

The x402 ecosystem is young. Servers implement different spec versions and sometimes mix formats. By running all three adapters in parallel, BoltzPay maximizes compatibility and speed without requiring any configuration from the user. Your agent calls fetch() and the SDK figures out the rest.

​
Wallet-Aware Fallback

After detection, the SDK sorts results by priority (MPP > x402 > L402) and filters by configured wallets. If an endpoint supports both MPP and x402:
  • With a Tempo wallet configured: MPP is used
  • With only Coinbase credentials: x402 is used
  • With both: MPP is preferred (higher priority)
  • With neither: an actionable error lists detected protocols and required wallet types
Endpoint supports MPP (tempo, stripe) and x402 (coinbase).
Configure at least one wallet.

​
Next Steps