smol402

x402, but actually decentralized.

Trustless x402 payment protocol using pypolkadot light clients. No facilitators, no RPC providers, no middlemen.

Why?

	x402 (original)	smol402
Verification	Facilitator service	Local light client
Dependencies	Third party server uptime	None
Censorship	Facilitator can block	Unstoppable
Trust	RPC provider	Cryptographic proofs

How It Works

Client requests resource → Server returns 402 with payment address/amount
Client submits payment on-chain, waits for finalization
Client retries with X-Payment: block=0x... header
Server verifies payment via embedded light client
Server returns resource

tldr:

x402: Client → Server → Facilitator → RPC → Chain
smol402: Client → Server → Light Client ←→ Chain (P2P, trustless)

Key insight: Server only queries chain when buyer provides proof. No background listeners needed.

Installation

pip install -r requirements.txt

Or use uv, of course.

Start

python server_simple.py # (simple)
python server_cookie.py # (with persistence and session tokens for paiments)

Client Usage (simple)

# 1. Request (get 402)
curl -i http://localhost:5402/premium

# Call curl http://localhost:5402/health once to warm up light client

# 2. Make payment on Paseo Asset Hub
#    - Use polkadot.js/apps or any wallet
#    - Send to the recipient address
#    - Wait for finalization, note the block hash

# 3. Retry with proof
curl http://localhost:5402/premium \
  -H "X-Payment: block=0xYOUR_BLOCK_HASH"

Client Usage (cookie)

# 1. Request (get 402 + session cookie)
curl -i -c cookies.txt http://localhost:5402/premium

# Call curl http://localhost:5402/health once to warm up light client

# 2. Make payment on Paseo Asset Hub
#    - Use polkadot.js/apps or any wallet
#    - Send to the recipient address
#    - Wait for finalization, note the block hash

# 3. Retry with proof + cookie
curl -i -b cookies.txt http://localhost:5402/premium \
    -H "X-Payment: block=0xYOUR_BLOCK_HASH"

Supported Networks

Paseo Asset Hub - testnet (network="paseo")
Polkadot Asset Hub - mainnet (network="polkadot")
Kusama Asset Hub - canary (network="kusama")

Features

Trustless verification via light client
SS58 and hex address support
Replay protection (single-use proofs)
Multi-asset support (USDC, etc)
Payment freshness checks
Signed receipts
Credit/subscription system

How It Compares

Feature	x402	smol402
Needs facilitator	✅	❌
Self-hostable	Partial	✅ Fully
Censorship resistant	❌	✅
Light client verification	❌	✅

License

GPL3

Credits

https://x402.org - the protocol spec
https://code.jedda.eu/pypolkadot - Python light client
https://github.com/smol-dot/smoldot - underlying light client

Smol402