Carson Roscoe 30a847d7d1
feat: New Python SDK with v2 support (#841)
* chore: renamed python/x402 to python/legacy

* feat: initial Python core SDK

* feat: added core HTTP wrappers

* feat: added core types

* feat: added evm mechanism for exact v1/v2

* feat: added httpx client

* feat: added requests client

* feat: added fastapi middleware

* feat: added flask middleware

* feat: added integration tests

* feat: added Python SDK to e2e tests

* python-v2: fix workflow checks (#863)

* fix format

* fix lint

* fix build

* fix pytest

* Fix syntax errors and missing imports in manual integration example (#902)

- Add missing imports (base64, json, Response, JSONResponse, PaymentPayload, FacilitatorClient)
- Fix function signature syntax error
- Fix dict initialization syntax (colon to equals)
- Add missing return statement after successful payment
- Remove trailing whitespace

* feat: add Python SDK v2 server examples (FastAPI, Flask)  (#879)

* feat: add fastapi example project configuration

* feat: add fastapi example with x402 payment middleware

* docs: add comprehensive README for fastapi example

* feat: add flask example project configuration

* feat: add flask example with x402 payment middleware

* docs: add comprehensive README for flask example

* feat: add test clients for fastapi and flask examples

* docs: add test client usage to READMEs

* chore - remove python-version and test-client.py

* docs - remove test client guide from README.md

* chore - remove license and classifier

* feat - add description and mime type

* feat - update .env-local

* feat: add Python v2 client examples (httpx & requests) (#857)

* feat: add Python v2 client examples (httpx & requests)

Add simple client examples demonstrating httpx (async) and requests (sync) usage with the x402 Python v2 SDK.

- examples/python/clients/example.py - Simple example showing both httpx and requests
- Uses EthAccountSigner with register_exact_evm_client helper
- Minimal configuration required

* refactor: split Python client examples into separate directories

Address PR review feedback:
- Separate httpx/ and requests/ directories
- Add pyproject.toml for uv sync support
- Add environment variable validation
- Add payment response header extraction
- Use context manager for requests session cleanup

Tested on Base Sepolia testnet:
- httpx: tx 0xce49f668aba01c4b0b1af2eb0d9a381f4c62295506a91f20af479e0e834ef350
- requests: tx 0xb83b6feefa5a744b7779ba5b37df33f9c7241f58119454d66102acd97a92f024

* Update examples/python/clients/httpx/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

* Update examples/python/clients/requests/main.py

Co-authored-by: phdargen <pdargent@icloud.com>

---------

Co-authored-by: phdargen <pdargent@icloud.com>

* feat(python): Make v2 framework and client dependencies optional extras (#901)

* python-v2: add svm mechanism (#904)

* add svm mechanism

* add unit tests

* add integration tests

* update server examples

* add e2e tests

* update clients

* make EVM/SVM dependencies optional extras

* fix legacy uv paths

* V2 python bazaar (#929)

* add bazaar extension

* strip query params for discovery

* fix 862

* updated e2e tests

* Add advanced Python client examples (#947)

* Add advanced Python client examples

Implements 5 advanced patterns demonstrating x402 SDK v2 features:
- hooks.py: Payment lifecycle hooks (before, after, failure)
- preferred_network.py: Custom network preference selector
- builder_pattern.py: Network-specific registration with wildcards
- error_recovery.py: Error classification and recovery strategies
- custom_transport.py: Custom httpx transport with retry/timing

Includes:
- CLI entry point (index.py) for running examples
- Comprehensive test suite (40 unit tests)
- E2E integration tests
- README documentation

All tests passing.

* Remove tests and examples beyond TypeScript SDK parity

Address PR review feedback:
- Remove tests directory (tests belong in SDK, not examples)
- Remove custom_transport.py (runtime error, beyond TS parity)
- Remove error_recovery.py (duplicate of hooks.py, beyond TS parity)
- Update index.py, README.md, pyproject.toml accordingly

* Address PR feedback: add SVM support and use optional deps

- Update pyproject.toml to use x402[evm,svm,httpx] instead of
  listing dependencies separately
- Add Solana/SVM network examples to preferred_network.py
- Support both EVM and SVM signers for cross-chain flexibility
- Update .env-local with SOLANA_PRIVATE_KEY option

* Python-v2: facilitator example + e2e (#950)

* add facilitator example

* improve svm signer

* add description to DiscoveredResource

* add facilitator e2e

* add paywall builder (#953)

* Add Python custom client example (#954)

Demonstrates manual x402 v2 payment flow without convenience wrappers.

Shows the 6-step process:
1. Initialize client and register payment schemes
2. Make initial request, receive 402
3. Decode PAYMENT-REQUIRED header
4. Create signed payment payload
5. Retry with PAYMENT-SIGNATURE header
6. Handle success/failure response

Useful for integrating with non-standard HTTP libraries or implementing
custom retry logic.

* feat(v2-sdk): support async dynamic hooks for price and metadata (#900)

* feat(http): implement dual class design for sync/async support

- Add x402HTTPResourceServer (async) for FastAPI/Starlette
- Add x402HTTPResourceServerSync (sync) for Flask/Django
- Share common logic via _x402HTTPServerBase
- Remove dynamic description/resource (keep only dynamic price/payTo)
- Update Flask middleware to use sync server directly
- Integrate with enrich_extensions for bazaar support
- Add per-route hook_timeout_seconds configuration

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(types): add missing Awaitable import and fix test import sorting

- Add Awaitable import to types.py for DynamicPayTo/DynamicPrice type hints
- Fix import block sorting in test_async_hooks.py and test_core.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify API by removing unused types and making timeout opt-in

Address reviewer feedback from @phdargen:
- Remove SyncDynamicPayTo/SyncDynamicPrice (unused types that would require SyncPaymentOption to be useful)
- Change hook_timeout_seconds default to None (opt-in, matching TS/Go parity)
- Export x402HTTPResourceServerSync from http/__init__.py

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

* python-v2: make create_facilitator_config work with both V1 and V2 (#968)

* make create_facilitator_config work with both V1 and V2

* fix lint

* feat: add Python SDK v2 server advanced example (FastAPI) (#952)

* feat - add pyproject.toml, uv.lock for advanced example

* feat - add bazaar extension

* feat - add hooks

* feat - add x402 extensions to pyproject.toml

* feat - add dynamic pricing feature

* feat - add dynamic pay-to and custom money parser features

* docs - add README for advanced server example

* style - apply lint

* chore - add comments for bazaar extension code

* fix: python v2 x402HTTPAdapter retry logic (#978)

* fix: fix consecutive payment bug in x402HTTPAdapter

- Replace instance-level _is_retry flag with per-request header
  to prevent state leakage between consecutive 402 requests.

* tests - add test case for consecutive payment with x402HTTPAdapter

* style - apply lint

* Python-v2: async lifecycle hooks (#975)

* add dual sync/async classes for server/client/facilitator

* update integration/e2e tests

* add unit tests for core, http and implement wrapHttpxWithPaymentFromConfig/wrapRequestsWithPayment

* refactor core server/client/facilitator

* refactor x402_http_server/facilitator_client/x402_http_client

* update exmamples

* add utility function that takes care of html-safe escaping

* add sdk readmes

* add retry unit tests to httpx client

* Update Python SDK Docs for v2 (#976)

* Porting docs and updating for v2 changes (#813)

* porting docs and updating for v2 changes

* update quickstart for sellers

* update quickstarts, miniapps, and mcp docs

* update doc links

* update FAQs

* fix getting started docs

* update core concepts

* remove miniapps guide

* update extensions

* fix bazaar code examples

* fix broken links and yaml file

* remove unnecessary protocol layer doc

* add migration guide

* update documentation for python v2 sdk

* testing pr preview

* docs(python): remove unused os imports and align with TS tab patterns

- Remove unused 'import os' from FastAPI and Flask examples in quickstart-for-sellers
- Update bazaar-discovery-layer Python example to use hardcoded '0xYourPrivateKey' to match TypeScript tab consistency

* update migration doc

* cleanup comments

* cleanup readme

* fix: Python facilitator e2e code

* fix: lint

---------

Co-authored-by: phdargen <p.dargent@cern.ch>
Co-authored-by: somesome <57699892+sohw400@users.noreply.github.com>
Co-authored-by: Logan Kang <kcs93023@gmail.com>
Co-authored-by: 1bcMax <viewitter@gmail.com>
Co-authored-by: phdargen <pdargent@icloud.com>
Co-authored-by: Vladimir Sotnikov <bubert9@gmail.com>
Co-authored-by: Shuhei <shuhei0866@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Faris Habib <faris.habib@coinbase.com>
2026-01-21 16:32:07 -08:00

9.6 KiB

x402 Custom Server (Python)

Demonstrates how to implement x402 payment handling manually without using pre-built middleware packages like x402-fastapi.

from x402.http import HTTPFacilitatorClient, FacilitatorConfig
from x402.mechanisms.evm.exact import ExactEvmServerScheme
from x402.server import x402ResourceServer

resource_server = x402ResourceServer(
    HTTPFacilitatorClient(FacilitatorConfig(url=facilitator_url))
).register("eip155:84532", ExactEvmServerScheme())

# In your request handler:
if not payment_header:
    payment_required = resource_server.create_payment_required_response([requirements], resource)
    return JSONResponse(status_code=402, headers={"PAYMENT-REQUIRED": encode(payment_required)})

payment_payload = decode(payment_header)
verify_result = await resource_server.verify_payment(payment_payload, requirements)
if not verify_result.is_valid:
    return JSONResponse(status_code=402, content={"error": verify_result.invalid_reason})

# Execute handler, then settle
settle_result = await resource_server.settle_payment(payment_payload, requirements)
response.headers["PAYMENT-RESPONSE"] = encode(settle_result)

Prerequisites

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

Setup

  1. Copy .env-local to .env:
cp .env-local .env

and 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 "https://x402.org/facilitator")
  1. Install dependencies:
uv sync
  1. Run the server:
uv run python main.py

Or with uvicorn directly:

uv run uvicorn main:app --host 0.0.0.0 --port 4021 --reload

Testing the Server

You can test the server using one of the example clients:

Using the httpx Client

cd ../../clients/httpx
# Ensure .env is setup
uv run python main.py

Using the requests Client

cd ../../clients/requests
# Ensure .env is setup
uv run python main.py

These clients will demonstrate how to:

  1. Make an initial request to get payment requirements
  2. Process the payment requirements
  3. Make a second request with the payment token

Example Endpoint

The server includes a single example endpoint at /weather that requires a payment of 0.001 USDC on Base Sepolia to access. The endpoint returns weather data for a given city.

HTTP Headers

Request Headers

When submitting payment, include one of these headers (both are supported for backwards compatibility):

Header Protocol Description
PAYMENT-SIGNATURE v2 Base64-encoded JSON payment payload
X-PAYMENT v1 Base64-encoded JSON payment payload

Example request with payment:

GET /weather HTTP/1.1
Host: localhost:4021
PAYMENT-SIGNATURE: eyJwYXltZW50IjoiLi4uIn0=

Response Headers

Header Status Description
PAYMENT-REQUIRED 402 Base64-encoded JSON with payment requirements
PAYMENT-RESPONSE 200 Base64-encoded JSON with settlement details

Response Format

Payment Required (402)

HTTP/1.1 402 Payment Required
Content-Type: application/json
PAYMENT-REQUIRED: <base64-encoded JSON>

{"error":"Payment Required","message":"This endpoint requires payment"}

The PAYMENT-REQUIRED header contains base64-encoded JSON with the payment requirements:

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "http://localhost:4021/weather",
    "description": "Weather data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USDC",
        "version": "2",
        "resourceUrl": "http://localhost:4021/weather"
      }
    }
  ]
}

Successful Response (with payment)

HTTP/1.1 200 OK
Content-Type: application/json
PAYMENT-RESPONSE: <base64-encoded JSON>

{"city":"San Francisco","weather":"foggy","temperature":60,"timestamp":"2024-01-01T12:00:00.000000"}

The PAYMENT-RESPONSE header contains base64-encoded JSON with the settlement details:

{
  "success": true,
  "transaction": "0x...",
  "network": "eip155:84532",
  "payer": "0x...",
  "requirements": {
    "scheme": "exact",
    "network": "eip155:84532",
    "amount": "1000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "payTo": "0x...",
    "maxTimeoutSeconds": 300,
    "extra": {
      "name": "USDC",
      "version": "2",
      "resourceUrl": "http://localhost:4021/weather"
    }
  }
}

Payment Flow

The custom implementation demonstrates each step of the x402 payment flow:

  1. Request Arrives — Middleware intercepts all requests
  2. Route Check — Determine if route requires payment
  3. Payment Check — Look for PAYMENT-SIGNATURE or X-PAYMENT header
  4. Decision Point:
    • No Payment: Return 402 with requirements in PAYMENT-REQUIRED header
    • Payment Provided: Verify with facilitator
  5. Verification — Check payment signature and validity
  6. Handler Execution — Run protected endpoint handler
  7. Settlement — Settle payment on-chain (for 2xx responses)
  8. Response — Add settlement details in PAYMENT-RESPONSE header

Key Implementation Details

Defining Payment Requirements

from dataclasses import dataclass
from x402.schemas import Network

@dataclass
class RoutePaymentConfig:
    scheme: str
    price: str
    network: Network
    pay_to: str
    description: str
    mime_type: str

route_configs: dict[str, RoutePaymentConfig] = {
    "GET /weather": RoutePaymentConfig(
        scheme="exact",
        price="$0.001",
        network="eip155:84532",
        pay_to=evm_address,
        description="Weather data",
        mime_type="application/json",
    ),
}

Checking for Payment

payment_header = request.headers.get("payment-signature") or request.headers.get("x-payment")

if not payment_header:
    payment_required = resource_server.create_payment_required_response(
        [requirements],
        resource={
            "url": str(request.url),
            "description": route_config.description,
            "mime_type": route_config.mime_type,
        },
    )
    requirements_header = base64.b64encode(
        json.dumps(payment_required.model_dump(by_alias=True)).encode()
    ).decode()

    return JSONResponse(
        status_code=402,
        content={"error": "Payment Required", "message": "This endpoint requires payment"},
        headers={"PAYMENT-REQUIRED": requirements_header},
    )

Verifying Payment

payment_payload_dict = json.loads(base64.b64decode(payment_header).decode("utf-8"))
payment_payload = PaymentPayload.model_validate(payment_payload_dict)
verify_result = await resource_server.verify_payment(payment_payload, requirements)

if not verify_result.is_valid:
    return JSONResponse(
        status_code=402,
        content={"error": "Invalid Payment", "reason": verify_result.invalid_reason},
    )

Settling Payment

settle_result = await resource_server.settle_payment(payment_payload, requirements)
settlement_header = base64.b64encode(
    json.dumps(settle_result.model_dump(by_alias=True)).encode()
).decode()
response.headers["PAYMENT-RESPONSE"] = settlement_header

Middleware vs Custom Comparison

Aspect With Middleware (PaymentMiddlewareASGI) Custom Implementation
Code Complexity ~10 lines ~150 lines
Automatic Verification ✅ Yes ❌ Manual
Automatic Settlement ✅ Yes ❌ Manual
Header Management ✅ Automatic ❌ Manual
Flexibility Limited ✅ Complete control
Error Handling ✅ Built-in ❌ You implement
Maintenance x402 team You maintain

When to Use Each Approach

Use Middleware (PaymentMiddlewareASGI, flask_payment_middleware) when:

  • Building standard applications
  • Want quick integration
  • Prefer automatic payment handling
  • Using supported frameworks (FastAPI, Flask)

Use Custom Implementation when:

  • Using unsupported frameworks (Starlette, Django, etc.)
  • Need complete control over flow
  • Require custom error handling
  • Want to understand internals
  • Building custom abstractions

Adapting to Other Frameworks

To use this pattern with other frameworks:

  1. Create middleware function for your framework
  2. Check for payment requirements per route
  3. Use x402ResourceServer to verify/settle payments
  4. Intercept responses to add settlement headers

The pattern in main.py can be adapted to any Python ASGI/WSGI web framework.