X402.Extensions.Bazaar (X402 v0.5.0)

Copy Markdown View Source

Builds the bazaar discovery extension for x402 v2.

Resource servers advertise their endpoint specification by placing the extension under extensions.bazaar in a PAYMENT-REQUIRED response. The extension carries the actual discovery data (info) together with a JSON Schema (Draft 2020-12) that validates it (schema).

info.input is a discriminated union selected by the type field:

  • "http" — an HTTP endpoint. Query methods (GET, HEAD, DELETE) describe example query parameters; body methods (POST, PUT, PATCH) add a bodyType and an example body.
  • "mcp" — a Model Context Protocol tool, identified by toolName and described by a JSON Schema inputSchema for its arguments.

info.output describes the expected response format. It is always present (defaulting to a "json" content type). The schema's output property declares type (and optionally format) as strings and infers the JSON type of example, optionally refined by the :schema option.

The factory returns a plain, string-keyed map ready for JSON encoding:

extensions = %{"bazaar" => X402.Extensions.Bazaar.build_extension(method: :get)}

See the bazaar extension spec.

Summary

Types

t()

A built extensions.bazaar discovery extension payload.

Functions

build_extension(opts)

Builds a bazaar discovery extension payload (info + schema).

Types

t()

@type t() :: %{required(binary()) => map()}

A built extensions.bazaar discovery extension payload.

Functions

build_extension(opts)

(since 0.5.0) 
@spec build_extension(keyword()) :: t()

Builds a bazaar discovery extension payload (info + schema).

Accepts either an HTTP endpoint config or an MCP tool config.

HTTP options

  • :method — (required) HTTP method: :get, :head, :delete, :post, :put, :patch (or the uppercase string). Query methods produce a read-only signature; body methods add bodyType and body.
  • :input — example input values (a map of query parameters for query methods, a map for "json" / "form-data" bodies, or a string for "text" bodies).
  • :input_schema — JSON Schema merged into the schema's queryParams or body property.
  • :body_type — request body content type for body methods: "json" (default), "form-data", or "text".
  • :headers — example custom header values.
  • :path_params — concrete path parameter values (dynamic routes).
  • :path_params_schema — JSON Schema for path parameters.

MCP options

  • :tool_name — (required) MCP tool name.
  • :input_schema — (required) JSON Schema for the tool's arguments.
  • :description — human-readable tool description.
  • :transport — MCP transport: "streamable-http" (default) or "sse".
  • :example — example arguments object.

Output options (:output)

A keyword list or map describing the expected response:

  • :type — response content type (default "json").
  • :format — additional format information.
  • :example — example response value.
  • :schema — JSON Schema merged into the schema's example property.

Examples

iex> ext = X402.Extensions.Bazaar.build_extension(method: :get, input: %{"city" => "San Francisco"})
iex> ext["info"]["input"]["type"]
"http"
iex> ext["info"]["input"]["method"]
"GET"
iex> ext["info"]["input"]["queryParams"]
%{"city" => "San Francisco"}

iex> ext = X402.Extensions.Bazaar.build_extension(method: :post, input: %{"query" => "example"})
iex> ext["info"]["input"]["bodyType"]
"json"

iex> ext = X402.Extensions.Bazaar.build_extension(
...>   tool_name: "financial_analysis",
...>   input_schema: %{"type" => "object", "properties" => %{"ticker" => %{"type" => "string"}}, "required" => ["ticker"]}
...> )
iex> ext["info"]["input"]["type"]
"mcp"
iex> ext["info"]["input"]["toolName"]
"financial_analysis"