tempo-x402-node 1.5.1

tempo-x402 implements HTTP 402 Payment Required for the Tempo blockchain. Clients sign EIP-712 payment authorizations, servers gate content behind 402 responses, and a facilitator settles payments on-chain via transferFrom — all in a single request/response cycle.

The facilitator holds no user funds. It only has token approval to call transferFrom on behalf of clients who have explicitly approved it.

How it works

Client                     Server                    Facilitator               Chain
  |                          |                            |                      |
  |  GET /resource           |                            |                      |
  |------------------------->|                            |                      |
  |                          |                            |                      |
  |  402 + price/token/to    |                            |                      |
  |<-------------------------|                            |                      |
  |                          |                            |                      |
  |  [sign EIP-712]          |                            |                      |
  |                          |                            |                      |
  |  GET /resource           |                            |                      |
  |  + PAYMENT-SIGNATURE     |                            |                      |
  |------------------------->|                            |                      |
  |                          |  POST /verify-and-settle   |                      |
  |                          |--------------------------->|                      |
  |                          |                            |  transferFrom()      |
  |                          |                            |--------------------->|
  |                          |                            |              tx hash |
  |                          |                            |<---------------------|
  |                          |         settlement result  |                      |
  |                          |<---------------------------|                      |
  |                          |                            |                      |
  |  200 + content + tx hash |                            |                      |
  |<-------------------------|                            |                      |

1. Client requests a protected endpoint
2. Server responds 402 with PaymentRequirements (price, token, recipient)
3. Client signs an EIP-712 PaymentAuthorization, retries with PAYMENT-SIGNATURE header
4. Server forwards to facilitator's /verify-and-settle
5. Facilitator atomically verifies signature, checks balance/allowance/nonce, calls transferFrom
6. Server returns the content + settlement transaction hash

Quick start

Install

cargo add tempo-x402   # core: types, traits, signing, client SDK, WASM wallet

Make a paid request

use alloy::signers::local::PrivateKeySigner;
use x402::client::{TempoSchemeClient, X402Client};

#[tokio::main]
async fn main() {
    let signer: PrivateKeySigner = "0xYOUR_PRIVATE_KEY".parse().unwrap();
    let client = X402Client::new(TempoSchemeClient::new(signer));

    let (response, settlement) = client
        .fetch("https://x402-gateway.example.com/g/my-api/data", reqwest::Method::GET)
        .await
        .unwrap();

    println!("{}", response.text().await.unwrap());
    if let Some(s) = settlement {
        println!("tx: {}", s.transaction.unwrap_or_default());
    }
}

Monetize any API via the gateway

No code changes to the upstream API — the gateway proxies requests and handles payment.

# Register an endpoint (pays a small platform fee)
curl -X POST https://x402-gateway.example.com/register \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-payment>" \
  -d '{"slug": "my-api", "target_url": "https://api.example.com", "price": "$0.05"}'

# Clients call through the gateway
curl https://x402-gateway.example.com/g/my-api/users/123 \
  -H "PAYMENT-SIGNATURE: <base64-payment>"

Target APIs receive verification headers: X-X402-Verified, X-X402-Payer, X-X402-Amount, X-X402-TxHash.

Architecture

crates/
├── tempo-x402/                # Core: types, EIP-712, TIP-20, nonce store, HMAC, wallet, client SDK
├── tempo-x402-gateway/        # API gateway + embedded facilitator + payment middleware
├── tempo-x402-identity/       # Agent identity: wallet gen, persistence, faucet, ERC-8004 on-chain
├── tempo-x402-soul/           # Autonomous cognition: plan-driven execution, neuroplastic memory
├── tempo-x402-node/           # Self-deploying node: gateway + identity + clone orchestration + soul
├── tempo-x402-app/            # Leptos WASM dashboard (not published)
└── tempo-x402-security-audit/ # Security invariant tests enforced on every build (not published)

Feature flags

tempo-x402 (core):

• full (default) — all features including async runtime, SQLite, HTTP client
• wasm — WASM-compatible subset: types, EIP-712 signing, wallet (no tokio/rusqlite)
• demo — includes demo private key for testing

tempo-x402-identity:

• erc8004 (default) — on-chain agent identity (ERC-8004 contracts, reputation, validation)

tempo-x402-node:

• soul (default) — autonomous thinking loop
• agent (default) — Railway clone orchestration
• erc8004 — on-chain agent identity features

Gateway API

The gateway lets you monetize any HTTP API without modifying its source code.

Self-Deploying Nodes

Nodes are autonomous agents that:

• Bootstrap identity — generate wallet, fund via faucet, register with parent
• Run a gateway — serve endpoints, process payments, proxy APIs
• Think autonomously — plan-driven execution loop powered by Gemini, with neuroplastic memory
• Create services — introspective endpoints that expose the node's own capabilities
• Clone themselves — spawn copies on Railway infrastructure
• Communicate with peers — discover siblings, inspect their endpoint catalogs, call paid services

The soul's cognition includes:

• Plan-driven execution — goals decompose into deterministic step sequences
• Neuroplastic memory — salience scoring, tiered decay, prediction error learning
• World model — structured beliefs about self, endpoints, codebase, strategy
• Agent-to-agent economy — peer discovery, endpoint catalog exchange, paid cross-agent calls
• Coding agent — read, write, edit files, run shell commands, git commit, push
• Script endpoints — create instant bash-based HTTP endpoints (no compilation)
• ERC-8004 identity — on-chain agent NFTs, reputation, validation

Network

Prerequisites

Before making payments:

# 1. Fund your wallet with testnet pathUSD
cast rpc tempo_fundAddress 0xYOUR_ADDRESS --rpc-url https://rpc.moderato.tempo.xyz

# 2. Approve the facilitator to spend your tokens
cargo run --bin x402-approve

Or programmatically:

use x402::tip20;
tip20::approve(&provider, token, facilitator_address, amount).await?;

Environment variables

Security

The tempo-x402-security-audit crate runs invariant tests on every build that scan all production source code for:

• No hardcoded private keys in production code
• HMAC verification reaches constant-time comparison on all paths (via subtle crate)
• All reqwest HTTP clients disable redirects (SSRF protection)
• Webhook URLs require HTTPS with private IP blocking
• HTTP error responses never leak internal details
• SQLite nonce store is mandatory in production
• Parameterized SQL queries only (no string formatting)
• HMAC shared secret is mandatory (not Option)
• Private keys never appear in tracing/logging macros

Additional hardening:

• EIP-2 high-s rejection prevents signature malleability
• Per-payer mutex locks prevent TOCTOU races during settlement
• Nonces claimed before transferFrom, never released on failure
• Integer-only arithmetic for all token amounts (never f64)
• SSRF protection on proxy and webhooks: HTTPS-only, private IP blocking, DNS resolution validation, CRLF rejection
• Atomic slug reservation with BEGIN IMMEDIATE to prevent race conditions

Deployed services

Health check: GET /health on any service.

Development

cargo build --workspace            # build everything
cargo test --workspace             # run all tests (including security audit)
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check

OpenAPI 3.1 specs are available in the openapi/ directory.

License

MIT