Python x402 Facilitator Bazaar Discovery Reference

Python x402 Facilitator Bazaar Discovery Reference

Detailed API reference for the Bazaar discovery extension in the x402-avm Python package.

Bazaar Extension API

declare_discovery_extension()

from x402.extensions.bazaar import declare_discovery_extension

Creates a discovery extension dict for route configuration.

Signature:

def declare_discovery_extension(
    input: dict,
    input_schema: dict,
    body_type: str | None = None,
    output: OutputConfig | None = None,
) -> dict:

Parameters:

Returns: {"bazaar": {"info": {...}, "schema": {...}}}

body_type values:

extract_discovery_info()

from x402.extensions.bazaar import extract_discovery_info

Extracts discovery info from a payment request. Handles both v2 (extensions in PaymentPayload) and v1 (output_schema in PaymentRequirements) formats.

Signature:

def extract_discovery_info(
    payment_payload: PaymentPayload | dict,
    payment_requirements: PaymentRequirements | dict,
    validate: bool = True,
) -> DiscoveredResource | None:

Parameters:

Returns: DiscoveredResource or None if no Bazaar extension found

extract_discovery_info_from_extension()

from x402.extensions.bazaar import extract_discovery_info_from_extension

Extracts discovery info from an extension object directly.

Signature:

def extract_discovery_info_from_extension(
    extension: dict | DiscoveryExtension,
    validate: bool = True,
) -> DiscoveryInfo:

Parameters:

Returns: QueryDiscoveryInfo or BodyDiscoveryInfo

validate_discovery_extension()

from x402.extensions.bazaar import validate_discovery_extension

Validates that an extension's info data conforms to its schema.

Signature:

def validate_discovery_extension(
    extension: dict | DiscoveryExtension,
) -> ValidationResult:

Parameters:

Returns: ValidationResult with valid: bool and errors: list[str]

validate_and_extract()

from x402.extensions.bazaar import validate_and_extract

Validates and extracts discovery info in one step.

Signature:

def validate_and_extract(
    extension: dict | DiscoveryExtension,
) -> ValidationExtractResult:

Returns: Object with valid: bool, errors: list[str], and info: DiscoveryInfo | None

bazaar_resource_server_extension

from x402.extensions.bazaar import bazaar_resource_server_extension

A server-side extension that enriches discovery declarations with HTTP method information at runtime. Must be registered on an x402ResourceServer or x402ResourceServerSync instance.

Usage:

server.register_extension(bazaar_resource_server_extension)

What it does at runtime:

1. Intercepts the declaration enrichment step when an HTTP request arrives for a payment-protected route with a "bazaar" extension
2. Reads the HTTP method from the transport context (e.g., request.method)
3. Injects the method into info.input.method and updates the schema
4. The enriched extension is included in the 402 Payment Required response

with_bazaar()

from x402.extensions.bazaar import with_bazaar

Extends a facilitator client with discovery query capabilities.

Signature:

def with_bazaar(
    client: HTTPFacilitatorClient,
) -> BazaarExtendedClient:

Returns: Extended client with client.extensions.discovery.list_resources() method. All original facilitator client methods are delegated transparently.

OutputConfig

from x402.extensions.bazaar import OutputConfig

Configuration for the output portion of a discovery extension.

Fields:

Data Types

DiscoveredResource

@dataclass
class DiscoveredResource:
    resource_url: str          # Normalized URL (no query/hash)
    method: str                # HTTP method (GET, POST, etc.)
    x402_version: int          # 1 or 2
    discovery_info: DiscoveryInfo  # QueryDiscoveryInfo or BodyDiscoveryInfo
    description: str | None    # From resource info or requirements
    mime_type: str | None      # From resource info or requirements

DiscoveryInfo (Union Type)

DiscoveryInfo = QueryDiscoveryInfo | BodyDiscoveryInfo

ValidationResult

@dataclass
class ValidationResult:
    valid: bool
    errors: list[str]  # Empty when valid

Pydantic Models (from x402.extensions.bazaar.types)

Union Types

Type Constants and Literals

Config Dataclasses

Client Types (from x402.extensions.bazaar.facilitator_client)

Helper Functions (from x402.extensions.bazaar.types)

Functions Summary Table

Installation Commands

# Extensions only
pip install "x402-avm[extensions]"

# Extensions + Algorand support
pip install "x402-avm[extensions,avm]"

# Extensions + Algorand + FastAPI
pip install "x402-avm[extensions,avm,fastapi]"

# Extensions + Algorand + Flask
pip install "x402-avm[extensions,avm,flask]"

# Everything
pip install "x402-avm[all]"

The [extensions] extra adds one dependency: jsonschema>=4.0.0.

Testing

# Start the server with Bazaar discovery
AVM_ADDRESS="your-address" uvicorn server:app --port 4021

# Check health
curl http://localhost:4021/health

# Access the payment-gated endpoint (will return 402 with discovery metadata)
curl -v http://localhost:4021/weather?city=London
# Response includes 402 status with PaymentRequired body containing bazaar extension

External Resources

• Extensions Examples
• x402-avm AVM Documentation
• JSON Schema Specification
• CAIP-2 Chain ID Specification