* feat: add dynamic routing to bazaar
* feat: fixed format/linter errors
* fix: access routeConfig.config.settlementFailedResponseBody after getRouteConfig return type change
getRouteConfig now returns { config: RouteConfig; pattern: string } instead of RouteConfig
directly. The buildSettlementFailureResponse call site was not updated, causing
settlementFailedResponseBody callbacks to be silently skipped after settlement failures.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: updated param logic
* feat: added typescript, python and go bazaar server examples
* feat: updated e2e bazaar facilitators
* fix: add pathParams if not set
* fix: lint in python
* fix: typescript examples lock
* feat: pr feedback
* feat: pr feedback
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
140 lines
4.8 KiB
Markdown
140 lines
4.8 KiB
Markdown
# 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"` |
|