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//! verifies the payment, executes the request, and settles valid payments after successful
5//! execution. If the handler returns an error (4xx/5xx), settlement is skipped.
6//!
7//! Returns a `402 Payment Required` response if the request lacks a valid payment.
8//!
9//! See [`X402Middleware`] for full configuration options.
10//! For low-level interaction with the facilitator, see [`facilitator::FacilitatorClient`].
11//!
12//! ## Configuration Notes
13//!
14//! - **[`X402Middleware::with_price_tag`]** sets the assets and amounts accepted for payment (static pricing).
15//! - **[`X402Middleware::with_dynamic_price`]** sets a callback for dynamic pricing based on request context.
16//! - **[`X402Middleware::with_base_url`]** sets the base URL for computing full resource URLs.
17//!   If not set, defaults to `http://localhost/` (avoid in production).
18//! - **[`X402Middleware::with_supported_cache_ttl`]** configures the TTL for caching facilitator capabilities.
19//! - **[`X402Middleware::with_facilitator_timeout`]** sets a per-request timeout for facilitator HTTP calls.
20//! - **[`X402LayerBuilder::with_description`]** is optional but helps the payer understand what is being paid for.
21//! - **[`X402LayerBuilder::with_mime_type`]** sets the MIME type of the protected resource (default: `application/json`).
22//! - **[`X402LayerBuilder::with_resource`]** explicitly sets the full URI of the protected resource.
23
24pub mod facilitator;
25pub mod layer;
26pub mod paygate;
27pub mod pricing;
28
29pub use layer::{X402LayerBuilder, X402Middleware};
30pub use paygate::{
31    PAYMENT_HEADER_NAME, Paygate, PaygateBuilder, ResourceInfoBuilder, VerifiedPayment,
32    error_into_response, extract_payment_header, extract_payment_payload, make_verify_request,
33    settlement_to_header, validate_verify_response,
34};
35pub use pricing::{DynamicPriceTags, PriceTagSource, StaticPriceTags};
36
37/// Common verification errors shared between protocol versions.
38#[derive(Debug, thiserror::Error)]
39pub enum VerificationError {
40    /// Required payment header is missing.
41    #[error("{0} header is required")]
42    PaymentHeaderRequired(&'static str),
43    /// Payment header is present but malformed.
44    #[error("Invalid or malformed payment header")]
45    InvalidPaymentHeader,
46    /// No matching payment requirements found.
47    #[error("Unable to find matching payment requirements")]
48    NoPaymentMatching,
49    /// Verification with facilitator failed.
50    #[error("Verification failed: {0}")]
51    VerificationFailed(String),
52}
53
54/// Paygate error type that wraps verification and settlement errors.
55#[derive(Debug, thiserror::Error)]
56pub enum PaygateError {
57    /// Payment verification failed.
58    #[error(transparent)]
59    Verification(#[from] VerificationError),
60    /// On-chain settlement failed.
61    #[error("Settlement failed: {0}")]
62    Settlement(String),
63}
r402_http/server/mod.rs

r402_http/server/
mod.rs
