X402.PaymentRequirements (X402 v0.4.1)

Validation and matching helpers for x402 v2 payment requirements.

A client's PaymentPayload.accepted value must preserve every core field advertised by the resource server. Server-declared extra values are matched as a recursive subset so clients may append scheme-specific metadata without changing the server's payment terms.

Summary

Types

validation_error()

Functions

extensions_match?(advertised, echoed)

Returns whether client extension echoes preserve advertised extension values.

match?(required, accepted)

Returns whether a client-selected requirement preserves the server requirement.

validate(requirements)

Validates the required x402 v2 PaymentRequirements fields.

Types

validation_error()

@type validation_error() ::
  {:missing_fields, [String.t()]} | {:invalid_fields, [String.t()]}

Functions

extensions_match?(advertised, echoed)

(since 0.4.0)

@spec extensions_match?(term(), term()) :: boolean()

Returns whether client extension echoes preserve advertised extension values.

Omitting extensions is accepted for compatibility with the reference SDK. When the client echoes an advertised extension, every server-provided value must be retained.

Examples

iex> advertised = %{"example" => %{"info" => %{"required" => true}}}
iex> echoed = %{"example" => %{"info" => %{"required" => true, "client" => "value"}}}
iex> X402.PaymentRequirements.extensions_match?(advertised, echoed)
true

match?(required, accepted)

(since 0.4.0)

@spec match?(term(), term()) :: boolean()

Returns whether a client-selected requirement preserves the server requirement.

Core fields must be equal. The client may add fields under extra, but it cannot remove or change values advertised by the server.

Examples

iex> required = %{"scheme" => "exact", "extra" => %{"name" => "USDC"}}
iex> accepted = %{"scheme" => "exact", "extra" => %{"name" => "USDC", "version" => "2"}}
iex> X402.PaymentRequirements.match?(required, accepted)
true

iex> required = %{"scheme" => "exact", "extra" => %{"name" => "USDC"}}
iex> X402.PaymentRequirements.match?(required, %{"scheme" => "exact", "extra" => %{}})
false

validate(requirements)

(since 0.4.0)

@spec validate(term()) ::
  :ok | {:error, validation_error() | :invalid_payment_requirements}

Validates the required x402 v2 PaymentRequirements fields.

Examples

iex> requirements = %{
...>   "scheme" => "exact",
...>   "network" => "eip155:84532",
...>   "amount" => "10000",
...>   "asset" => "0xasset",
...>   "payTo" => "0xreceiver",
...>   "maxTimeoutSeconds" => 60,
...>   "extra" => %{}
...> }
iex> X402.PaymentRequirements.validate(requirements)
:ok

iex> X402.PaymentRequirements.validate(%{})
{:error, {:missing_fields, ["amount", "asset", "extra", "maxTimeoutSeconds", "network", "payTo", "scheme"]}}