phdargen 9a718b002d
Fix py publishing (#2295)
* fix uv build

* exclude-newer = 3 days
2026-05-13 22:37:58 +02:00
..
2026-05-13 22:37:58 +02:00

Bazaar Discovery Example Server (Python)

FastAPI server demonstrating how to make a paid API discoverable using the Bazaar extension with dynamic route parameters.

The key addition over a basic x402 server is declare_discovery_extension -- it describes your endpoint's inputs, outputs, and path parameters so that facilitators (and agents) can automatically catalog and invoke your API.

What This Example Shows

Dynamic route parameters -- the route GET /weather/:city uses a :city slug. The x402 middleware automatically:

  1. Matches /weather/san-francisco, /weather/tokyo, etc. against the route pattern
  2. Extracts { city: "san-francisco" } as pathParams in the discovery extension
  3. Produces routeTemplate: "/weather/:city" so all concrete URLs consolidate into one catalog entry
from x402.extensions.bazaar import declare_discovery_extension, OutputConfig

routes = {
    "GET /weather/:city": RouteConfig(
        accepts=[
            PaymentOption(scheme="exact", price="$0.01", network=EVM_NETWORK, pay_to=EVM_ADDRESS),
        ],
        description="Weather data for a city",
        extensions=declare_discovery_extension(
            path_params_schema={
                "properties": {"city": {"type": "string", "description": "City name slug"}},
                "required": ["city"],
            },
            output=OutputConfig(
                example={"city": "san-francisco", "weather": "foggy", "temperature": 60}
            ),
        ),
    ),
}

@app.get("/weather/{city}")
async def get_weather(city: str) -> dict:
    ...

Note that the x402 route key uses :city (Express convention) while the FastAPI handler uses {city} (FastAPI convention). The x402 middleware handles the :city matching; FastAPI handles the {city} extraction for your handler.

Prerequisites

  • Python 3.10+
  • uv (install via docs.astral.sh/uv)
  • Valid EVM address for receiving payments (Base Sepolia)
  • Valid SVM address for receiving payments (Solana Devnet)
  • URL of a facilitator supporting the desired payment network, see facilitator list

Setup

  1. Copy .env-local to .env:
cp .env-local .env
  1. Fill required environment variables:
  • EVM_ADDRESS - Ethereum address to receive payments (Base Sepolia)
  • SVM_ADDRESS - Solana address to receive payments (Solana Devnet)
  • FACILITATOR_URL - Facilitator endpoint URL (optional, defaults to production)
  1. Install dependencies:
uv sync
  1. Run the server:
uv run python main.py

Server runs at http://localhost:4021

How Discovery Works

When a client hits GET /weather/san-francisco without a payment, the 402 response includes the enriched bazaar extension:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": { "url": "http://localhost:4021/weather/san-francisco" },
  "extensions": {
    "bazaar": {
      "routeTemplate": "/weather/:city",
      "info": {
        "input": {
          "type": "http",
          "method": "GET",
          "pathParams": { "city": "san-francisco" }
        },
        "output": {
          "type": "json",
          "example": { "city": "san-francisco", "weather": "foggy", "temperature": 60 }
        }
      }
    }
  },
  "accepts": [{ "..." : "..." }]
}

The facilitator uses routeTemplate as the canonical catalog key, so requests to /weather/san-francisco, /weather/tokyo, and /weather/new-york all map to a single discoverable endpoint: /weather/:city.

Example Endpoints

Endpoint Payment Price
GET /health No -
GET /weather/:city Yes $0.01 USDC
GET /weather/:country/:city Yes $0.01 USDC

Multiple Path Parameters

Routes can have multiple :param segments. Param names are matched by position in the URL, not by the order they appear in path_params_schema:

GET /weather/:country/:city
                 ^         ^
                 |         └── second URL segment -> "city"
                 └──────────── first URL segment  -> "country"

A request to /weather/us/san-francisco produces pathParams: { country: "us", city: "san-francisco" }. The property order in path_params_schema does not affect matching -- only the segment position in the URL matters.

declare_discovery_extension API

Parameter Purpose
input Example query parameter values (for GET/HEAD/DELETE)
input_schema JSON Schema for query parameters
path_params_schema JSON Schema for URL path parameters (:param segments)
output OutputConfig(example=...) -- example response body
body_type For POST/PUT/PATCH: "json", "form-data", or "text"