feat(middleware): support dynamic payment requirements via async hooks

[shuhei0866]

feat(middleware): Support Dynamic Payment Requirements via Hooks

1. Problem Statement

The current require_payment middleware in the x402 Python SDK only accepts static values for parameters like price, description, and resource. While this works for simple fixed-price APIs, it limits developers in more complex scenarios:

• Dynamic Content (CMS-like): Serving thousands of resources via a single route (e.g., /contents/{id}) where each resource has a unique price and metadata.
• Adaptive Pricing: Calculating prices at runtime based on demand, user history, or resource length (e.g., character count).

Currently, developers are forced to bypass the middleware and manually construct 402 responses, which increases implementation errors and reduces the value of the SDK.

2. Proposed Solution: Dynamic Hooks

Extend the middleware parameters to accept Async Callables (Hooks). These hooks are executed at request time, allowing the middleware to generate PaymentRequirements on-the-fly using the request context.

Architecture

sequenceDiagram
    participant Client as Client
    participant MW as x402 Middleware
    participant Hook as Dynamic Hook (User Logic)
    
    Client->>MW: Request (GET /contents/123)
    Note over MW, Hook: Lazy Evaluation at Runtime
    MW->>Hook: execute(request)
    Hook-->>MW: price, description, etc.
    MW->>MW: Generate PaymentRequirements
    MW-->>Client: 402 Payment Required (Dynamic Info)

Loading

Key Technical Changes

• Type Flexibility: Updated parameters to accept Union[T, Callable[[Request], Awaitable[T]]].
• Lazy Evaluation: Moved value resolution inside the middleware function to ensure it has access to the Request object.
• Implementation Note: Hooks receive the raw Request. As FastAPI middleware runs before route matching, specific identifiers (like IDs) should be parsed from request.url.path.
• Backward Compatibility: Existing static definitions (e.g., price=0.10) continue to work seamlessly.

3. Testing Performed

• ✅ Static Backward Compatibility: Verified that fixed-price definitions still work as expected.
• ✅ Dynamic Price Resolution: Verified that an async hook can return different prices based on the request URL.
• ✅ Dynamic Metadata: Verified that descriptions can be dynamically generated at runtime.
• ✅ Error Handling: Verified that a 500 error is returned if a hook fails, preventing invalid payment requirements.

4. Expected Impact

This change enables x402 to power sophisticated content delivery platforms and autonomous agents with fluctuating pricing strategies, making the SDK suitable for production-grade CMS and decentralized media applications.

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[vercel]

@shuhei0866 is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.