# `X402.Facilitator.HTTP`
[🔗](https://github.com/cardotrejos/x402/blob/v0.9.0/lib/x402/facilitator/http.ex#L1)

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`.

# `finch_name`

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

# `query`

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

Query string parameters accepted by `get/4`.

# `response`

```elixir
@type response() :: {:ok, success()} | {:error, X402.Facilitator.Error.t()}
```

# `success`

```elixir
@type success() :: %{
  status: non_neg_integer(),
  body: map(),
  headers: [{String.t(), String.t()}]
}
```

A successful facilitator HTTP response.

`:headers` carries the response headers as returned by Finch (names
lower-cased), so callers can read transport sidechannels such as
`EXTENSION-RESPONSES` (see `X402.ExtensionResponses`).

# `get`
*since 0.6.0* 

```elixir
@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`
*since 0.1.0* 

```elixir
@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* 

```elixir
@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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*