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

206 lines
7.6 KiB
Python

"""
Custom x402 Client Implementation (v2 Protocol)
This example demonstrates how to implement x402 payment handling manually
using only the core packages, without the convenience wrappers like x402HttpxClient.
x402 v2 Protocol Headers:
- PAYMENT-REQUIRED: Server -> Client (402 response)
- PAYMENT-SIGNATURE: Client -> Server (retry with payment)
- PAYMENT-RESPONSE: Server -> Client (settlement confirmation)
This gives you complete control over every step of the payment flow,
useful for integrating with non-standard HTTP libraries or implementing
specialized retry logic.
"""
import asyncio
import os
import sys
import httpx
from dotenv import load_dotenv
from eth_account import Account
from x402 import x402Client
from x402.http.constants import (
HTTP_STATUS_PAYMENT_REQUIRED,
PAYMENT_REQUIRED_HEADER,
PAYMENT_RESPONSE_HEADER,
PAYMENT_SIGNATURE_HEADER,
)
from x402.http.utils import (
decode_payment_required_header,
decode_payment_response_header,
encode_payment_signature_header,
)
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client
from x402.mechanisms.svm import KeypairSigner
from x402.mechanisms.svm.exact.register import register_exact_svm_client
from x402.schemas import PaymentRequired
load_dotenv()
def validate_environment() -> tuple[str | None, str | None, str, str]:
"""Validate required environment variables.
Returns:
Tuple of (evm_private_key, svm_private_key, base_url, endpoint_path).
Raises:
SystemExit: If required environment variables are missing.
"""
evm_private_key = os.getenv("EVM_PRIVATE_KEY")
svm_private_key = os.getenv("SVM_PRIVATE_KEY")
base_url = os.getenv("RESOURCE_SERVER_URL")
endpoint_path = os.getenv("ENDPOINT_PATH")
missing = []
if not evm_private_key and not svm_private_key:
missing.append("EVM_PRIVATE_KEY or SVM_PRIVATE_KEY")
if not base_url:
missing.append("RESOURCE_SERVER_URL")
if not endpoint_path:
missing.append("ENDPOINT_PATH")
if missing:
print(f"Error: Missing required environment variables: {', '.join(missing)}")
print("Please copy .env-local to .env and fill in the values.")
sys.exit(1)
return evm_private_key, svm_private_key, base_url, endpoint_path
async def make_request_with_payment(client: x402Client, url: str) -> None:
"""
Makes a request with manual x402 payment handling.
This function demonstrates the complete payment flow:
1. Make initial request
2. Handle 402 Payment Required response
3. Decode payment requirements from header
4. Create signed payment payload
5. Retry request with payment signature
6. Handle success and settlement confirmation
Args:
client: The x402 client instance configured with payment schemes.
url: The URL to request.
"""
print(f"\n Making initial request to: {url}\n")
async with httpx.AsyncClient(timeout=30.0) as http:
# Step 1: Make initial request (no payment)
response = await http.get(url)
print(f" Initial response status: {response.status_code}\n")
# Step 2: Handle 402 Payment Required
if response.status_code == HTTP_STATUS_PAYMENT_REQUIRED:
print(" Payment required! Processing...\n")
# Step 3: Decode payment requirements from PAYMENT-REQUIRED header
payment_required_header = response.headers.get(PAYMENT_REQUIRED_HEADER)
if not payment_required_header:
raise ValueError(f"Missing {PAYMENT_REQUIRED_HEADER} header")
payment_required: PaymentRequired = decode_payment_required_header(
payment_required_header
)
# Display available payment options
accepts = payment_required.accepts
requirements = accepts if isinstance(accepts, list) else [accepts]
print(" Payment requirements:")
for i, req in enumerate(requirements, 1):
print(f" {i}. {req.network} / {req.scheme} - {req.amount}")
# Step 4: Create signed payment payload
# The client will select the appropriate scheme based on registration
print("\n Creating payment...\n")
payment_payload = await client.create_payment_payload(payment_required)
# Step 5: Encode payment and retry with PAYMENT-SIGNATURE header
payment_header = encode_payment_signature_header(payment_payload)
print(" Retrying with payment...\n")
response = await http.get(
url,
headers={PAYMENT_SIGNATURE_HEADER: payment_header},
)
print(f" Response status: {response.status_code}\n")
# Step 6: Handle response
if response.status_code == 200:
print(" Success!\n")
print(f"Response: {response.json()}")
# Decode settlement confirmation from PAYMENT-RESPONSE header
settlement_header = response.headers.get(PAYMENT_RESPONSE_HEADER)
if settlement_header:
settlement = decode_payment_response_header(settlement_header)
print("\n Settlement:")
print(f" Transaction: {settlement.transaction}")
print(f" Network: {settlement.network}")
print(f" Payer: {settlement.payer}")
elif response.status_code == HTTP_STATUS_PAYMENT_REQUIRED:
# Payment was rejected (e.g., insufficient balance, invalid signature)
print(" Payment rejected!\n")
payment_response_header = response.headers.get(PAYMENT_RESPONSE_HEADER)
if payment_response_header:
payment_response = decode_payment_response_header(
payment_response_header
)
print(f" Error: {payment_response.error_reason}")
else:
print(" No error details available in response headers.")
print(f" Response body: {response.text}")
else:
raise RuntimeError(f"Unexpected status: {response.status_code}")
async def main() -> None:
"""Main entry point demonstrating custom x402 client usage."""
print("\n Custom x402 Client (v2 Protocol)\n")
# Validate environment variables
evm_private_key, svm_private_key, base_url, endpoint_path = validate_environment()
# Create x402 client
# You can optionally provide a custom selector function to choose
# between payment options when multiple are available:
#
# def select_payment(version: int, requirements: list) -> PaymentRequirements:
# # Custom logic to select preferred payment option
# return requirements[0] # Default: use first option
#
# client = x402Client(selector=select_payment)
#
client = x402Client()
# Register EVM payment scheme if private key provided
if evm_private_key:
account = Account.from_key(evm_private_key)
register_exact_evm_client(client, EthAccountSigner(account))
print(f" Initialized EVM account: {account.address}")
# Register SVM payment scheme if private key provided
if svm_private_key:
svm_signer = KeypairSigner.from_base58(svm_private_key)
register_exact_svm_client(client, svm_signer)
print(f" Initialized SVM account: {svm_signer.address}")
print(" Client ready\n")
# Build full URL and make request
url = f"{base_url}{endpoint_path}"
await make_request_with_payment(client, url)
print("\n Done!")
if __name__ == "__main__":
asyncio.run(main())