* feat(python): add payment-identifier extension types and constants - Add PaymentIdentifierInfo and PaymentIdentifierExtension Pydantic models - Add constants: PAYMENT_IDENTIFIER, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_PATTERN - Define PaymentIdentifierSchema type alias * feat(python): add payment-identifier utility functions - Add generate_payment_id() to create UUID v4-based payment IDs - Add is_valid_payment_id() to validate ID format (16-128 chars, alphanumeric + hyphens/underscores) * feat(python): add payment-identifier JSON Schema definition - Add payment_identifier_schema compliant with JSON Schema Draft 2020-12 - Schema validates required boolean and optional id string field * feat(python): add payment-identifier validation and extraction functions - Add ValidationResult dataclass for validation results - Add is_payment_identifier_extension() type guard - Add validate_payment_identifier() for full extension validation - Add extract_payment_identifier() to extract ID from PaymentPayload - Add extract_and_validate_payment_identifier() combined function - Add has_payment_identifier() to check extension presence - Add is_payment_identifier_required() to check requirement flag - Add validate_payment_identifier_requirement() for requirement compliance * feat(python): add payment-identifier client utilities - Add append_payment_identifier_to_extensions() to append payment ID to extensions dict - Only appends if server declared the extension - Generates new ID if not provided * feat(python): add payment-identifier resource server utilities - Add declare_payment_identifier_extension() to create extension declaration - Add PaymentIdentifierResourceServerExtension class implementing ResourceServerExtension protocol - Add payment_identifier_resource_server_extension singleton instance * feat(python): add payment-identifier extension main module - Export all public APIs from payment-identifier extension - Add comprehensive usage documentation with examples for servers, clients, and idempotency * feat(python): export payment-identifier extension from extensions module - Add payment-identifier imports and exports to main extensions __init__.py - Export all constants, types, functions, and classes for public API * fix(python): resolve ValidationResult type mismatch in extensions module - Export payment_identifier.ValidationResult as ValidationResult (matches payment_identifier function return types) - Export bazaar.ValidationResult as BazaarValidationResult for explicit bazaar usage - Both ValidationResult classes are structurally equivalent (same dataclass fields) - Fixes type mismatch where payment_identifier functions returned payment_identifier.ValidationResult but ValidationResult imported from x402.extensions was bazaar.ValidationResult * refactor(python): rename payment_identifier ValidationResult to PaymentIdentifierValidationResult - Rename ValidationResult class to PaymentIdentifierValidationResult in payment_identifier/validation.py - Update all function return types and usages throughout validation.py - Update exports in payment_identifier/__init__.py - Update imports/exports in extensions/__init__.py - Keep ValidationResult from bazaar as default export for backward compatibility - Export PaymentIdentifierValidationResult separately for explicit payment_identifier usage - Makes naming consistent with BazaarValidationResult pattern * test(python): add comprehensive test suite for payment_identifier extension - Add test_types.py: Test constants and Pydantic models - Add test_utils.py: Test ID generation and validation functions - Add test_validation.py: Test all validation and extraction functions - Add test_client.py: Test client-side utilities - Add test_server.py: Test server-side utilities - Tests cover all major functionality including edge cases and error handling - Follows same structure as bazaar extension tests * fix(python): fix payment_identifier test helper and assertions - Fix create_extension_with_id helper to handle invalid IDs for testing - Update test assertion to check for 'identifier' in error message - All 67 tests now passing * fix(python): add ValidationResult alias for backward compatibility - Add ValidationResult = BazaarValidationResult alias after bazaar import - Fixes AttributeError when importing ValidationResult from x402.extensions - ValidationResult was imported as BazaarValidationResult but exported in __all__ - Now both ValidationResult and BazaarValidationResult are available * test(python): add test to verify __all__ exports are importable - Add test_exports.py to verify all items in __all__ can be imported - Tests that ValidationResult alias works correctly - Tests that 'import *' works as expected - This would have caught the ValidationResult AttributeError bug * fix(python): make jsonschema import lazy in payment_identifier validation - Remove module-level jsonschema import that raised ImportError - Import jsonschema lazily only when schema validation is needed - Return validation error instead of raising ImportError at module level - Allows payment_identifier extension to be imported without jsonschema - Users can still use non-validation functions without optional dependency * fix(python): fix linting errors - Remove unused variable in test_types.py - Fix import sorting in extensions/__init__.py - Add noqa comment for intentional E402 (import after alias) * Lint * docs(python): add payment-identifier extension examples Add client and server examples demonstrating how to use the payment-identifier extension for idempotent payment processing. Client example shows: - Generating payment IDs with generate_payment_id() - Using on_before_payment_creation hook to inject the ID - Making duplicate requests to demonstrate cache behavior Server example shows: - Declaring extension support with declare_payment_identifier_extension() - Extracting payment IDs with extract_payment_identifier() - Caching responses after settlement for idempotency * Lint * Format * Changelog
3.9 KiB
3.9 KiB
Payment-Identifier Extension Client Example
Example client demonstrating how to use the payment-identifier extension to enable idempotency when making payments.
How It Works
- Client generates a unique payment ID using
generate_payment_id() - Client includes the payment ID in the
PaymentPayloadusingappend_payment_identifier_to_extensions() - Server caches responses keyed by payment ID
- Retry requests with the same payment ID return cached responses without re-processing payment
from x402 import x402Client
from x402.extensions.payment_identifier import (
append_payment_identifier_to_extensions,
generate_payment_id,
)
from x402.http.clients import x402HttpxClient
client = x402Client()
# ... register schemes ...
# Generate a unique payment ID for this logical request
payment_id = generate_payment_id()
# Hook into payment flow to add the payment ID before payload creation
async def before_payment_creation(context):
extensions = context.payment_required.extensions
if extensions is not None:
append_payment_identifier_to_extensions(extensions, payment_id)
client.on_before_payment_creation(before_payment_creation)
async with x402HttpxClient(client) as http:
# First request - payment is processed
response1 = await http.get(url)
# Retry with same payment ID - cached response returned (no payment)
response2 = await http.get(url)
Prerequisites
- Python 3.10+
- uv (install via docs.astral.sh/uv)
- A running payment-identifier server (see payment-identifier server example)
- Valid EVM private key for making payments (Base Sepolia with USDC)
Setup
- Install dependencies:
uv sync
- Copy
.env-localto.envand add your private key:
cp .env-local .env
Required environment variable:
EVM_PRIVATE_KEY- Ethereum private key for EVM payments
- Start the payment-identifier server (in another terminal):
cd ../../servers/payment-identifier
uv run python main.py
- Run the client:
uv run python main.py
Expected Output
Generated Payment ID: pay_7d5d747be160e280504c099d984bcfe0
====================================================
First Request (with payment ID: pay_7d5d747be160e280504c099d984bcfe0)
====================================================
Making request to: http://localhost:4022/weather
Response (1523ms): {"report": {"weather": "sunny", "temperature": 70, "cached": false}}
Payment settled on eip155:84532
====================================================
Second Request (SAME payment ID: pay_7d5d747be160e280504c099d984bcfe0)
====================================================
Making request to: http://localhost:4022/weather
Expected: Server returns cached response without payment processing
Response (45ms): {"report": {"weather": "sunny", "temperature": 70, "cached": true}}
No payment processed - response served from cache!
====================================================
Summary
====================================================
Payment ID: pay_7d5d747be160e280504c099d984bcfe0
First request: 1523ms (payment processed)
Second request: 45ms (cached)
Cached response was 97% faster!
Use Cases
- Network failures: Safely retry failed requests without duplicate payments
- Client crashes: Resume requests after restart using persisted payment IDs
- Load balancing: Same request can hit different servers with shared cache
- Testing: Replay requests during development without spending funds
Best Practices
- Generate payment IDs at the logical request level, not per retry
- Persist payment IDs for long-running operations so they survive restarts
- Use descriptive prefixes (e.g.,
order_,sub_) to identify payment types - Don't reuse payment IDs across different logical requests