erc8004-rust-sdk

Production-ready ERC-8004 Rust SDK for identity, reputation, and validation, with optional x402 payment flows and middleware, plus optional Stripe and Coinbase adapters.

Why This Repository

• High-level Rust client for ERC-8004 identity, reputation, and validation flows
• Optional x402 stack for paid API access (402 challenge/response, verification, replay protection, policy, observability)
• Optional server middleware and provider adapters (Stripe and Coinbase)
• Multi-crate workspace with integration tests and CI-level verification commands

Quick Links

• SDK usage guide: SDK_USAGE_GUIDE.md
• Quick start: Quick Start (SDK) section below
• x402 extension: Optional x402 Payments Extension section below
• Live adapter tests: Live Sandbox Tests (Optional) section below

Workspace Crates

Compatibility Pins

• EIP: https://eips.ethereum.org/EIPS/eip-8004
• Upstream contracts/ABIs: erc-8004/erc-8004-contracts commit 29e1ccb7ae9038950f6949d6348e2d1b866ee7e3

Quick Start (SDK)

use alloy::network::EthereumWallet;
use alloy::providers::ProviderBuilder;
use alloy::signers::local::PrivateKeySigner;
use erc8004_sdk::adapters::alloy::AlloyTransport;
use erc8004_sdk::client::Erc8004Client;
use erc8004_sdk::config::{Erc8004Addresses, Erc8004Config};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let signer: PrivateKeySigner =
    "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80".parse()?;
let wallet = EthereumWallet::new(signer.clone());
let provider = ProviderBuilder::new()
    .wallet(wallet)
    .connect_http("http://127.0.0.1:8545".parse()?);

let adapter = AlloyTransport::new(provider, signer);
let addresses = Erc8004Addresses::new(
    "0x8004A818BFB912233c491871b3d84c89A494BD9e",
    "0x8004B663056A597Dffe9eCcC1965A193B7388713",
    "0x0000000000000000000000000000000000000001",
    11_155_111,
);

let config = Erc8004Config::new(adapter, addresses)
    .with_signer_address("0x1111111111111111111111111111111111111111")?;
let client = Erc8004Client::new(config);

assert_eq!(client.get_chain_id(), 11_155_111);
# Ok(())
# }

Optional x402 Payments Extension

Enable x402 in the SDK without changing baseline behavior:

erc8004-sdk = { path = "crates/erc8004-sdk", features = ["payments-x402"] }

# #[cfg(feature = "payments-x402")]
# {
use erc8004_sdk::payments::x402::{
    InMemoryPaymentEventSink, PaymentPayload, PaymentPayloadBuilder,
    PaymentRequiredChallenge, SessionSpendPolicy, X402Error, X402HttpClient,
    X402SecurityPolicy,
};
use std::sync::Arc;

struct StaticBuilder;

impl PaymentPayloadBuilder for StaticBuilder {
    fn build_payment_payload(
        &self,
        _challenge: &PaymentRequiredChallenge,
    ) -> Result<PaymentPayload, X402Error> {
        unimplemented!("attach signer/facilitator-specific payment payload")
    }
}

let policy = X402SecurityPolicy::default();
let spend_policy = SessionSpendPolicy::new()
    .with_max_total_amount(5_000_000)
    .with_max_per_payment_amount(1_000_000)
    .with_allowed_networks(["eip155:8453", "eip155:84532"]);
let events = InMemoryPaymentEventSink::default();

let _client = X402HttpClient::with_policy(reqwest::Client::new(), StaticBuilder, policy)
    .with_spend_policy(Arc::new(spend_policy))
    .with_event_sink(Arc::new(events));
# }

Default security posture includes:

• HTTPS-only target URLs
• local/private host rejection
• bounded PAYMENT-REQUIRED header size
• request timeout limits

For local development only, use explicit overrides such as X402SecurityPolicy::permissive_for_local_dev().

Server Middleware + Discovery (Optional)

Use erc8004-payments-x402-middleware to gate paid endpoints:

use std::sync::Arc;

use async_trait::async_trait;
use axum::{middleware, routing::get, Router};
use erc8004_payments_x402_middleware::{
    x402_gate_middleware, ChallengeProvider, PaidServiceDescriptor, PaymentProofVerifier,
    RequestMetadata, X402GateState,
};

# #[derive(Clone)]
# struct Challenge;
# #[derive(Clone)]
# struct Verifier;
# #[async_trait]
# impl ChallengeProvider for Challenge {
#     async fn challenge_for(
#         &self,
#         _request: &RequestMetadata,
#     ) -> Result<erc8004_payments_x402::PaymentRequiredChallenge, erc8004_payments_x402_middleware::GateError> {
#         unimplemented!()
#     }
# }
# #[async_trait]
# impl PaymentProofVerifier for Verifier {
#     async fn verify_payload(
#         &self,
#         _payload: &erc8004_payments_x402::PaymentPayload,
#     ) -> Result<erc8004_payments_x402::VerifyResponse, erc8004_payments_x402_middleware::GateError> {
#         unimplemented!()
#     }
# }

let gate_state = Arc::new(X402GateState::new(Challenge, Verifier));
let _app = Router::new()
    .route("/premium", get(|| async { "paid response" }))
    .route(
        "/.well-known/x402",
        get(erc8004_payments_x402_middleware::discovery_handler),
    )
    .with_state(Arc::new(PaidServiceDescriptor {
        service_name: "example".to_string(),
        service_version: "1.0.0".to_string(),
        resources: vec![],
    }))
    .layer(middleware::from_fn_with_state(
        gate_state,
        x402_gate_middleware::<Challenge, Verifier>,
    ));

Provider Adapter Crates (Optional)

• erc8004-payments-x402-stripe: map PaymentIntent metadata to x402 routing and verify webhook signatures before settlement handling.
• erc8004-payments-x402-coinbase: parse wallet profile payloads and derive x402 PaymentRequirements for agent wallet flows.

Live Sandbox Tests (Optional)

The Stripe and Coinbase adapter crates include ignored integration tests that call real sandbox/API endpoints.

Use sandbox credentials only:

export STRIPE_TEST_SECRET_KEY=sk_test_xxx
export STRIPE_TEST_PAY_TO=0x209693Bc6afc0C5328bA36FaF03C514EF312287C   # optional
export STRIPE_TEST_API_BASE=https://api.stripe.com                         # optional

cargo test -p erc8004-payments-x402-stripe --test live_sandbox -- --ignored

export COINBASE_TEST_WALLET_PROFILE_URL=https://...
export COINBASE_TEST_BEARER_TOKEN=...     # optional (or COINBASE_TEST_API_KEY)
export COINBASE_TEST_API_KEY=...          # optional (used if bearer token is absent)
export COINBASE_TEST_AMOUNT=1000          # optional
export COINBASE_TEST_ASSET=0x036CbD53842c5426634e7929541eC2318f3dCF7e  # optional

cargo test -p erc8004-payments-x402-coinbase --test live_sandbox -- --ignored

Example Programs

cargo run -p erc8004-sdk --example config_from_network
cargo run -p erc8004-agent-framework --example basic_bot
cargo run -p erc8004-verifiable --example auditor_agent

Verification Commands

These match CI checks on main:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test -p erc8004-sdk --no-default-features
cargo test -p erc8004-sdk --features payments-x402
cargo test -p erc8004-payments-x402
cargo test -p erc8004-sdk --doc
cargo test -p erc8004-sdk --doc --features payments-x402

Integration tests require anvil (Foundry):

cargo test -p erc8004-integration

Refresh Upstream ABIs

scripts/fetch_upstream_abis.sh

UPSTREAM_REPO and UPSTREAM_COMMIT can be overridden via environment variables.

License

MIT (LICENSE)