X402 (X402 v0.4.0)

Copy Markdown View Source

Convenience API for working with x402 payment headers and wallet addresses.

X402 exposes the most common encode/decode and validation operations while delegating implementation details to dedicated modules:

Summary

Header Encoding

decode_payment_required(header)

Decodes a PAYMENT-REQUIRED header payload.

decode_payment_response(header)

Decodes a PAYMENT-RESPONSE header payload.

decode_payment_signature(header)

Decodes a PAYMENT-SIGNATURE header payload.

encode_payment_required(payload)

Encodes a PAYMENT-REQUIRED header payload.

encode_payment_response(payload)

Encodes a PAYMENT-RESPONSE header payload.

Payment Verification

decode_and_validate_payment_signature(header)

Decodes and validates a PAYMENT-SIGNATURE payload.

validate_payment_signature(payload)

Validates a decoded PAYMENT-SIGNATURE payload.

Functions

valid_wallet?(wallet)

Returns true when the wallet address is a valid EVM or Solana address.

wallet_type(wallet)

Returns the wallet type.

Header Encoding

decode_payment_required(header)

(since 0.1.0) 
@spec decode_payment_required(String.t()) ::
  {:ok, map()} | {:error, :invalid_base64 | :invalid_json | :payload_too_large}

Decodes a PAYMENT-REQUIRED header payload.

Examples

iex> {:ok, encoded} = X402.PaymentRequired.encode(%{"x402Version" => 2, "accepts" => []})
iex> {:ok, decoded} = X402.decode_payment_required(encoded)
iex> decoded["x402Version"]
2

decode_payment_response(header)

(since 0.1.0) 
@spec decode_payment_response(String.t()) ::
  {:ok, map()} | {:error, :invalid_base64 | :invalid_json | :payload_too_large}

Decodes a PAYMENT-RESPONSE header payload.

Examples

iex> {:ok, encoded} = X402.PaymentResponse.encode(%{"success" => true, "transaction" => "0xabc", "network" => "eip155:8453"})
iex> {:ok, decoded} = X402.decode_payment_response(encoded)
iex> decoded["success"]
true

decode_payment_signature(header)

(since 0.1.0) 
@spec decode_payment_signature(String.t()) ::
  {:ok, map()} | {:error, X402.PaymentSignature.decode_error()}

Decodes a PAYMENT-SIGNATURE header payload.

Examples

iex> payload = %{"x402Version" => 2, "accepted" => %{}, "payload" => %{}}
iex> encoded = payload |> Jason.encode!() |> Base.encode64()
iex> {:ok, decoded} = X402.decode_payment_signature(encoded)
iex> decoded["x402Version"]
2

encode_payment_required(payload)

(since 0.1.0) 
@spec encode_payment_required(map()) ::
  {:ok, String.t()} | {:error, :invalid_payload | :invalid_json}

Encodes a PAYMENT-REQUIRED header payload.

Examples

iex> {:ok, header} = X402.encode_payment_required(%{"x402Version" => 2, "accepts" => []})
iex> is_binary(header)
true

encode_payment_response(payload)

(since 0.1.0) 
@spec encode_payment_response(map()) ::
  {:ok, String.t()} | {:error, :invalid_payload | :invalid_json}

Encodes a PAYMENT-RESPONSE header payload.

Examples

iex> {:ok, header} = X402.encode_payment_response(%{"success" => true, "transaction" => "0xabc", "network" => "eip155:8453"})
iex> is_binary(header)
true

Payment Verification

decode_and_validate_payment_signature(header)

(since 0.1.0) 
@spec decode_and_validate_payment_signature(String.t()) ::
  {:ok, map()} | {:error, X402.PaymentSignature.decode_and_validate_error()}

Decodes and validates a PAYMENT-SIGNATURE payload.

Examples

iex> payload = %{
...>   "x402Version" => 2,
...>   "accepted" => %{"scheme" => "exact", "network" => "eip155:8453", "amount" => "1", "asset" => "asset", "payTo" => "receiver", "maxTimeoutSeconds" => 60, "extra" => %{}},
...>   "payload" => %{}
...> }
iex> encoded = payload |> Jason.encode!() |> Base.encode64()
iex> {:ok, _decoded} = X402.decode_and_validate_payment_signature(encoded)

validate_payment_signature(payload)

(since 0.1.0) 
@spec validate_payment_signature(map()) ::
  {:ok, map()} | {:error, X402.PaymentSignature.validate_error()}

Validates a decoded PAYMENT-SIGNATURE payload.

Examples

iex> payload = %{
...>   "x402Version" => 2,
...>   "accepted" => %{"scheme" => "exact", "network" => "eip155:8453", "amount" => "1", "asset" => "asset", "payTo" => "receiver", "maxTimeoutSeconds" => 60, "extra" => %{}},
...>   "payload" => %{}
...> }
iex> X402.validate_payment_signature(payload)
{:ok, payload}

Functions

valid_wallet?(wallet)

(since 0.1.0) 
@spec valid_wallet?(term()) :: boolean()

Returns true when the wallet address is a valid EVM or Solana address.

Examples

iex> X402.valid_wallet?("0x1111111111111111111111111111111111111111")
true

iex> X402.valid_wallet?("not-a-wallet")
false

wallet_type(wallet)

(since 0.1.0) 
@spec wallet_type(term()) :: :evm | :solana | :unknown

Returns the wallet type.

Examples

iex> X402.wallet_type("0x1111111111111111111111111111111111111111")
:evm

iex> X402.wallet_type("9xQeWvG816bUx9EPfQmQTYnC16hHhV6bQf8kX6y4YB9")
:solana