X402.Facilitator.HTTP (X402 v0.3.3)

Copy Markdown View Source

HTTP transport for facilitator verify and settle requests.

Summary

Types

finch_name()
response()

Functions

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()}

response()

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

Functions

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)

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.