x402_rs/
lib.rs

1//! Core Rust implementation of the [x402 protocol](https://www.x402.org).
2//!
3//! This crate provides the foundational data structures, protocol types, and a reference
4//! facilitator implementation for on-chain verification and settlement of x402 payments.
5//!
6//! # Overview
7//!
8//! The x402 protocol enables HTTP-native payments using the `402 Payment Required` status code.
9//! This crate supports both EVM-compatible chains (via EIP-155) and Solana, with multiple
10//! protocol versions (V1 and V2) and payment schemes.
11//!
12//! # Roles
13//!
14//! The crate is designed for reuse across all x402 roles:
15//!
16//! - **Facilitator**: A server that verifies and settles x402 payments on-chain.
17//!   See [`facilitator`] for the trait definition and [`facilitator_local`] for the
18//!   reference implementation.
19//!
20//! - **Seller**: A payment-gated service that requires payment for access to resources.
21//!   Use the [`proto`] module for protocol types and [`scheme`] for payment scheme definitions.
22//!
23//! - **Buyer/Client**: A client that constructs and submits x402-compliant payments.
24//!   See [`scheme::client`] for client-side payment handling.
25//!
26//! # Modules
27//!
28//! - [`chain`] — Blockchain-specific types and providers for EIP-155 (EVM) and Solana chains.
29//! - [`config`] — Configuration types for the facilitator server, including chain and scheme settings.
30//! - [`facilitator`] — The [`Facilitator`](facilitator::Facilitator) trait for payment verification and settlement.
31//! - [`facilitator_local`] — Reference implementation of the facilitator using on-chain verification.
32//! - [`handlers`] — HTTP endpoint handlers for the facilitator server (verify, settle, supported).
33//! - [`networks`] — Registry of well-known blockchain networks and CAIP-2 chain identifiers.
34//! - [`proto`] — Protocol types for x402 V1 and V2, including payment payloads and requirements.
35//! - [`scheme`] — Payment scheme implementations (e.g., `exact` scheme for EIP-155 and Solana).
36//! - [`timestamp`] — Unix timestamp type for payment authorization windows.
37//! - [`util`] — Utility types including base64 encoding, telemetry, and signal handling.
38//!
39//! # Feature Highlights
40//!
41//! - **Multi-chain support**: EVM chains via EIP-155 and Solana
42//! - **Protocol versions**: Both x402 V1 and V2 protocols
43//! - **Payment schemes**: Extensible scheme system with built-in `exact` scheme
44//! - **CAIP-2 identifiers**: Standard chain-agnostic blockchain identification
45//! - **OpenTelemetry**: Built-in tracing and metrics support
46//!
47//! # Example
48//!
49//! For a complete facilitator server example, see the `x402-axum-example` in the examples directory.
50//! For client-side payment handling, see the `x402-reqwest` crate.
51
52pub mod chain;
53pub mod config;
54pub mod facilitator;
55pub mod facilitator_local;
56pub mod handlers;
57pub mod networks;
58pub mod proto;
59pub mod scheme;
60pub mod timestamp;
61pub mod util;