Behaviour for pluggable x402 payment schemes.

A scheme is x402's unit of extension: the pairing of a payment scheme name ("exact", "upto", ...) with a family of CAIP-2 networks ("eip155:*", "solana:*", ...). Everything scheme-specific this library does — deciding whether the client can sign an advertised requirement, producing the signed scheme payload, structurally validating an incoming PAYMENT-SIGNATURE, and running cheap local pre-checks before the facilitator round-trip — dispatches through this behaviour. Adding support for a new chain or scheme means writing one module and passing it as an option, not editing X402.Client, X402.PaymentSignature, or X402.Plug.PaymentGate.

The built-in schemes are X402.Scheme.ExactEVM (exact on eip155:* networks via EIP-3009), X402.Scheme.ExactSVM (exact on solana:* networks via partially signed v0 transactions), and X402.Scheme.UptoEVM (upto on eip155:* networks via Permit2). Resolution — including wildcard CAIP-2 matching and exact-match precedence — is handled by X402.Scheme.Registry.

Callbacks and the roles they serve

Only scheme/0 and networks/0 are required. A scheme module implements the callbacks for the roles it plays: a client-only scheme can omit validate_payload/3 and precheck/3; a server-only scheme can omit sign/3. Missing optional callbacks are neutral — signing falls back to the {:unsupported_kind, scheme, network} error, while validation and pre-checks pass through with :ok (the facilitator remains the authority).

Adding a chain or scheme in one module

Implement the behaviour:

defmodule MyApp.CashScheme do
  @behaviour X402.Scheme

  @impl X402.Scheme
  def scheme, do: "cash"

  @impl X402.Scheme
  def networks, do: ["local:*"]

  # Client side: produce the scheme payload carried as
  # PaymentPayload.payload.
  @impl X402.Scheme
  def sign(requirements, _signer, _opts) do
    {:ok, %{"note" => "IOU " <> requirements["amount"]}}
  end

  # Server side: structural validation of the decoded payload.
  @impl X402.Scheme
  def validate_payload(payload, _requirements, _opts) do
    case get_in(payload, ["payload", "note"]) do
      note when is_binary(note) -> :ok
      _missing -> {:error, {:invalid_scheme_payment, :missing_note}}
    end
  end

  # Server side: cheap local pre-checks before the facilitator call.
  @impl X402.Scheme
  def precheck(payload, _requirements, _opts) do
    case get_in(payload, ["payload", "counterfeit"]) do
      true -> {:error, {:precheck_failed, :counterfeit_note}}
      _other -> :ok
    end
  end
end

Then pass it where you use the SDK — every entry point takes a :schemes option (a list of modules consulted before the built-ins):

# Resource server: gate routes may now use scheme "cash".
plug X402.Plug.PaymentGate,
  schemes: [MyApp.CashScheme],
  routes: [
    %{
      method: :get,
      path: "/paid",
      scheme: "cash",
      price: "5",
      network: "local:test",
      asset: "note",
      pay_to: "till"
    }
  ]

# Payer client: "cash" requirements become selectable and signable.
X402.Client.build_payment(payment_required, signer, schemes: [MyApp.CashScheme])

# Standalone header validation.
X402.PaymentSignature.validate(payload, requirements, schemes: [MyApp.CashScheme])

There is no global registration and no application environment: scheme modules are passed explicitly as options, so two gates (or two clients) in the same VM can support different scheme sets. A user module listed in :schemes is consulted before the built-ins and can override them — see X402.Scheme.Registry for the exact precedence rules.

Error conventions

• sign/3 returns {:ok, scheme_payload} where scheme_payload is the map carried as the v2 PaymentPayload.payload, or {:error, reason}.
• validate_payload/3 failures should be {:error, {:invalid_scheme_payment, reason}}, which X402.Plug.PaymentGate answers with HTTP 400 Invalid Request (the built-in upto scheme keeps its historical {:invalid_upto_payment, reason} tuples, mapped the same way). Unrecognized error shapes fail closed as HTTP 500.
• precheck/3 failures should be {:error, {:precheck_failed, reason}} so the gate answers 402 without a facilitator round-trip. Pre-checks must only fail fast on certain mismatch — the facilitator remains the authority.