x402_sdk_solana_rust/
lib.rs

1//! # X402 SDK for Solana (Rust)
2//!
3//! A Rust SDK for the X402 payment protocol on Solana, enabling pay-per-use APIs 
4//! with automatic blockchain-based payment handling.
5//!
6//! ## Overview
7//!
8//! X402 is a payment protocol that allows API providers to charge users on a per-request 
9//! basis using blockchain payments. This SDK provides three main components:
10//!
11//! - **Client**: HTTP client with automatic payment handling (402 Payment Required)
12//! - **Server**: Payment-protected API server with middleware
13//! - **Facilitator**: Payment verification and settlement service
14//!
15//! ## Features
16//!
17//! - 🔐 Automatic payment handling for HTTP 402 responses
18//! - ⚡ Async/await support with Tokio
19//! - 🔗 Solana blockchain integration
20//! - 💰 Support for SOL transfers (SPL Token support planned)
21//! - 🛡️ Built-in signature verification
22//! - 📝 Comprehensive error handling
23//! - 🔧 Easy configuration via environment variables
24//!
25//! ## Quick Start
26//!
27//! ### Client Example
28//!
29//! ```rust,ignore
30//! use x402_sdk_solana_rust::{client::Fetcher, solana::Wallet, types::X402Request};
31//!
32//! #[tokio::main]
33//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
34//!     // Initialize wallet from private key
35//!     let wallet = Wallet::from_private_key("your-base58-private-key")?;
36//!     
37//!     // Create HTTP client (fetcher) with payment capabilities
38//!     let fetcher = Fetcher::with_max_value(wallet, 100000, None);
39//!     
40//!     // Create request
41//!     let request = X402Request {
42//!         method: "GET".to_string(),
43//!         url: "http://localhost:8080/api/data".to_string(),
44//!         headers: std::collections::HashMap::new(),
45//!         body: None,
46//!     };
47//!     
48//!     // Make request - will automatically handle 402 Payment Required
49//!     let response = fetcher.fetch(request).await?;
50//!     println!("Response: {:?}", response);
51//!     
52//!     Ok(())
53//! }
54//! ```
55//!
56//! ### Server Example
57//!
58//! ```rust,ignore
59//! use actix_web::{web, App, HttpServer, HttpResponse};
60//! use x402_sdk_solana_rust::server::{check_payment, PaymentMiddlewareConfig};
61//! use std::collections::HashMap;
62//!
63//! #[actix_web::main]
64//! async fn main() -> std::io::Result<()> {
65//!     // Configure payment middleware
66//!     let config = PaymentMiddlewareConfig::new(
67//!         "your-solana-public-key".to_string(),
68//!         HashMap::new(), // route configurations
69//!         None,           // facilitator config
70//!         None,           // x402 config
71//!     );
72//!     
73//!     HttpServer::new(move || {
74//!         App::new()
75//!             .route("/api/data", web::get().to(|| async {
76//!                 HttpResponse::Ok().json(serde_json::json!({"data": "value"}))
77//!             }))
78//!     })
79//!     .bind("127.0.0.1:8080")?
80//!     .run()
81//!     .await
82//! }
83//! ```
84//!
85//! ## Architecture
86//!
87//! ```text
88//! ┌─────────┐         ┌─────────┐         ┌──────────────┐
89//! │ Client  │ ──402──▶│ Server  │ ──────▶ │ Facilitator  │
90//! │         │ ◀─sig──┤         │ ◀verify─┤              │
91//! │         │         └─────────┘         │              │
92//! │         │                              │              │
93//! │         │ ──tx──▶ Solana Chain ◀─────┤              │
94//! └─────────┘                              └──────────────┘
95//! ```
96//!
97//! ## Configuration
98//!
99//! All examples support `.env` files. See the `examples/` directory for complete 
100//! configuration templates.
101//!
102//! ## Current Limitations
103//!
104//! - Currently supports SOL transfers only (not SPL Tokens/USDC)
105//! - To use USDC/SPL Tokens, modify client to call `create_token_transfer_transaction`
106//!
107//! ## Examples
108//!
109//! See the `examples/` directory for complete working examples:
110//! - `client_example.rs` - HTTP client with automatic payments
111//! - `server_example.rs` - Payment-protected API server
112//! - `facilitator_example.rs` - Payment verification service
113
114pub mod client;
115pub mod server;
116pub mod facilitator;
117pub mod solana;
118pub mod types;
119pub mod error;
120pub mod utils;
121
122// Re-export commonly used items
123pub use error::X402Error;
124pub use types::{
125    Network, PaymentPayload, PaymentRequirements, PaymentScheme, X402Config, 
126    FacilitatorConfig, RouteConfig, SvmConfig, TokenConfig,
127};
128pub use client::{Fetcher, create_payment_header};
129pub use server::{check_payment, settle_payment, PaymentMiddlewareConfig};
130pub use facilitator::Handler;
131pub use solana::{Wallet, TransactionBuilder, create_signer};
x402_sdk_solana_rust/lib.rs

x402_sdk_solana_rust/
lib.rs
