Stateful client for x402 facilitator verify and settle operations.
Summary
Payment Verification
Verifies a payment using the default facilitator process name.
Verifies a payment using the given facilitator process.
Verifies a payment using the given facilitator process and hook module.
Payment Settlement
Settles a payment using the default facilitator process name.
Settles a payment using the given facilitator process.
Settles a payment using the given facilitator process and hook module.
Types
Facilitator response payload, including values recovered or transformed by hooks.
Facilitator server identifier accepted by GenServer.call/3.
Payment Verification
Verifies a payment using the default facilitator process name.
Verifies a payment using the given facilitator process.
Verifies a payment using the given facilitator process and hook module.
This overrides the hook module configured when the facilitator process started.
Payment Settlement
Settles a payment using the default facilitator process name.
Settles a payment using the given facilitator process.
Settles a payment using the given facilitator process and hook module.
This overrides the hook module configured when the facilitator process started.
Types
@type operation_result() :: map()
Facilitator response payload, including values recovered or transformed by hooks.
@type response() :: {:ok, operation_result()} | {:error, X402.Facilitator.Error.t() | X402.Hooks.hook_error() | term()}
@type server() :: GenServer.server()
Facilitator server identifier accepted by GenServer.call/3.
@type state() :: %{ url: String.t(), finch: term(), hooks: module(), auth: nil | X402.Facilitator.Auth.t(), max_retries: non_neg_integer(), retry_backoff_ms: non_neg_integer(), receive_timeout_ms: non_neg_integer() }
Functions
@spec child_spec(keyword()) :: Supervisor.child_spec()
Returns a child specification for X402.Facilitator.
@spec start_link(keyword()) :: GenServer.on_start() | {:error, NimbleOptions.ValidationError.t()}
Starts the facilitator client.
When an otp_app is given, options are merged over the config :app, <name>
configuration entry, with the explicit options taking precedence. This
enables configuring the facilitator at runtime without hardcoding secrets:
# config/runtime.exs
config :my_app, MyX402,
url: X402.Facilitator.Auth.CDP.facilitator_url(),
finch: MyFinch,
auth: {X402.Facilitator.Auth.CDP,
api_key_id: System.fetch_env!("CDP_API_KEY_ID"),
api_key_secret: System.fetch_env!("CDP_API_KEY_SECRET")}
# application.ex
children = [{X402.Facilitator, otp_app: :my_app, name: MyX402}]Options
:name(term/0) - Registered name of the facilitator client process. The default value isX402.Facilitator.:otp_app(atom/0) - Application that holds this facilitator's configuration. When set,config :app, <name>is merged under the given options, with the options taking precedence. Enables the Ecto-style pattern whereconfig/runtime.exsis the single source of truth. Available since v0.5.0.:url(String.t/0) - Facilitator base URL. The default value is"https://x402.org/facilitator".:finch(term/0) - Required. Finch process name used for HTTP requests.:hooks- Lifecycle hook module implementingX402.Hooks. The default value isX402.Hooks.Default.:max_retries(non_neg_integer/0) - Maximum retry count for transient errors. The default value is2.:retry_backoff_ms(non_neg_integer/0) - Initial retry backoff in milliseconds. The default value is100.:receive_timeout_ms(non_neg_integer/0) - HTTP receive timeout in milliseconds. The default value is5000.:auth- Request authentication. Eithernil(no authentication), anX402.Facilitator.Authmodule, or a{module, opts}tuple. SeeX402.Facilitator.Auth.CDPfor the Coinbase Developer Platform facilitator. Available since v0.5.0. The default value isnil.