r402_http/server/
mod.rs

1//! Axum middleware for enforcing [x402](https://www.x402.org) payments on protected routes (V2-only).
2//!
3//! This middleware validates incoming payment headers using a configured x402 facilitator,
4//! and settles valid payments either before or after request execution (configurable).
5//!
6//! Returns a `402 Payment Required` response if the request lacks a valid payment.
7//!
8//! See [`X402Middleware`] for full configuration options.
9//! For low-level interaction with the facilitator, see [`facilitator::FacilitatorClient`].
10//!
11//! ## Settlement Timing
12//!
13//! By default, settlement occurs **after** the request is processed. You can change this behavior:
14//!
15//! - **[`X402Middleware::settle_before_execution`]** - Settle payment **before** request execution.
16//!   This prevents issues where failed settlements need retry or authorization expires.
17//! - **[`X402Middleware::settle_after_execution`]** - Settle payment **after** request execution (default).
18//!   This allows processing the request before committing the payment on-chain.
19//!
20//! ## Configuration Notes
21//!
22//! - **[`X402Middleware::with_price_tag`]** sets the assets and amounts accepted for payment (static pricing).
23//! - **[`X402Middleware::with_dynamic_price`]** sets a callback for dynamic pricing based on request context.
24//! - **[`X402Middleware::with_base_url`]** sets the base URL for computing full resource URLs.
25//!   If not set, defaults to `http://localhost/` (avoid in production).
26//! - **[`X402Middleware::with_supported_cache_ttl`]** configures the TTL for caching facilitator capabilities.
27//! - **[`X402LayerBuilder::with_description`]** is optional but helps the payer understand what is being paid for.
28//! - **[`X402LayerBuilder::with_mime_type`]** sets the MIME type of the protected resource (default: `application/json`).
29//! - **[`X402LayerBuilder::with_resource`]** explicitly sets the full URI of the protected resource.
30
31pub mod facilitator;
32pub mod layer;
33pub mod paygate;
34pub mod pricing;
35
36pub use layer::{X402LayerBuilder, X402Middleware};
37pub use pricing::{DynamicPriceTags, PriceTagSource, StaticPriceTags};
38
39/// Common verification errors shared between protocol versions.
40#[derive(Debug, thiserror::Error)]
41pub enum VerificationError {
42    /// Required payment header is missing.
43    #[error("{0} header is required")]
44    PaymentHeaderRequired(&'static str),
45    /// Payment header is present but malformed.
46    #[error("Invalid or malformed payment header")]
47    InvalidPaymentHeader,
48    /// No matching payment requirements found.
49    #[error("Unable to find matching payment requirements")]
50    NoPaymentMatching,
51    /// Verification with facilitator failed.
52    #[error("Verification failed: {0}")]
53    VerificationFailed(String),
54}
55
56/// Paygate error type that wraps verification and settlement errors.
57#[derive(Debug, thiserror::Error)]
58pub enum PaygateError {
59    /// Payment verification failed.
60    #[error(transparent)]
61    Verification(#[from] VerificationError),
62    /// On-chain settlement failed.
63    #[error("Settlement failed: {0}")]
64    Settlement(String),
65}
r402_http/server/mod.rs

r402_http/server/
mod.rs
