* 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>
5.9 KiB
5.9 KiB
x402 Python
Python package for the x402 payments protocol.
Installation
pip install x402
Overview
The x402 package provides the core building blocks for implementing the x402 Payment Protocol in Python. It's designed to be used by:
- FastAPI middleware for accepting payments
- Flask middleware for accepting payments
- httpx client for paying resources
- requests client for paying resources
FastAPI Integration
The simplest way to add x402 payment protection to your FastAPI application:
from fastapi import FastAPI
from x402.fastapi.middleware import require_payment
app = FastAPI()
app.middleware("http")(
require_payment(price="0.01", pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C")
)
@app.get("/")
async def root():
return {"message": "Hello World"}
To protect specific routes:
app.middleware("http")(
require_payment(price="0.01",
pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C"),
path="/foo" # <-- this can also be a list ex: ["/foo", "/bar"]
)
Flask Integration
The simplest way to add x402 payment protection to your Flask application:
from flask import Flask
from x402.flask.middleware import PaymentMiddleware
app = Flask(__name__)
# Initialize payment middleware
payment_middleware = PaymentMiddleware(app)
# Add payment protection for all routes
payment_middleware.add(
price="$0.01",
pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
)
@app.route("/")
def root():
return {"message": "Hello World"}
To protect specific routes:
# Protect specific endpoint
payment_middleware.add(
path="/foo",
price="$0.001",
pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
)
Client Integration
Simple Usage
Httpx Client
from eth_account import Account
from x402.clients.httpx import x402HttpxClient
# Initialize account
account = Account.from_key("your_private_key")
# Create client and make request
async with x402HttpxClient(account=account, base_url="https://api.example.com") as client:
response = await client.get("/protected-endpoint")
print(await response.aread())
Requests Session Client
from eth_account import Account
from x402.clients.requests import x402_requests
# Initialize account
account = Account.from_key("your_private_key")
# Create session and make request
session = x402_requests(account)
response = session.get("https://api.example.com/protected-endpoint")
print(response.content)
Advanced Usage
Httpx Extensible Example
import httpx
from eth_account import Account
from x402.clients.httpx import x402_payment_hooks
# Initialize account
account = Account.from_key("your_private_key")
# Create httpx client with x402 payment hooks
async with httpx.AsyncClient(base_url="https://api.example.com") as client:
# Add payment hooks directly to client
client.event_hooks = x402_payment_hooks(account)
# Make request - payment handling is automatic
response = await client.get("/protected-endpoint")
print(await response.aread())
Requests Session Extensible Example
import requests
from eth_account import Account
from x402.clients.requests import x402_http_adapter
# Initialize account
account = Account.from_key("your_private_key")
# Create session and mount the x402 adapter
session = requests.Session()
adapter = x402_http_adapter(account)
# Mount the adapter for both HTTP and HTTPS
session.mount("http://", adapter)
session.mount("https://", adapter)
# Make request - payment handling is automatic
response = session.get("https://api.example.com/protected-endpoint")
print(response.content)
Manual Server Integration
If you're not using the FastAPI middleware, you can implement the x402 protocol manually. Here's what you'll need to handle:
- Return 402 error responses with the appropriate response body
- Use the facilitator to validate payments
- Use the facilitator to settle payments
- Return the appropriate response header to the caller
Here's an example of manual integration:
import base64
import json
from typing import Annotated
from fastapi import FastAPI, Request, Response, JSONResponse
from x402.types import PaymentRequiredResponse, PaymentRequirements, PaymentPayload
from x402.encoding import safe_base64_decode
from x402.facilitator import FacilitatorClient
payment_requirements = PaymentRequirements(...)
facilitator = FacilitatorClient(facilitator_url)
@app.get("/foo")
async def foo(request: Request, response: Response):
payment_required = PaymentRequiredResponse(
x402_version=1,
accepts=[payment_requirements],
error="",
)
payment_header = request.headers.get("X-PAYMENT", "")
if payment_header == "":
payment_required.error = "X-PAYMENT header not set"
return JSONResponse(
content=payment_required.model_dump(by_alias=True),
status_code=402,
)
payment = PaymentPayload(**json.loads(safe_base64_decode(payment_header)))
verify_response = await facilitator.verify(payment, payment_requirements)
if not verify_response.is_valid:
payment_required.error = "Invalid payment"
return JSONResponse(
content=payment_required.model_dump(by_alias=True),
status_code=402,
)
settle_response = await facilitator.settle(payment, payment_requirements)
if settle_response.success:
response.headers["X-PAYMENT-RESPONSE"] = base64.b64encode(
settle_response.model_dump_json().encode("utf-8")
).decode("utf-8")
return {"message": "Payment successful"}
else:
payment_required.error = "Settle failed: " + settle_response.error
return JSONResponse(
content=payment_required.model_dump(by_alias=True),
status_code=402,
)
For more examples and advanced usage patterns, check out our examples directory.