x402_paywall/
lib.rs

1//! # X402 Paywall
2//!
3//! A framework-agnostic HTTP paywall implementation for the X402 payment protocol.
4//!
5//! This crate provides [`paywall::PayWall`], a composable middleware that protects
6//! HTTP resources with X402 payments. It handles the complete payment lifecycle including
7//! verification and settlement through a configured facilitator.
8//!
9//! ## Modules
10//!
11//! - [`paywall`]: The main [`PayWall`](paywall::PayWall) struct and payment flow logic.
12//! - [`processor`]: Payment processing types including [`RequestProcessor`](processor::RequestProcessor)
13//!   and [`PaymentState`](processor::PaymentState).
14//! - [`errors`]: Error types for payment failures and HTTP error responses.
15//!
16//! ## Payment Flow
17//!
18//! The standard payment flow using [`PayWall::handle_payment`](paywall::PayWall::handle_payment):
19//!
20//! 1. **Update Accepts**: Filter payment requirements based on facilitator support.
21//! 2. **Process Request**: Extract and validate the `PAYMENT-SIGNATURE` header.
22//! 3. **Verify**: Verify the payment signature with the facilitator.
23//! 4. **Run Handler**: Execute the resource handler.
24//! 5. **Settle**: Settle the payment on successful response.
25//!
26//! For custom flows, use the step-by-step API directly. See [`PayWall`](paywall::PayWall) for details.
27//!
28//! ## Framework Integration
29//!
30//! While framework-agnostic, `x402-paywall` works seamlessly with any HTTP framework.
31//! See the [`x402-kit` documentation](https://docs.rs/x402-kit) for complete usage examples
32//! with Axum and other frameworks.
33//!
34//! ## Error Handling
35//!
36//! [`ErrorResponse`](errors::ErrorResponse) implements `IntoResponse` for Axum and can be
37//! easily adapted to other frameworks. It returns appropriate HTTP status codes:
38//!
39//! - `402 Payment Required`: No payment signature provided.
40//! - `400 Bad Request`: Invalid payment payload or unsupported requirements.
41//! - `500 Internal Server Error`: Facilitator communication failures.
42
43pub mod errors;
44pub mod paywall;
45pub mod processor;