140 lines
4.8 KiB
Markdown
Raw Permalink Normal View History

# 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
```python
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](https://docs.astral.sh/uv/getting-started/installation/))
- 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](https://www.x402.org/ecosystem?category=facilitators)
## Setup
1. Copy `.env-local` to `.env`:
```bash
cp .env-local .env
```
2. 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)
3. Install dependencies:
```bash
uv sync
```
4. Run the server:
```bash
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:
```json
{
"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"` |