Arb402 — Final Report
Project Summary
We delivered Arb402, an HTTP 402 payment facilitator for Arbitrum that lets AI agents and automated services pay for APIs and resources with USDC, without holding gas or pre-approving spend. Across Milestones 1–8 we built the core 402 protocol and EIP-3009 signature verification, a crash-safe two-phase settlement engine, an HTTP facilitator service, a 14-command CLI, a reproducible on-chain settlement harness, four extensible application templates, a chain registry covering Arbitrum One, Nova, and Orbit L3s, and a complete documentation set. The result is a production-shaped facilitator a developer can run in minutes and a reviewer can verify with a single command. (GitHub: GitHub - badreldenbeko/Arb402 · GitHub )
Major Highlights
Open-source repository with the complete implementation — 7,259 lines of TypeScript and Solidity across protocol, CLI, harness, and templates, MIT licensed: GitHub - badreldenbeko/Arb402 · GitHub
Gasless settlement via EIP-3009 — the payer signs a TransferWithAuthorization off-chain and never sends a transaction or pre-approves an allowance; the facilitator pulls funds, takes a fee, and forwards the merchant’s share in two on-chain transactions.
Crash-safe settlement engine — a five-state payment machine with a background recovery worker, FOR UPDATE SKIP LOCKED row claiming, serialized wallet nonce management, and an admin refund path, so an RPC timeout or process crash can never pay a merchant twice or strand a user’s funds.
Chains as data, not code — Arbitrum One, Nova, and Sepolia ship built in; any Orbit L3 is added by writing one JSON entry, with no fork and no rebuild. An on-chain probe verifies EIP-3009 support and EIP-712 domain agreement before any chain is trusted: Arb402/docs/chains.md at main · badreldenbeko/Arb402 · GitHub
Reproducible verification — 146 automated tests plus a deterministic on-chain harness that settles all four sample applications end to end and asserts every balance moved exactly as the fee breakdown claims. Both run from a clean clone with no faucet, funded wallet, or external RPC.
Complete documentation — 1,576 lines across seven guides covering integration, CLI, HTTP API, configuration, chains, and deployment; every CLI command, endpoint, and environment variable documented: Arb402/docs at main · badreldenbeko/Arb402 · GitHub
Milestone Reports
01 — General 402 Payment Setup (Completed)
What we shipped
Core 402 protocol: payment requirement generation, x402 v1 and v2 payload schemas, EIP-712 digest construction, EIP-3009 signature verification, and the fee-inclusive pricing model (service fee in basis points plus a flat gas buffer, extracted before the merchant is paid).
Links
- Repository: GitHub - badreldenbeko/Arb402 · GitHub
- Commit: M1 - M3 implemented for reviewer demonstration · badreldenbeko/Arb402@4ae383f · GitHub
- Verify: npm test — signature roundtrips, fee math, and payment validation
02 — Working 402 (Completed)
What we shipped
Two-phase USDC settlement engine: transferWithAuthorization pulls funds from the payer, transfer forwards the merchant’s net share. Payments move through a persisted state machine (pending → incoming_submitted → incoming_complete → outgoing_submitted → complete), each transfer is signed and recorded before broadcast, and a background recovery worker retries stuck outgoing transfers with exponential backoff. Concurrent settlements are serialized through a single wallet nonce manager; recovery claims work with row locks so it is safe across cycles and instances. Failed payments can be refunded through an authenticated admin path.
Links
- Commit: M1 - M3 implemented for reviewer demonstration · badreldenbeko/Arb402@4ae383f · GitHub
- Hardening detail: M4 - M6 implemented with settlement engine hardening · badreldenbeko/Arb402@7c95f93 · GitHub
- Payment states: Arb402/docs/api.md at main · badreldenbeko/Arb402 · GitHub
03 — Arbitrum Chain Specific Implementations (Completed)
What we shipped
Arbitrum One as a first-class settlement chain using native Circle USDC (0xaf88d065e77c8cC2239327C5EDb3A432268e5831), verified on-chain as EIP-3009 capable with EIP-712 domain name=“USD Coin”, version=“2”. Delivered together with the HTTP facilitator service that exposes the protocol: eight endpoints covering health, supported payment kinds, requirements, verification, settlement, and admin operations, with bcrypt merchant and admin authentication, rate limiting, a maximum settlement cap, and boot-time checks that refuse to start against the wrong chain ID or a non-compliant token.
Links
- API reference: Arb402/docs/api.md at main · badreldenbeko/Arb402 · GitHub
- Verify: npx arb402 chains --verify — probes Arbitrum One’s USDC on the live network
04 — CLI (Completed)
What we shipped
The arb402 binary: 14 commands covering configuration scaffolding (init), inspection (config, chains, wallet), deployment readiness (doctor), key generation (keygen), running the facilitator (dev, start), and merchant lifecycle management (merchant create/add/list/enable/disable/delete). doctor is designed as a deployment gate — it exits non-zero on any blocking issue, so it can sit in a CI or deploy pipeline.
Links
- CLI reference: Arb402/docs/cli.md at main · badreldenbeko/Arb402 · GitHub
- Commit: M4 - M6 implemented with settlement engine hardening · badreldenbeko/Arb402@7c95f93 · GitHub
- Verify: npx arb402 --help, then npx arb402 doctor
05 — Reproducible Settlement Testing (Completed)
What we shipped
A deterministic on-chain settlement harness. It compiles and deploys its own EIP-3009 TestUSDC contract to a local chain running at Arbitrum Sepolia’s chain ID (421614), starts the real facilitator against it, and settles each of the four sample applications end to end — signing a genuine EIP-3009 authorization and driving the full /requirements → /settle flow. For every payment it asserts on-chain that the payer was debited the full amount, the merchant received the net amount, the facilitator retained exactly serviceFee + gasFee, and total funds were conserved.
The harness runs from a clean clone with one command and requires no faucet, no funded wallet, and no external RPC.
Links
- Harness: Arb402/harness at main · badreldenbeko/Arb402 · GitHub
- Verify: cd harness && npm install && npm run harness
06 — General Implementation Templates (Completed)
What we shipped
Four extensible templates, each built on one shared dependency-free x402 client: a pay-per-call API (client and server), metered AI inference with batch settlement that amortises gas across many calls, an agent-to-agent task payment flow, and a paid MCP tool using a quote → pay → result handshake. Every template settles end to end in the harness.
Links
- Templates: Arb402/templates at main · badreldenbeko/Arb402 · GitHub
- Integration guide: Arb402/docs/integration.md at main · badreldenbeko/Arb402 · GitHub
07 — Nova and Orbit Implementations (Completed)
What we shipped
A chain registry that treats chains as data rather than code. Arbitrum One, Nova, and Sepolia ship as a built-in table; any Orbit L3 is registered by adding one entry to arb402.chains.json — no fork, no rebuild — and is then accepted everywhere a built-in chain is, including configuration, startup checks, and settlement.
Because a registry entry is a claim rather than a fact, we added an on-chain token probe that checks it against the contract: authorizationState proves EIP-3009 is implemented, and the declared EIP-712 domain must reproduce the contract’s own DOMAIN_SEPARATOR. Both are surfaced by arb402 chains --verify and enforced at boot.
That probe produced a finding worth recording: Arbitrum Nova has no EIP-3009-capable stablecoin. Nova’s canonical USDC.e (0x750ba8b76187092B0D1E87E28daaf484d1b5273b) is a bridged gateway ERC-20 — it has six decimals, the symbol USDC, and even a DOMAIN_SEPARATOR, but authorizationState reverts and transferWithAuthorization does not exist. It cannot settle a single payment. Rather than ship a default that would produce valid-looking signatures reverting on-chain, Nova ships fully supported except for a settlement token the operator supplies, which doctor then verifies before it is relied on.
Links
- Chains guide: Arb402/docs/chains.md at main · badreldenbeko/Arb402 · GitHub
- Orbit config template: Arb402/arb402.chains.example.json at main · badreldenbeko/Arb402 · GitHub
- Commit: M7 - M8 implemented with chain registry and documentation · badreldenbeko/Arb402@422cd77 · GitHub
- Verify: npx arb402 chains --verify
08 — Documentation (Completed)
What we shipped
Seven guides totalling 1,576 lines: an index, integration (charging for an API and paying for one), a CLI reference with every command, option, and exit code, an HTTP API reference with every endpoint, schema, and error, a configuration reference covering every environment variable, a chains guide for One, Nova, and Orbit onboarding, and a deployment guide covering production, scaling, monitoring, and key rotation. Coverage is complete and checkable: 14 of 14 CLI commands, 8 of 8 endpoints, and 23 of 23 environment variables documented. Released under MIT.
Links
- Documentation: Arb402/docs at main · badreldenbeko/Arb402 · GitHub
- License: Arb402/LICENSE at main · badreldenbeko/Arb402 · GitHub
- Commit: M7 - M8 implemented with chain registry and documentation · badreldenbeko/Arb402@422cd77 · GitHub
Conclusion
Milestones 1–8 delivered the intended outcome: a working HTTP 402 payment facilitator for Arbitrum that a developer can configure and run in minutes, with gasless payments for the payer, crash-safe settlement, multi-chain support spanning Arbitrum One, Nova, and Orbit L3s, and documentation covering every command, endpoint, and setting. Every claim in this report is reproducible from a clean clone — npm test for the 146-test suite, npm run harness for full on-chain settlement of all four sample applications, and arb402 chains --verify for live token verification.
We will continue maintaining the repository, tracking Arbitrum toolchain and token changes, and supporting teams adopting 402 payments. For feedback, issues, or contributions, use the repository above.
Thank you.