Struct X402Middleware 

pub struct X402Middleware<F> { /* private fields */ }

Available on crate feature server only.

The main X402 middleware instance for enforcing x402 payments on routes.

Create a single instance per application and use it to build payment layers for protected routes.

Implementations

impl<F> X402Middleware<F>

pub const fn from_facilitator(facilitator: F) -> Self

Creates a middleware instance from any facilitator implementation.

Use this when you already have a configured facilitator (e.g. one with custom timeouts, caching, or a non-default HTTP client).

pub const fn facilitator(&self) -> &F

Returns a reference to the underlying facilitator.

impl X402Middleware<Arc<FacilitatorClient>>

pub fn new(url: &str) -> Self

Creates a new middleware instance with a default facilitator URL.

Panics

Panics if the facilitator URL is invalid.

pub fn try_new(url: &str) -> Result<Self, Box<dyn Error>>

Creates a new middleware instance with a facilitator URL.

Errors

Returns an error if the URL is invalid.

pub fn facilitator_url(&self) -> &Url

Returns the configured facilitator URL.

pub fn with_supported_cache_ttl(&self, ttl: Duration) -> Self

Sets the TTL for caching the facilitator’s supported response.

Default is 10 minutes. Use FacilitatorClient::without_supported_cache() to disable caching entirely.

pub fn with_facilitator_timeout(&self, timeout: Duration) -> Self

Sets a per-request timeout for all facilitator HTTP calls (verify, settle, supported).

Without this, the underlying reqwest::Client uses no timeout by default, which can cause requests to hang indefinitely if the facilitator is slow or unreachable, eventually triggering OS-level TCP timeouts (typically 2–5 minutes).

A reasonable production value is 30 seconds.

impl<F> X402Middleware<F>

where F: Clone,

pub fn with_base_url(&self, base_url: Url) -> Self

Sets the base URL used to construct resource URLs dynamically.

If X402LayerBuilder::with_resource is not called, this base URL is combined with each request’s path/query to compute the resource. If not set, defaults to http://localhost/.

In production, prefer calling with_resource or setting a precise base_url.

impl<TFacilitator> X402Middleware<TFacilitator>

where TFacilitator: Clone,

pub fn with_price_tag( &self, price_tag: PriceTag, ) -> X402LayerBuilder<StaticPriceTags, TFacilitator>

Sets the price tag for the protected route.

Creates a layer builder that can be further configured with additional price tags and resource information.

pub fn with_price_tags( &self, price_tags: Vec<PriceTag>, ) -> X402LayerBuilder<StaticPriceTags, TFacilitator>

Sets multiple price tags for the protected route.

Convenience method for services that accept several payment options (e.g. multiple tokens / networks). Returns an empty-bypass builder when the list is empty — the middleware will pass requests through without payment enforcement.

pub fn with_dynamic_price<F, Fut>( &self, callback: F, ) -> X402LayerBuilder<DynamicPriceTags, TFacilitator>

where F: Fn(&HeaderMap, &Uri, Option<&Url>) -> Fut + Send + Sync + 'static, Fut: Future<Output = Vec<PriceTag>> + Send + 'static,

Sets a dynamic price source for the protected route.

The callback receives request headers, URI, and base URL, and returns a vector of V2 price tags.

Trait Implementations

impl<F: Clone> Clone for X402Middleware<F>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<F: Debug> Debug for X402Middleware<F>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl TryFrom<&str> for X402Middleware<Arc<FacilitatorClient>>

type Error = Box<dyn Error>

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<String> for X402Middleware<Arc<FacilitatorClient>>

type Error = Box<dyn Error>

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, Self::Error>

Performs the conversion.