@spec list_resources(
  server() | keyword(),
  keyword()
) ::
  {:ok, discovery_resources_response()}
  | {:error, X402.Facilitator.Error.t() | NimbleOptions.ValidationError.t()}

Lists discoverable x402 resources from the facilitator's bazaar.

Performs GET /discovery/resources in the calling process. Filter and pagination parameters are validated with NimbleOptions and encoded as query string parameters. The response is validated fail-closed: a malformed body returns {:error, %X402.Facilitator.Error{type: :malformed_facilitator_response}}.

Items are returned as raw, string-keyed maps exactly as sent by the facilitator. X402.Hooks callbacks do not apply to this read-only operation.

When called with just a keyword list — list_resources(limit: 20) — the parameters apply to the default facilitator process name.

Parameters

• :type (String.t/0) - Filter by resource type (for example "http" or "mcp").

• :pay_to (String.t/0) - Filter by payment recipient address (sent as payTo).

• :scheme (String.t/0) - Filter by payment scheme (for example "exact").

• :network (String.t/0) - Filter by CAIP-2 payment network (for example "eip155:8453").

• :extensions (String.t/0) - Filter by extension key present on each discovered resource.

• :limit - Maximum number of results to return (1–100; server default 20).

• :offset (non_neg_integer/0) - Number of results to skip for pagination.

Examples

{:ok, %{items: items, pagination: pagination}} =
  X402.Facilitator.list_resources(MyFacilitator,
    network: "eip155:8453",
    limit: 20
  )

@spec search_resources(
  server() | keyword(),
  keyword()
) ::
  {:ok, discovery_search_response()}
  | {:error, X402.Facilitator.Error.t() | NimbleOptions.ValidationError.t()}

Searches discoverable x402 resources in the facilitator's bazaar.

Performs GET /discovery/search in the calling process — the natural-language search endpoint of the bazaar extension. Parameters are validated with NimbleOptions and encoded as query string parameters; :query is required. The response is validated fail-closed: a malformed body returns {:error, %X402.Facilitator.Error{type: :malformed_facilitator_response}}.

Unlike list_resources/2, the search endpoint pages with an opaque cursor: pass pagination.cursor from one response as :cursor to fetch the next page, until it is nil. Both :limit and :cursor are advisory — the facilitator may ignore them.

Resources are returned as raw, string-keyed maps exactly as sent by the facilitator (X402.Extensions.Bazaar.search/2 parses them). X402.Hooks callbacks do not apply to this read-only operation.

When called with just a keyword list — search_resources(query: "weather") — the parameters apply to the default facilitator process name.

Parameters

• :query (String.t/0) - Required. Natural-language search query.

• :type (String.t/0) - Filter by resource type (for example "http" or "mcp").

• :pay_to (String.t/0) - Filter by payment recipient address (sent as payTo).

• :scheme (String.t/0) - Filter by payment scheme (for example "exact").

• :network (String.t/0) - Filter by CAIP-2 payment network (for example "eip155:8453").

• :extensions (String.t/0) - Filter by extension key present on each discovered resource.

• :limit (pos_integer/0) - Advisory maximum number of results; the facilitator may return fewer or ignore it.

• :cursor (String.t/0) - Advisory continuation cursor from a previous page's pagination.cursor.

Examples

{:ok, %{resources: resources, pagination: pagination}} =
  X402.Facilitator.search_resources(MyFacilitator,
    query: "weather forecast APIs",
    network: "eip155:8453",
    limit: 10
  )

@spec supported(server()) ::
  {:ok, supported_response()} | {:error, X402.Facilitator.Error.t()}

Fetches the payment kinds, extensions, and signers a facilitator supports.

Performs GET /supported in the calling process and validates the response fail-closed: a malformed body returns {:error, %X402.Facilitator.Error{type: :malformed_facilitator_response}} rather than partial data. Missing extensions and signers fields default to [] and %{} (matching the reference TypeScript client); a missing or malformed kinds field is an error.

X402.Hooks callbacks do not apply to this read-only operation.

Examples

{:ok, %{kinds: kinds, extensions: _, signers: signers}} =
  X402.Facilitator.supported(MyFacilitator)

Enum.any?(kinds, &(&1.scheme == "exact" and &1.network == "eip155:8453"))