x402 protocol

x402 protocol

This page is the canonical operational reference for Boon’s x402 surface. It supersedes the historical docs/x402-api.md file in the repo — the doc site is the source of truth. The companion x402 paid endpoints page lists route shapes and launch pricing.

Boon uses x402 only for detailed graph and scoring reads. Sending, claiming, aggregate points, profiles, receipts, and recipient help remain free.

Version and packages

The Worker uses scoped x402 V2 packages:

• @x402/hono — Hono middleware integration
• @x402/core — protocol primitives
• @x402/evm — EVM settlement adapter
• @x402/fetch — if a paid API client is added, pin the same major/minor

All four must stay on matching versions. Do not implement the legacy V1 x-402-payment path for Boon.

Header flow

1. Client calls a paid endpoint without payment.
2. Worker returns 402 Payment Required and a PAYMENT-REQUIRED challenge.
3. Client signs the payment payload.
4. Client retries with PAYMENT-SIGNATURE.
5. Worker verifies/settles through the facilitator.
6. Worker returns the JSON response and PAYMENT-RESPONSE.

Networks

Network identifiers are CAIP-2 strings.

Environment	Network
Sandbox examples	eip155:84532 (Base Sepolia)
Production	eip155:8453 (Base mainnet)

Production Base USDC:

0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Facilitators

The repo configuration supports:

• Sandbox / test: https://x402.org/facilitator — signup-free, Base Sepolia.
• Production CDP: https://api.cdp.coinbase.com/platform/v2/x402 — Base mainnet.

CDP production usage requires CDP_API_KEY_ID and CDP_API_KEY_SECRET Worker secrets. The CDP facilitator has a monthly free tier and then charges per transaction, which is why the base paid route is not priced below $0.002 unless Boon is intentionally pointed at a fee-free facilitator.

Worker configuration

These are the Worker variables (set via wrangler.jsonc or as secrets):

Var	Value / purpose
X402_RECIPIENT	Boon team Safe 0x9eD16E6E1c0eA4f3739d1cF23041ed7aA782c08F. Receives x402 revenue. Do not replace with an operator/deployer EOA.
X402_NETWORK	eip155:84532 for sandbox; eip155:8453 for Base mainnet.
X402_FACILITATOR_URL	Sandbox: https://x402.org/facilitator. Production CDP: https://api.cdp.coinbase.com/platform/v2/x402.
USDC_ADDRESS	Base USDC address above.
CDP_API_KEY_ID	Required only for production CDP facilitator.
CDP_API_KEY_SECRET	Required only for production CDP facilitator.

Security rules

• Do not bypass payment based on Origin; non-browser clients can spoof it. The SPA stays free because it calls only the free endpoints listed in API overview → Public data surfaces, not because of an Origin allowlist on paid routes.
• Bind/check the x402 resource per route so a payment receipt for one endpoint cannot be replayed against another.
• Do not log payment signatures or full payment payloads.
• Return a generic unavailable/payment error to clients when the facilitator is down; log structured upstream detail server-side only.
• Sender disclosure writes (POST / DELETE /api/v1/boons/:txHash/disclosure) must be EIP-712-verified against the indexed tipper. Unauthenticated disclosure is a privacy bug.
• Keep claim, viewing, and recipient help out of paid endpoints.

Boon Points model

Boon Points are non-transferable, non-redeemable, public reputation derived from onchain Tip events plus OAuth-linked wallets.

• Recipient-handle points live on the subgraph Recipient entity.
• Sender-wallet points live on the Tipper entity.
• Per-handle sentPoints is a Worker read-side join from Recipient.linkedWallet → Tipper.id. Handles with no linked wallet return sentPointsSource: "unlinked".
• Points use scaled integers (POINT_SCALE = 1000) so fractional rules stay deterministic.
• Pair/day anti-farming state lives in the subgraph, not an in-memory AssemblyScript map.
• The contract event does not include artifactHash; repo/artifact bonuses use deterministic note markers unless a future contract field is added.

The public policy endpoint (GET /api/v1/points/policy) returns the versioned rules and pointScale.

Disclosure storage

Optional sender disclosure metadata lives in the Worker’s DISCLOSURE_KV namespace (wired in worker/wrangler.jsonc). Reads are public; writes and deletes require sender EIP-712 verification per the security rules above.

Verification and deployment gates

Before deploying production paid routes, the Worker cluster ships serialized through gates U0 → U1 → U2 → U4 → U5. U3 only ships if sender-signature auth is included in the change.

Validation commands:

forge test -vvv
pnpm --filter boon-worker test
pnpm --filter boon-worker exec wrangler deploy --dry-run
pnpm --filter boon-app typecheck
pnpm --filter boon-app build

The funded live-settlement smoke is the final launch gate. It must return a validated event after exercising the full 402 challenge → PAYMENT-SIGNATURE retry → PAYMENT-RESPONSE → settlement receipt → Base USDC transfer to X402_RECIPIENT:

cd worker
X402_PAYER_KEY=0x... pnpm run smoke:x402-live

Use a low-balance burner key funded with enough Base USDC to cover the advertised price. A successful 402 challenge response alone is not proof that paid settlement works end to end.

Subgraph build commands run only after subgraph/networks.json has real contract addresses and start blocks; the render script intentionally fails on zero addresses so a placeholder subgraph cannot be deployed by accident:

npm --prefix subgraph run build:mainnet
npm --prefix subgraph run build:sepolia

References

• x402 paid endpoints — route shapes and launch pricing.
• Authentication — voucher and disclosure signature shapes.
• Coinbase x402 docs: https://docs.cdp.coinbase.com/x402/core-concepts/how-it-works
• x402 network support: https://docs.cdp.coinbase.com/x402/network-support
• Cloudflare x402 Workers docs: https://developers.cloudflare.com/agents/agentic-payments/x402/