X402.Facilitator.HTTP (X402 v0.6.0)

HTTP transport for facilitator requests.

request/5 performs the POST requests used by verify and settle; get/4 performs the GET requests used by /supported and /discovery/resources.

Summary

Types

finch_name()

query()

Query string parameters accepted by get/4.

response()

Functions

get(finch_name, base_url, path, opts \\ [])

Performs a facilitator HTTP GET request.

request(finch_name, base_url, path, payload, opts \\ [])

Performs a facilitator HTTP POST request.

secure_pool_opts()

Returns recommended Finch pool options with TLS peer verification enabled.

Types

finch_name()

@type finch_name() :: atom() | pid() | {:via, module(), term()}

query()

@type query() :: [{String.t(), String.t() | integer()}]

Query string parameters accepted by get/4.

response()

@type response() ::
  {:ok, %{status: non_neg_integer(), body: map()}}
  | {:error, X402.Facilitator.Error.t()}

Functions

get(finch_name, base_url, path, opts \\ [])

(since 0.6.0)

@spec get(finch_name(), String.t(), String.t(), keyword()) :: response()

Performs a facilitator HTTP GET request.

Used for the read-only facilitator endpoints (GET /supported and GET /discovery/resources). No request body is sent.

In addition to the options accepted by request/5, opts supports:

:query (default: []) — query string parameters as a list of {name, value} tuples with string names and string or integer values, encoded with URI.encode_query/1.

The same TLS requirements as request/5 apply; see secure_pool_opts/0.

request(finch_name, base_url, path, payload, opts \\ [])

(since 0.1.0)

@spec request(finch_name(), String.t(), String.t(), map(), keyword()) :: response()

Performs a facilitator HTTP POST request.

opts supports:

:max_retries (default: 2)
:retry_backoff_ms (default: 100)
:receive_timeout_ms (default: 5_000)
:headers (default: []) — additional {name, value} request headers, merged after the JSON content headers.

TLS Verification

REQUIRED: TLS peer verification must be configured when starting your Finch pool. Failure to do so leaves your application vulnerable to MITM attacks.

Example configuration:

Finch.start_link(
  name: MyFinch,
  pools: %{
    default: [
      conn_opts: [
        transport_opts: [
          verify: :verify_peer,
          # Note: requires OTP 25+, see https://www.erlang.org/doc/apps/public_key/public_key.html#cacerts_get/0
          cacerts: :public_key.cacerts_get()
        ]
      ]
    ]
  }
)

See secure_pool_opts/0 for a ready-to-use configuration.

secure_pool_opts()

(since 0.3.2)

@spec secure_pool_opts() :: keyword()

Returns recommended Finch pool options with TLS peer verification enabled.

Use these when starting your Finch pool to ensure facilitator connections are verified against the system CA store:

Finch.start_link(
  name: MyFinch,
  pools: %{default: X402.Facilitator.HTTP.secure_pool_opts()}
)

Requires OTP 25+ for :public_key.cacerts_get/0.