covenant-x402

Paid agent endpoints in USDC/USDG over x402, with instant on-chain settlement and credentials that never touch a prompt.

COVENANT turns any endpoint into a paid stablecoin route, settles through x402 — v1 and v2 simultaneously — across four chains (Robinhood 4663, Ethereum, Base, Arbitrum), and brokers agent credentials through a live vault so models can use secrets without seeing them. Open source, MIT-licensed.

Five pillars, one gateway:

Why this isn't "just a 402 demo"

• Four chains, one replay-guard, correctly scoped. Robinhood Chain (USDG), Ethereum, Base, and Arbitrum (Circle-native USDC) — each chain's own RPC, settlement wallet instance, and EIP-712 domain (chainId is part of the domain, so a signature for chain A cannot replay on chain B). The nonce table's primary key is (chain_id, nonce), not just nonce — a SQLite schema migration (not a greenfield assumption) that keeps old single-chain history intact while making cross-chain nonce collision structurally impossible.
• BNB Chain was evaluated and explicitly rejected, not silently skipped. Its "USDC" is Binance-Peg (bridged, not Circle-issued), 18 decimals instead of 6, no EIP-3009/DOMAIN_SEPARATOR. Mixing an 18-decimal asset into 6-decimals-everywhere code is exactly the silent-wrong-amount bug class that shouldn't ship — see the comment in gateway/chains.js.
• Every asset address was verified on-chain before being added, not copied from a block explorer listing — eth_getCode + symbol()/decimals()/name()/DOMAIN_SEPARATOR() via eth_call against a public RPC.
• Machine-readable discovery that's actually complete. GET /openapi.json returns a full OpenAPI 3.1 document — every paid route carries x-payment-info with both the per-call and session protocols, so an agent scanner (e.g. x402scan) discovers the cheaper session option without a human reading the README first.
• Dual x402 transport, same route. The ecosystem moved from v1 (JSON-body challenge) to v2 (Payment-Required header + extensions.bazaar) in Dec 2025. COVENANT's x402-v2.js adapter encodes a spec-compliant v2 header with the official @x402/core codec on top of the same route data — old clients and new clients both get a valid 402, no flag-flipping.
• Settlement is the honest approve+transferFrom pattern, not a claimed EIP-3009. None of the four supported chains' deployments implement transferWithAuthorization as COVENANT uses them — verified against on-chain bytecode, documented in the code rather than assumed. See How settlement works.
• Sessions aren't a toy feature. Settle once (0.01 USDG → 100 calls / 1h), then POST /session/redeem per call with no wallet interaction, no signature, no on-chain tx — a 100x cost reduction for agents that hammer an API, and it's advertised in the OpenAPI doc's x-payment-info.protocols[1], not hidden behind a support thread.
• Reputation is explainable, not vibes. score(address) = settled-count (log scale, 40pt) + cumulative volume (25pt) + longevity (15pt) + recency (20pt) — every point traceable to a real settlement tx hash via GET /reputation/:address.
• Signed webhooks, not an open POST. The kit's settlementWebhook carries an HMAC-SHA256 X-Covenant-Signature header when settlementWebhookSecret is set, with constant-time verification and 3-attempt exponential-backoff delivery — a receiver can reject spoofed settlement callbacks instead of trusting whoever finds the URL.
• Prometheus metrics, not just a JSON dashboard. GET /metrics exposes the same live counters as /x402/stats in standard text-exposition format — drop the gateway into existing Grafana/Alertmanager stacks without scraping JSON.

Repository layout

gateway/   Zero-dependency HTTP gateway: RPC proxy, x402 v1+v2, vault, facilitator (settlement), reputation
kit/       TypeScript middleware (@covenantx402/x402-kit) — Express paywall + usage analytics
examples/  Runnable examples: paywalled API, agent client that pays
skill/     Agent skill file (SKILL.md) — teach any agent (Claude/Cursor/Hermes) to use COVENANT
mcp/       MCP server (@covenantx402/mcp) — typed tools for discovery, 402 inspection, receipts and opt-in capped payment
Dockerfile, docker-compose.yml   Multi-stage build + one-command run (see Quick start below)

Quick start (gateway)

cd gateway
npm install            # pulls ethers, better-sqlite3, @x402/core
cp .env.example .env   # set RPC upstream + settlement key
node server.js         # listens on 127.0.0.1:8792

Then explore the machine-readable contract: curl http://127.0.0.1:8792/openapi.json

Quick start (Docker)

cp gateway/.env.example .env     # fill in at least COVENANT_RPC_UPSTREAM
docker compose up --build
curl http://127.0.0.1:8792/x402/health

Data (vault entries, wallets, keys, settlement/nonce history) persists in a named volume (covenant-data) across restarts and rebuilds. The container binds 0.0.0.0 internally (COVENANT_HOST=0.0.0.0, set in docker-compose.yml) so the -p/ports: mapping actually reaches it — the default bare-metal bind is 127.0.0.1, which only works when something else (nginx, a Cloudflare tunnel) is on the same host.

Environment