feat: x402 payment protocol — complete POC with escrow, channels, dApp, and deployment

[andreabadesso]

x402 Payment Protocol POC for Hathor Network

Complete proof-of-concept implementation of the x402 protocol on Hathor Network, enabling pay-per-request HTTP APIs settled natively on Hathor's DAG-based L1 blockchain using nano contract escrow. Aligned with x402 V2 spec.

Live Demo

• dApp: https://x402.hathor.dev
• Paid API (402): https://api.x402.hathor.dev/weather
• Facilitator: https://facilitator.x402.hathor.dev
• Health check: https://facilitator.x402.hathor.dev/health
• Network: playground testnet (node1.playground.testnet.hathor.network)

Connect your Hathor wallet via WalletConnect, fetch the weather API, approve the escrow deposit, and receive the data.

---

How it works

Every x402 payment creates a new nano contract instance from the X402Escrow blueprint. The client deposits funds into the contract (locked on-chain), the facilitator verifies the lock, the server delivers the resource, and the facilitator releases the funds to the seller.

Client → GET /weather → 402 Payment Required (x402Version: 2)
Client → Create escrow nano contract (deposit funds on-chain)
Client → GET /weather + PAYMENT-SIGNATURE: <base64> → Facilitator verifies → 200 + PAYMENT-RESPONSE header + data
Facilitator → release() → Funds sent to seller

For repeat clients, payment channels allow pre-funding a single contract and making multiple requests without per-request contract creation.

See the README for the full explanation of the escrow model.

---

x402 V2 Spec Alignment

Change	Description	Issues
PAYMENT-SIGNATURE header	Base64-encoded payment proof (replaces X-Payment, backward compat kept)	#2
PAYMENT-RESPONSE header	Base64-encoded settlement result on 200 responses	#3
x402Version: 2 field	Added to 402 response, payment payload, verify/settle responses	#4
CAIP-2 network IDs	hathor:<network> used consistently via config	#5
price field	Renamed from amount in 402 accepts[] array	#7
Settlement idempotency	Escrow settlements cached by ncId to prevent duplicate release()	#8
/health endpoint	Reports wallet connectivity, returns 503 when degraded	#12
Wallet auto-recovery	Facilitator checks wallets every 30s, restarts if disconnected	#12
MCP server example	examples/mcp-server/ — payment-gated AI tool calls	#13

---

What's included

Nano Contract Blueprints

Blueprint	File	Purpose
X402Escrow	blueprint/x402_escrow.py	One escrow per payment. LOCKED → RELEASED or REFUNDED.
X402Channel	blueprint/x402_channel.py	Pre-funded channel. Client deposits once, facilitator calls spend() per request.

Backend Services (Node.js)

Service	File	Port	Description
Facilitator	facilitator.js	8402	Verifies escrow/channel state, triggers settlement. /health endpoint with wallet auto-recovery. Idempotent escrow settlements.
Resource Server	resource-server.js	3001	Paid weather API with x402 V2 middleware. Returns PAYMENT-RESPONSE header on success.
Client	client.js	—	Programmatic x402 V2 client. Sends PAYMENT-SIGNATURE header.

Frontend dApp (Next.js)

Component	Description
dapp/components/X402Fetch.tsx	Main x402 flow: fetch URL → 402 → choose escrow or channel → pay → receive data
dapp/components/EscrowList.tsx	Track and list escrow contracts
dapp/components/EscrowDetail.tsx	View escrow details, trigger refund
dapp/components/CreateEscrowForm.tsx	Manual escrow creation form

Built with create-hathor-dapp. Connects via WalletConnect (Reown). Supports privatenet and testnet. Balance fetches fall back to direct fullnode query when WalletConnect relay is flaky.

MCP Server Example

File	Description
examples/mcp-server/server.js	Payment-gated MCP server with get_weather (paid) and get_price (free) tools
examples/mcp-server/README.md	Setup guide including Claude Code integration

Deployment (Docker Compose)

File	Description
docker-compose.yml	4 services: wallet-headless, facilitator, resource-server, dApp
Dockerfile	Backend services image
dapp/Dockerfile	Next.js production build
init-wallets.sh	Auto-starts facilitator and seller wallets on deploy

Deployed on Dokploy at *.x402.hathor.dev connected to the playground testnet.

---

Protocol Messages (V2)

402 Response:

{
  "x402Version": 2,
  "accepts": [
    { "scheme": "hathor-escrow", "network": "hathor:testnet", "asset": "00", "price": "100", "payTo": "WQ6F...", "description": "Pay 1.00 HTR (single escrow)", "extra": { "facilitatorUrl": "...", "blueprintId": "..." } },
    { "scheme": "hathor-channel", "network": "hathor:testnet", "asset": "00", "price": "100", "description": "Pay 1.00 HTR via channel" }
  ],
  "version": "1"
}

PAYMENT-SIGNATURE request header (Base64-encoded):

{ "x402Version": 2, "scheme": "hathor-escrow", "network": "hathor:testnet", "payload": { "ncId": "000abc...", "depositTxId": "000abc...", "buyerAddress": "Wg7r..." } }

PAYMENT-RESPONSE response header (Base64-encoded):

{ "x402Version": 2, "success": true, "scheme": "hathor-escrow", "network": "hathor:testnet", "ncId": "000abc...", "settleTxId": "000def..." }

---

Related RFCs

All design documents are in HathorNetwork/rfcs#109:

RFC	Title	Description
0001	x402 Protocol Support	Base protocol design — escrow blueprint, facilitator, message formats
0002	Client SDK (@hathor/x402-client)	fetch() wrapper that handles 402 → pay → retry automatically
0003	Server Middleware (@hathor/x402-server)	Express/Fastify/Hono middleware — 3 lines to add x402 to any API
0004	Payment Channels	Pre-funded channels for repeat clients — eliminates per-request contract creation

---

Issues addressed

Closes #2, closes #3, closes #4, closes #5, closes #7, closes #8, closes #12, closes #13

Issues NOT addressed (external/decision tasks):

• Register hathor-escrow and hathor-channel schemes with x402 ecosystem #6 — Scheme registration requires PR to coinbase/x402
• Implement Signed Offers & Receipts extension #9 — Signed Offers & Receipts needs signing key design decision
• Register with x402 Bazaar (discovery layer) #10 — Bazaar registration is post-production
• Consider SIWX (Sign-In-With-X) extension for repeat access #11 — SIWX evaluation (channels already solve repeat access)

Test plan

• Deploy to Dokploy and verify dApp completes payment flow (escrow + channel)
• Verify PAYMENT-SIGNATURE header sent by client (Base64)
• Verify PAYMENT-RESPONSE header present on 200 responses
• Verify 402 response includes x402Version: 2 and price field
• Verify /health endpoint returns wallet status
• Verify backward compat: old X-Payment header still accepted
• Verify channel spend() is called on every request (no over-caching)
• Verify escrow idempotency: duplicate settle returns cached result
• Verify wallet auto-recovery after headless restart

🤖 Generated with Claude Code