206 lines
7.6 KiB
Python
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())
|