* 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>
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
- Copy
.env-localto.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")
- Install dependencies:
uv sync
- 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:
- Make an initial request to get payment requirements
- Process the payment requirements
- 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:
- Request Arrives — Middleware intercepts all requests
- Route Check — Determine if route requires payment
- Payment Check — Look for
PAYMENT-SIGNATUREorX-PAYMENTheader - Decision Point:
- No Payment: Return 402 with requirements in
PAYMENT-REQUIREDheader - Payment Provided: Verify with facilitator
- No Payment: Return 402 with requirements in
- Verification — Check payment signature and validity
- Handler Execution — Run protected endpoint handler
- Settlement — Settle payment on-chain (for 2xx responses)
- Response — Add settlement details in
PAYMENT-RESPONSEheader
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:
- Create middleware function for your framework
- Check for payment requirements per route
- Use
x402ResourceServerto verify/settle payments - Intercept responses to add settlement headers
The pattern in main.py can be adapted to any Python ASGI/WSGI web framework.