X402 Paywall

A framework-agnostic HTTP paywall implementation for the X402 payment protocol.

This crate provides [paywall::PayWall], a composable middleware that protects HTTP resources with X402 payments. It handles the complete payment lifecycle including verification and settlement through a configured facilitator.

Modules

• [paywall]: The main PayWall struct and payment flow logic.
• [processor]: Payment processing types including RequestProcessor and PaymentState.
• [errors]: Error types for payment failures and HTTP error responses.

Payment Flow

The standard payment flow using PayWall::handle_payment:

1. Update Accepts: Filter payment requirements based on facilitator support.
2. Process Request: Extract and validate the PAYMENT-SIGNATURE header.
3. Verify: Verify the payment signature with the facilitator.
4. Run Handler: Execute the resource handler.
5. Settle: Settle the payment on successful response.

For custom flows, use the step-by-step API directly. See PayWall for details.

Framework Integration

While framework-agnostic, x402-paywall works seamlessly with any HTTP framework. See the x402-kit documentation for complete usage examples with Axum and other frameworks.

Error Handling

ErrorResponse implements IntoResponse for Axum and can be easily adapted to other frameworks. It returns appropriate HTTP status codes:

• 402 Payment Required: No payment signature provided.
• 400 Bad Request: Invalid payment payload or unsupported requirements.
• 500 Internal Server Error: Facilitator communication failures.