Architecture

The x402 Elixir SDK is an Elixir library implementing the x402 HTTP payment protocol (v2). It ships as a Hex package with no web server, database, or external service required by default. Behaviours allow applications to replace transports, signing, payment schemes, and storage.

Design principles

• Behaviours over config: extensibility via @callback (X402.Scheme, X402.Signer, X402.Hooks, X402.Extension, X402.Paywall, storage and cache adapters), not application environment.
• Flat module naming: X402.Wallet, not X402.Utils.Validators.Wallet.
• Tagged tuples, no exceptions for expected failures: fallible functions return {:ok, result} | {:error, reason}. Option validation may raise only where the contract explicitly uses NimbleOptions.validate!/2 (for example Plug initialization).
• Minimal required deps: jason, nimble_options, and telemetry. Finch, Plug, ex_secp256k1, ex_keccak, Redix, and telemetry_metrics are optional and guarded by compile-time availability checks; the package must compile with mix compile --no-optional-deps.
• Processes only where state lives: facilitator clients, spend budgets, nonce managers, cache adapters, and ETS table ownership use long-lived processes. Wire codecs, signing, and validation are function-based.

Module map

Wire format

Schemes and signing

ERC-7710 delegated transfers remain unsupported. Unknown transfer methods fail closed rather than falling back to another authorization.

Local verification

Facilitator

Resource server

Payer client

MCP transport

Extensions

HTTP authentication primitives

Authentication declarations do not enforce access. Applications own credential validation, trusted key discovery, nonce replay storage, body-digest checks, and proxy-aware URI reconstruction. Discovery URLs are untrusted inputs, not permission to fetch credentials or remote keys automatically.

Infrastructure

Request flow through X402.Plug.PaymentGate

Parameter routes match once-decoded Plug segments, not a rejoined path. An encoded slash remains inside one capture and cannot bypass a paid route. SIWX access grants bind the HTTP method and full URL, including origin and query, before the handler runs. The flow below covers requests requiring payment.

Incoming HTTP request
        │
        ├─ No PAYMENT-SIGNATURE → 402 + PAYMENT-REQUIRED (or HTML paywall for browsers)
        │
        └─ PAYMENT-SIGNATURE present
                ├─ Decode PaymentPayload (x402Version must be 2)
                │     malformed / wrong version → 400 + PAYMENT-REQUIRED
                ├─ Match payload.accepted against route requirements + extension echoes
                │     no match → 402 + PAYMENT-REQUIRED
                ├─ Optional inline local verification (X402.Verify.*)
                │     rejection → 402; infrastructure failure → 500
                ├─ Facilitator.verify + signature-bound replay claim
                │     invalid or replayed → 402; server/facilitator fault → 500
                ├─ Optional verified-payer/IP rate limit
                │     exhausted → 429 + Retry-After, no handler or settlement
                ├─ Assign payload/requirements → protected handler
                │     handler status >= 400 → skip settlement
                └─ Successful handler → Facilitator.settle before send
                      settlement_pending → exactly one retried settle
                      success → PAYMENT-RESPONSE + resource response
                      payment failure → 402; server/facilitator fault → 500

Replay claims use a signature-covered key per scheme family (EIP-3009 from

• nonce, Permit2 owner + canonicalized nonce, SVM message hash; raw-header hash for unknown schemes). The payment-identifier extension is surfaced but is deliberately not the dedup key: it is client-chosen and not covered by the payment signature. "upto" routes may replace the advertised maximum with the metered settlement amount. Missing facilitator decision fields fail closed. For built-in EVM payments, verification, settlement, payer reporting, and pending-settlement identity select authorization from the matched requirements. Unsigned alternate authorization objects never override that selection.

Operational boundaries

Rate limits run after payment verification, before resource execution and settlement. Payer keys prefer the facilitator's verified payer; fallback extraction is bound to the verified scheme, network, and transfer method. Unauthenticated claimed payer fields never select another wallet's quota. The default ETS limiter is per-node, defaults to allowing requests on store failure, and does not cover MCP calls or payment-exempt requests.

Facilitator failover retries read and verification failures according to the endpoint policy. With fallbacks configured, settlement makes one HTTP attempt per endpoint and switches providers only after a classified non-delivery failure. Timeouts, closed connections, TLS alerts, and server errors remain ambiguous and must not trigger another provider's settlement.

Telemetry metrics and statistics are optional observability surfaces, not a Phoenix dashboard or a durable accounting ledger.

Optional dependencies

Data formats (x402 v2)

All headers carry Base64-encoded JSON:

• PAYMENT-REQUIRED: {x402Version: 2, error?, resource, accepts[], extensions?}; each accept is {scheme, network, amount, asset, payTo, maxTimeoutSeconds, extra}.
• PAYMENT-SIGNATURE: {x402Version: 2, resource?, accepted, payload, extensions?}; accepted is a full requirements object that must match a server accept.
• PAYMENT-RESPONSE: {success, transaction, network, payer?, amount?, errorReason?, extensions?}.

Networks use CAIP-2 identifiers, e.g. "eip155:8453" (Base) and "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" (Solana mainnet).

Telemetry

Events are [:x402, module, operation] with a :status metadata key; the module and operation atoms are typed in X402.Telemetry, which is the authoritative list.