Repository avatar
AI Tools
v0.1.0
active

x402fi

dev.x402fi/x402fi

Find paid x402 APIs on Robinhood Chain and get the exact USDG payment for a call. Never pays.

Documentation

x402Fi

The dedicated x402 Finance platform and marketplace on Robinhood Chain.

x402Fi lets any business sell an API, a data feed, an AI agent or an on-chain product per request, in dollars, to people and AI agents, using the open x402 payment standard. Buyers pay in USDG on Robinhood Chain with a single signature: no accounts, no API keys, no invoices, no gas. Sellers keep 100% of every payment, which lands directly in their own wallet.

x402Fi is non-custodial software operated by Only Buy Bitcoin LLC. It never holds user funds. See Terms, Privacy and Disclaimer.


Contents

  1. Why x402Fi
  2. Features
  3. How a payment works
  4. Architecture
  5. x402 implementation details
  6. Pricing modes
  7. Verified Payee (x402 Identity)
  8. On-chain settlement: HoodFi name registration
  9. Our services on x402Fi: IPFS Pinning
  10. Security reviews (HEY Research Lab)
  11. Security model
  12. Public APIs
  13. Data model
  14. Project structure
  15. Local development
  16. Configuration and secrets
  17. Database migrations
  18. Deploying
  19. Testing
  20. Operations
  21. Known traps
  22. Reference values
  23. Legal

Why x402Fi

HTTP has reserved status code 402 Payment Required since 1997. x402 finally gives it a precise meaning: a server answers an unpaid request with a machine-readable price, the client signs a payment, retries, and gets the response. That makes per-request payments practical for software, and especially for AI agents, which cannot fill in sign-up forms or manage API keys.

x402Fi packages that into a product businesses and institutions can use without writing payment code:

  • For businesses: paste the URL of an API you already run, set a price, and x402Fi puts the paywall in front of it.
  • For institutions: every payment is non-custodial, settles on a public chain, comes with a receipt and a transaction hash, and lands in an exportable ledger. Payees can be bound to a signed on-chain name.
  • For developers: a public x402 facilitator for Robinhood Chain, a Bazaar-style discovery feed, an MCP server for agents, and open protocol details.

Features

AreaWhat it does
No-code paywallA gateway at /g/<listing>/<path> answers 402 with a price, verifies the buyer's signed USDG authorization, forwards the call to the seller's API and settles only after the API answers 2xx.
Multi-endpoint listingsOne listing (project) holds many endpoints, each with its own method, path and pricing: free, fixed, seller-quoted or on-chain contract.
MarketplaceSearchable listings with categories, price summaries, logos and a live Try it button that runs a real payment from the visitor's wallet. Try it shows one field per query parameter of the seller's example, pre-filled with the example value (0x addresses and numbers are checked before signing; wallet parameters offer "Use my wallet"), an editable JSON body for POST endpoints, and a file picker (up to 1 MB) for POST endpoints whose seller ticked "Takes a file as the request body".
Verified PayeeSellers link an x402 Identity (ENS) name. x402Fi checks it with the open payee-name verifier and shows a badge only when the name's own records list the service and its payout wallet.
Verified profilesLogo, website and X handle are read from the payee name's ENS records (verified ✓). Seller-entered values fill gaps and are labelled "by seller".
On-chain productsA contract pricing mode settles by calling a seller contract (e.g. register a name and deliver it) in one atomic transaction.
Ledger and receiptsEvery paid attempt is recorded (settled, not charged, or API error). Each payment has a public receipt page with its transaction hash, and sellers can export a CSV.
Public facilitator/api/facilitator/verify, /settle, /supported for sellers building x402 on Robinhood Chain. It settles to the payout wallet of a listing on x402Fi (a native listing counts), $0.01 or more.
Discovery feedBazaar-style JSON of every paid endpoint for agents and indexers (/api/discovery/resources), with a readable view at /discovery. Items carry the bazaar extension (how to call each endpoint); filters and pagination follow the Bazaar spec, and the SDK path /api/facilitator/discovery/resources works too.
MCP serverhttps://x402fi.dev/mcp (Streamable HTTP, no auth): search_services, get_listing, get_payment_requirements. Search and describe only; it never pays, signs or calls a paid endpoint.
Native x402 listingsSellers whose endpoint already charges with x402 list it as is: x402Fi reads the price, payTo and payee name from their 402 and buyers pay the seller directly. x402Fi never proxies, settles or takes a fee on these. x402 v1 and v2 endpoints both list; a v1 endpoint is labelled as v1 everywhere, with the X-PAYMENT header. "Try it" is for proxied endpoints only.
Priors credit recordsListings show the payout wallet's Priors record (ERC-8004 agent credit on Robinhood Chain): score, loans repaid, defaults.
HoodFi payee namesA *.hoodfi.eth name, native to Robinhood Chain, can be the payee name: its records are written in one Robinhood Chain transaction, and sellers can register one in the wizard over x402.
Security reviewsIndependent code reviews by HEY Research Lab, in a review program run with x402Fi. A seller requests one in the wizard or dashboard; HEY signs each state (EIP-712) and a reviewed endpoint shows HEY's line, the commit, the report and a signed proof. See Security reviews.
Listing wizardSix steps: service → endpoints (as many as you sell, each with its own path and price, or free) → name → connection test → security review (optional) → publish. Proxied or native. The name step suggests payee names from the service name, checked live on HoodFi Names (Robinhood Chain, USDG) and x402 Identity (Ethereum), registers them in place, and reads an existing name's records first so a name already set up needs no signature.
DashboardRevenue, a 30-day chart, ledger, CSV export, pause, payout rotation, upstream secret rotation, profile and endpoint editing (price, free, example request/body/response), and the security review panel (request, submit fixes, cancel). A notice names any live paid endpoint without an example response, since that is what agents read before paying.
Example responsesEach endpoint can show what a successful call returns: on the listing page, and as the bazaar output example in the feed and MCP. Text that looks like JSON must parse.
Wallet sign-inSign-In with Ethereum (EIP-4361). Works with injected, WalletConnect, email and social wallets (Reown AppKit). Disconnecting the wallet also ends the dashboard session, and Sign out also disconnects the wallet: one action either way.
DesignCream-and-forest design system, light theme only (dark mode was retired), phone-first layout.

Listing is free and x402Fi takes 0%. The only optional paid step in the flow is registering an x402 Identity name (a third-party ENS registrar, paid on Ethereum).

How a payment works

sequenceDiagram
    autonumber
    participant A as Buyer (agent or person)
    participant G as x402Fi gateway
    participant S as Seller API
    participant C as Robinhood Chain (USDG)

    A->>G: GET /g/fx-rates?pair=EURUSD
    G-->>A: 402 Payment Required (price, USDG, payTo, network, payee name)
    Note over A: Wallet signs EIP-3009 TransferWithAuthorization<br/>(exact amount, one-time nonce, expiry). No gas.
    A->>G: Same request + PAYMENT-SIGNATURE header
    G->>C: Verify: signature, amount, payTo, validity window,<br/>nonce unused, balance (chain time, not server time)
    G->>G: Claim nonce + reserve funds in D1 (a replay loses here)
    G->>S: Forward request + X-X402Fi-Secret + X-X402Fi-Payer
    S-->>G: 200 OK + data
    G->>C: transferWithAuthorization (x402Fi pays gas)
    C-->>G: Receipt (status checked)
    G-->>A: 200 OK + data + PAYMENT-RESPONSE (tx hash) + receipt link

If the seller's API errors or times out, step 9 never happens: the authorization is never used and the buyer is not charged. The ledger records the failed attempt.

Architecture

                     ┌────────────────────────── Cloudflare ──────────────────────────┐
 Browser / Agent ──▶ │  Worker: Next.js 15 (App Router) via @opennextjs/cloudflare   │
                     │   ├─ pages: /, /market, /market/[slug], /sell/new, /dashboard, │
                     │   │         /learn, /institutions, /developers, /receipt/[id],│
                     │   │         /terms, /privacy, /disclaimer                     │
                     │   ├─ /g/[slug]/[[...path]]   x402 gateway (all methods)       │
                     │   ├─ /api/facilitator/*      public facilitator               │
                     │   ├─ /api/discovery/*        discovery feed                   │
                     │   ├─ /api/rpc, /api/rpc/mainnet  browser RPC proxies          │
                     │   └─ /api/{auth,listings,services,dashboard,payments,logo}    │
                     │  D1 (SQLite, Drizzle)   KV (payee/profile cache, SIWE nonces) │
                     │  Email Routing: contact@x402fi.dev                            │
                     └───────────────┬──────────────────────────────┬────────────────┘
                                     │                              │
                 Robinhood Chain (4663): USDG, settlement     Ethereum mainnet: ENS
                 Alchemy → public RPC → Blockscout RPC        (payee names, profiles)

Stack: Next.js 15, React 19, TypeScript, Tailwind CSS v4, viem, wagmi, Reown AppKit, Drizzle ORM, Cloudflare Workers + D1 + KV, Vitest. Related on-chain code (the HoodFi registration contract) lives in the hoodfi-eth repository (Foundry).

x402 implementation details

x402Fi implements x402 version 2, scheme exact, on network eip155:4663 (Robinhood Chain), asset USDG.

402 response. JSON body plus the same object base64-encoded in the PAYMENT-REQUIRED header:

{
  "x402Version": 2,
  "resource": { "url": "https://x402fi.dev/g/demo-quote", "description": "…", "mimeType": "application/json" },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:4663",
    "amount": "10000",
    "asset": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
    "payTo": "0x837Fa2d033f1F7275452D780a5E54Eda903C1330",
    "maxTimeoutSeconds": 120,
    "extra": { "name": "Global Dollar", "version": "1" }
  }],
  "extensions": { "payee-name": { "info": { "name": "hoodfi.402api.eth" } } }
}

Payment header. The client retries with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1 name, accepted) containing base64 JSON:

{
  "x402Version": 2,
  "accepted": { "...": "the chosen entry from accepts" },
  "payload": {
    "signature": "0x…",
    "authorization": { "from": "0x…", "to": "0x…", "value": "10000", "validAfter": "0", "validBefore": "1794…", "nonce": "0x…32 bytes" }
  }
}

Success. PAYMENT-RESPONSE and X-PAYMENT-RESPONSE carry base64 { success, transaction, network, payer }; X-X402Fi-Receipt links the receipt page.

USDG EIP-712 domain. { name: "Global Dollar", version: "1", chainId: 4663, verifyingContract: 0x5fc5…d168 }. The token has no version() getter; "1" was confirmed by reproducing its DOMAIN_SEPARATOR() on-chain. Signatures are EIP-3009 TransferWithAuthorization with v/r/s (EOA wallets).

Verification (src/lib/x402/facilitator.ts): x402 version, scheme, network, asset, payTo and to match, value equals the price exactly, validBefore ≥ chain time + 6 s (the gateway asks for 40 s: the seller's 25 s timeout plus a settlement margin, since it settles after the seller answers), validAfter ≤ chain time, signature recovers to from (verifyTypedData, which also supports ERC-1271/6492), nonce unused (authorizationState), and balance ≥ value. A failed chain read returns 503 retry, never a denial.

Pricing modes

Each endpoint (a "service" inside a listing) has a path prefix, a method and one pricing mode. Requests route to the live endpoint with the same method and the longest matching path prefix.

ModePrice comes fromSettlementWho can enable
free—Forwarded without payment, no ledger rowSeller
fixedpriceAtomic per callUSDG transfer to the listing's payout wallet, after the API returns 2xxSeller
quoteSeller API: GET {upstream}{quotePath}{rest} → {"price":"5.00"} or {"amount":"5000000"}, capped by a published ceiling, re-quoted on the paid requestSame as fixedSeller
contractOn-chain quote(label) on a "label registrar" contractThe contract call itself (registerWithAuthorization), atomicx402Fi admin (x402Fi pays the gas)
nativeThe seller's own 402, read by an unpaid probe (cached 10 min; re-checked when saved)None by x402Fi: the buyer pays the seller directly; the gateway answers 307 to the seller's URLSeller (signed in)

Minimum price: $0.01 for the modes x402Fi settles (fixed, quote). Settling one payment costs x402Fi roughly $0.006 to $0.007 of gas on Robinhood Chain (measured on the first live payment), so a cent covers it. Enforced in the wizard, the endpoint editor, seller quotes and the API (MIN_PRICE_ATOMIC).

Verified Payee (x402 Identity)

x402Fi integrates the x402 Identity Hub and its payee-name extension (spec):

  1. In the wizard's Identity step, a seller mints a name such as yourco.402api.eth with the embedded @x402identity/widget-react. x402Fi sets no platform fee on it.
  2. x402Fi writes the payee records in one Ethereum transaction (existing origins are kept):
    • org.x402.origins += https://x402fi.dev
    • address record for Robinhood Chain, coin type 0x80000000 | 4663 = 2147488311, = the payout wallet
    • optionally org.x402.payto for extra payees, e.g. eip155:4663:<contract> for contract endpoints
  3. The 402 carries extensions.payee-name.info.name, and the listing page runs @x402identity/payee verifyPayee (cached 10 minutes in KV). The badge is tri-state: Verified, not confirmed (with the reason) or couldn't check right now. A failed read is never shown as a failure.

Profile fields are read from the same name: avatar, url (or website), com.twitter (or com.x, X, x, twitter). ENS keys are case-sensitive. The wizard can write avatar, url and com.twitter in the same transaction as the payee records.

Writing payee records keeps any existing org.x402.origins and org.x402.payto entries (widget-core's builder always rewrites org.x402.payto, so x402Fi merges first).

Native listings are checked against the seller's own origin, because that is the origin buyers contact.

HoodFi names as payee names

*.hoodfi.eth names live in HoodFi's L2Registry on Robinhood Chain (0xf2bABA012244bdD7445129597350054E1B3aEe5C), which inherits ENS's TextResolver, AddrResolver and Multicallable. Only the name's owner (or an approved address) sets its records. HoodFi's CCIP gateway serves any record on Ethereum, so the standard payee-name verifier works unchanged.

  • The wizard's Use a HoodFi name option writes org.x402.origins, the Robinhood Chain address record, org.x402.payto (merged) and optional profile records in one multicall on Robinhood Chain (gas in ETH on 4663). It checks ownership first. A simulated write succeeds from the owner and reverts from anyone else.
  • A seller without a name can register one in place, from $3 in USDG over x402, through the HoodFi listing.
  • The verifier's informational parent_can_control reads true for these names because it is computed from Ethereum mainnet's NameWrapper, where L2 subnames do not exist. It does not describe control on Robinhood Chain, so x402Fi does not surface it.

On-chain settlement: HoodFi name registration

The first project on x402Fi is HoodFi Names (*.hoodfi.eth names on Robinhood Chain). Its listing has two endpoints:

EndpointPricing
GET /g/hoodfi-names/owner/<wallet>/names: every HoodFi name a wallet holdsfree
POST /g/hoodfi-names/register/<name>: registers <name>.hoodfi.eth for the payercontract, $3 (4+ chars) to $15 (1 char)

An x402 buyer only signs, but HoodFi's registrar mints to whoever sends the transaction. HoodfiX402Registrar (0x64A6439a05aa4c91c3ACE97842a98148888A2534, source verified on Sourcify, owned by the HoodFi Safe) bridges the gap in one transaction:

  1. pull exactly the quoted price from the buyer with their EIP-3009 signature (to = the contract);
  2. pay the live registrar and register the name (minted to the contract);
  3. point the name's address records (coin types 60 and 2147488311) at the buyer;
  4. transfer the NFT to the buyer.

Any failure reverts all four, so the buyer is never charged without the name. The name always goes to the address that signed. The contract keeps no margin and is never a registrar. Measured gas: about 350 to 400k (≈ $0.02 to $0.05). The first registration through x402 was dominic.hoodfi.eth.

Our services on x402Fi: IPFS Pinning

x402Fi also lists services we run ourselves, on the same terms as any seller. IPFS Pinning (/market/ipfs-pinning, payee name ipfs.hoodfi.eth, site ipfs.hoodfi.eth.link) lets an agent pin a file to IPFS with one x402 payment: no account, no API key.

EndpointPrice
POST /g/ipfs-pinning/pin: pins the request body (any content type, or multipart file), up to 1 MB; optional ?name=report.pdf; returns the CID and gateway links$0.01
GET https://ipfs.x402fi.dev/status/<cid>: whether a CID is pinned, and until whenfree

Pins are kept for 2 years (pinned_until is in every response), then a daily job unpins them. The upstream is its own Cloudflare Worker at ipfs.x402fi.dev (Worker + D1, storage on Pinata) that accepts only calls carrying the listing's X-X402Fi-Secret, and answers non-2xx on any failure so the buyer is not charged. Pinata dedupes identical files, so a file stays pinned while any buyer's pin of it is live. The first paid pin settled on 2026-11-13 (tx).

# Unpaid: returns the 402 (price, payTo, payee-name and bazaar extensions)
curl -X POST "https://x402fi.dev/g/ipfs-pinning/pin?name=hello.json" -H "content-type: application/json" -d '{"hello":"world"}'

Security reviews (HEY Research Lab)

A review program run in collaboration with HEY Research Lab. Free for listers today. One review per endpoint; rules in src/lib/reviews.ts.

StateSet byBuyers see
requestedthe lister (wizard "Review" step or dashboard)"Review in progress"
findings_sentHEY, signed"Review in progress"
fixes_submittedthe lister, naming the commit with the fixes"Review in progress"
reviewedHEY, signed, after re-testing at a pinned commitHEY's line, commit, date, report, signed proof
withdrawnHEY, signednothing: the review comes off the listing

The three in-progress states look the same in public, by design, so nobody can tell findings exist before they are fixed. A reviewed endpoint falls back to out of date once its method, path or upstream URL changes (reviewTarget()).

Signatures. HEY POSTs { message, signature } to /api/reviews/hey. EIP-712 domain { name: "HEY Security Review", version: "1" } (no chainId, no verifyingContract), primary type Review(string listing, string endpoint, string commit, string reportUrl, string state, uint64 issuedAt). The signature must recover to an address in HEY_REVIEW_SIGNERS; HEY publishes its signer at https://heyresearch.xyz/api/v1/security-review/signer. issuedAt must increase per endpoint (checked against the row and the signed-event log, so a replay is 409) and must not predate the lister's latest request. reviewed needs a 7 to 64 hex commit and an https reportUrl. Every applied message is kept in review_events.

Wording (agreed with HEY): the reviewed line is exactly "Independent review by HEY Research Lab, findings fixed and re-tested". Say "collaboration" or "review program"; never "audited", "safe", "partner", "certified" or "verified by". The home page card (ReviewProgramCard, /#security-reviews) carries HEY's disclaimer: a review covers the reviewed commit only, is not a guarantee about the endpoint or its operator, is not an audit or an endorsement, and HEY can withdraw it.

Where it shows: a card in the listing sidebar (logo + status across endpoints), a line on each endpoint card, a chip, a "reviewed" filter and a ranking boost on the marketplace, and the dashboard panel (where the lister also sees findings_sent). HEY's logo is public/partners/hey-research-lab.svg (traced from HEY's files; a -dark.svg exists for dark backgrounds).

Tested end to end on production on 2026-11-17 with demo-quote: findings_sent → fixes_submitted → reviewed → withdrawn.

Security model

  • Non-custodial. Payments go buyer → seller (or buyer → seller contract) under the buyer's own signature. The settlement wallet only holds ETH for gas and never receives USDG.
  • Charge only for answers. Fixed and quoted endpoints settle after the upstream returns 2xx; contract endpoints are atomic.
  • Replay protection. The authorization nonce is claimed in D1 under a unique index before the upstream is called, and USDG's authorizationState rejects reuse on-chain.
  • Funds are reserved while a call is in flight. The same statement that claims the nonce (src/lib/gateway/reserve.ts) inserts the row only if the payer's other pending payments plus this one fit in the balance the check read, so one balance cannot back several concurrent calls. A pending row stops counting after 3 minutes.
  • One path, one endpoint. A request whose decoded path has a dot segment or an encoded slash is answered 400 before an endpoint is matched, so it cannot be priced as one endpoint and forwarded to another. Caller-sent x-x402fi-* headers are never forwarded.
  • The facilitator does not spend gas on transfers that pay nobody. /verify and /settle refuse a zero or sub-minimum amount (amount_below_minimum), a transfer to the payer itself (self_transfer) and a payTo that is not the payout wallet of a live or paused listing (pay_to_not_listed). Each payee gets 200 facilitator settlements per UTC day (payee_daily_settle_limit, HTTP 429; the FACILITATOR_DAILY_SETTLES var changes it), taken in one statement so a burst cannot pass it; the gateway's own settlements are not counted.
  • Upstream secret. Every forwarded paid call carries X-X402Fi-Secret (per listing, rotatable) so sellers can reject calls that bypass the paywall, plus X-X402Fi-Payer.
  • SSRF guard (src/lib/ssrf.ts). https only, port 443, no credentials, no localhost/.internal/etc. Private, link-local, CGNAT, documentation and multicast ranges are blocked in every notation, including IPv4-mapped (::ffff:127.0.0.1), IPv4-compatible and NAT64 IPv6. Every A/AAAA answer is resolved over DoH before fetching, redirects are not followed, and requests time out. Workers also run with global_fetch_strictly_public.
  • Native probes are unpaid, SSRF-guarded, time-limited, available only to signed-in sellers, and never send a payment header.
  • Contract endpoints are admin-only and capped at 600k gas per settlement, so nobody can point x402Fi's gas at an expensive contract.
  • Logos are proxied server-side, sniffed by magic bytes (PNG, JPEG, GIF, WebP only; no SVG), capped at 1 MB and served with content-security-policy: default-src 'none'; sandbox and nosniff. Viewing a listing never contacts the seller's host from the visitor's browser.
  • Profile links are https-only and rendered rel="noopener noreferrer nofollow ugc"; X links must be x.com/twitter.com profiles.
  • CSV export neutralizes spreadsheet formula injection.
  • Sessions are HMAC-signed, httpOnly, secure, sameSite=lax cookies issued after SIWE verification with one-time KV nonces.
  • Browser RPC proxies allow only read methods and eth_sendRawTransaction.

Public APIs

Gateway

{METHOD} https://x402fi.dev/g/<slug>/<path>. Standard x402 v2 as above. Status codes: 402 (pay; insufficient_funds_in_flight when the buyer's other calls in flight already use the balance), 200 (paid response), 307 (native endpoint: redirect to the seller's own URL, which the buyer pays directly), 400 (missing name for contract endpoints; or a path with a dot segment or an encoded slash), 404 (unknown listing or path; lists the endpoints), 405 (wrong method; Allow header), 409 (name unavailable, with reason), 413 (body over 1 MB), 429 (seller's daily cap), 502 (upstream error; not charged), 503 (chain unreachable or paused; retry, not charged).

Facilitator

EndpointBodyReturns
POST /api/facilitator/verify{ paymentPayload, paymentRequirements }{ isValid, payer } or { isValid:false, invalidReason }
POST /api/facilitator/settlesame{ success, transaction, network, payer } or { success:false, errorReason }. payTo must be a listing's payout wallet; 200 settlements per payee per UTC day, then 429.
GET /api/facilitator/supported—{ kinds:[{x402Version:2, scheme:"exact", network:"eip155:4663"}], extensions:["payee-name"] }

Discovery

GET /api/discovery/resources (also at /api/facilitator/discovery/resources, the path the official x402 SDKs query) returns one item per paid live endpoint in the Bazaar format: resource, accepts, extensions.bazaar (how to call it: method, query/path params, body, example output; a contract endpoint adds a routeTemplate), description, serviceName, tags, iconUrl, and metadata (name, description, category, method, pricing, priceIsCeiling, payeeName, listing; contract endpoints add settlement: "contract", contract, pathTemplate; native endpoints add settlement: "direct" and paymentHeader, with resource being the seller's own URL and accepts read from its live 402; a v1 native endpoint is an item with x402Version: 1 and a v1 option: maxAmountRequired, the seller's own network name such as robinhood, and paymentHeader: "X-PAYMENT"). The network=eip155:4663 filter also matches v1 items. Filters: type, payTo, scheme, network, extensions; pagination: limit (default 100, max 500) and offset. CORS-open. Readable view: /discovery.

llms.txt

GET /llms.txt (llmstxt.org Markdown): what x402Fi is, how an agent pays, links to the MCP server, feed and docs, and the live service list built from the discovery feed.

MCP server

https://x402fi.dev/mcp (Streamable HTTP, stateless, no auth): search_services, get_listing, get_payment_requirements. Read-only: it never pays, signs or calls a paid endpoint, and labels seller-written text as untrusted.

Listing helpers (signed-in sellers)

POST /api/listings/probe-native { url, method, body } reads a seller's own x402 endpoint once, unpaid, and returns its USDG / Robinhood Chain price, payTo, payee name and offered networks.

Security reviews

RouteWhoWhat
POST /api/reviewssigned-in listerRequest a review: { listingId, serviceIds?, repoUrl?, commit?, contact, note? } (default: every live endpoint).
PATCH /api/reviews/<serviceId>signed-in lister{ action: "fixes_submitted", commit, note? } after findings, or { action: "cancel" }.
POST /api/reviews/heyHEY (signed)Apply a signed state; GET describes the format and lists the configured signers.
GET /api/reviews/requestsHEY (Bearer HEY_REVIEW_FEED_TOKEN)Open requests with repo, commit, contact and endpoint details.
GET /api/reviews/proof/<serviceId>publicThe signed reviewed message, domain, types and signature, to check against HEY's published signer. 404 unless the endpoint is currently reviewed.

Data model

D1 (SQLite) via Drizzle, schema in src/db/schema.ts, migrations in migrations/.

TablePurpose
sellersWallets that signed in (checksummed address).
listingsA project: name, summary, description, category, upstream base URL, payout wallet, payee name, upstream secret, daily cap, profile (logo, website, X), status.
servicesEndpoints of a listing: method, path, pricing (free/fixed/quote/contract/native), price, quote path, ceiling, contract config, examples (incl. the JSON body used to probe a native POST endpoint), order, status.
facilitator_settlesSettlements the public facilitator paid gas for, per payee and UTC day (the daily budget).
paymentsThe ledger: listing, endpoint, payer, payee, amount, unique nonce, status (pending/settled/settle_failed/upstream_failed), tx hash, error, path, upstream status, latency.
reviewsOne security review per endpoint: state, lister's repo/commit/contact/note, last applied issuedAt, reviewed commit, report URL, reviewed target, signer, requested/updated times.
review_eventsEvery signed HEY message applied: endpoint, state, message JSON, signature, signer.

KV stores SIWE nonces (10 min), payee verdicts, ENS profiles, native-endpoint probes and Priors records (10 min each; failures 60 s).

Project structure

src/
  app/
    page.tsx                     landing page
    learn/ institutions/ developers/ discovery/ terms/ privacy/ disclaimer/
    market/                      marketplace + listing pages (TryIt)
    sell/new/                    6-step listing wizard (multi-endpoint, free or paid, example responses; HoodFi / x402 Identity name suggestions; review request)
    dashboard/                   seller dashboard + endpoint editor + review panel
    receipt/[id]/                public receipts
    g/[slug]/[[...path]]/        x402 gateway route
    mcp/                         MCP server endpoint (Streamable HTTP, stateless)
    llms.txt/                    /llms.txt, generated from the discovery feed
    og/listing/[slug]/           1200x630 share cards
    api/                         facilitator (+ discovery alias for the SDKs), discovery, auth, listings (+ probe-native), services, dashboard, payments CSV, logo, rpc, reviews
  components/                    header, footer, handshake explainer, cards, payee + Priors badges, review badge/card + home program card, wallet button, legal layout
  db/schema.ts                   Drizzle schema
  lib/
    chains.ts                    Robinhood Chain, USDG, coin type
    x402/                        types, encoding, money, requirements, EIP-712, facilitator, contract settlement, native 402 parser, bazaar extension
    gateway/                     handler + pure routing/quote helpers
    mcp/                         MCP tools (search, listing, payment requirements) + pure search ranking
    server/                      env bindings, chain clients, session, queries, payee, profile, discovery, native probe, Priors, validation
    client/                      wagmi/AppKit config, SIWE session hook, payee-record writers (ENS on Ethereum, HoodFi on Robinhood Chain)
    ssrf.ts  profile.ts  priors.ts  reviews.ts (review states, EIP-712 types, signed-message rules)
migrations/                      D1 SQL migrations
scripts/                         seed-demo.mjs, seed-hoodfi.mjs, pay-demo.mjs
test/                            Vitest unit tests

Local development

Requirements: Node 22, npm, a Cloudflare account with Wrangler logged in.

npm install
cp .dev.vars.example .dev.vars        # fill in the values (see below)
npm run db:migrate:local              # apply migrations to the local D1
node scripts/seed-demo.mjs 0xYourPayout   # optional: the $0.01 demo listing
npm run dev                           # http://localhost:3000

next dev gets D1/KV bindings through initOpenNextCloudflareForDev() in next.config.ts. To run the real Worker runtime locally: npm run preview.

Configuration and secrets

Secrets live in Cloudflare (wrangler secret put NAME) and locally in .dev.vars (gitignored). Never declare a secret's name under vars in wrangler.jsonc: a plain var shadows the secret of the same name.

NameRequiredPurpose
SESSION_SECRETyesHMAC key for session cookies (64 random hex).
SETTLEMENT_PRIVATE_KEYyesSettlement wallet: pays gas to submit payments. Holds ETH on Robinhood Chain only.
ROBINHOOD_RPC_URLstrongly recommendedDedicated Robinhood Chain RPC (e.g. Alchemy robinhood-mainnet). The public RPC rate-limits Cloudflare Workers.
MAINNET_RPC_URLrecommendedEthereum RPC for ENS reads (server-side key, no domain allowlist).
NEXT_PUBLIC_REOWN_PROJECT_IDoptionalReown/WalletConnect project ID (a default is built in).
HEY_REVIEW_SIGNERSfor reviewsComma-separated addresses allowed to sign review states (HEY's published signer; add the new one before removing the old when HEY rotates). Unset = signed states answer 503.
HEY_REVIEW_FEED_TOKENfor reviewsBearer token for HEY's GET /api/reviews/requests. Shared with HEY privately; rotate with a new wrangler secret put.

Plain vars in wrangler.jsonc: LISTING_TEXT_SCAN, DELIVERY_SCAN (listing scans), and optionally FACILITATOR_DAILY_SETTLES (default 200 per payee per UTC day).

Bindings (wrangler.jsonc): DB (D1 x402fi), KV, ASSETS. Custom domain x402fi.dev; workers_dev stays enabled.

Database migrations

npm run db:generate          # drizzle-kit: SQL from src/db/schema.ts
npm run db:migrate:local
npm run db:migrate:remote    # production D1

Apply additive migrations before deploying code that uses them. Data migrations (like 0001_services.sql, which turned each listing into its first endpoint) are appended to the generated SQL.

Deploying

npm run deploy     # opennextjs-cloudflare build && deploy
npm run upload     # build + upload a new version without promoting (preview URL)

Check the deploy log for Current Version ID. Static chunks are served with cache-control: public, max-age=31536000, immutable via public/_headers.

Testing

npm test           # Vitest
npm run typecheck

Unit tests cover the money math, the 402 shape, verification against signed authorizations (wrong amount, payee, expiry, reuse, balance, tampering, RPC failure = retryable), the SSRF guard (every blocked notation plus public controls), endpoint routing and quotes, label parsing, the price minimum, profile parsing, native 402 parsing (v1 and v2, header and body), Priors record parsing, and the review rules (signature recovery, other signers and tampered messages refused, replays, messages older than the lister's request or dated in the future, commit and report URL checks, identical public in-progress states, out of date on endpoint change, lister moves per state).

End-to-end checks that need no money: send a payment signed by a throwaway wallet with no funds. A healthy gateway answers 402 insufficient_funds; a 503 means the chain was unreachable. A real paid test: node --dns-result-order=ipv4first scripts/pay-demo.mjs (run by the wallet owner; refuses anything above $0.01).

Operations

  • Settlement wallet: keep a small ETH balance on Robinhood Chain. One payment costs ≈ 0.0000022 ETH; a HoodFi registration ≈ 0.000007 ETH.
  • Gas economics: x402Fi pays settlement gas so buyers need only USDG. The $0.01 minimum keeps each payment above its gas cost; batch settlement is the long-term path for sub-cent prices.
  • Pausing: sellers can pause a listing or a single endpoint from the dashboard. Endpoints with payments are paused rather than deleted so receipts stay valid.
  • Adding a contract endpoint (admin): insert a services row with pricing = 'contract', a ceiling and contract_config = {"address":"0x…","kind":"label-registrar","labelSuffix":".example.eth"}. Add org.x402.payto = eip155:4663:<contract> to the listing's payee name.
  • Email: contact@x402fi.dev forwards through Cloudflare Email Routing.

Known traps

TrapWhat happensFix in this repo
Robinhood public RPC from WorkersRate-limited per IP across Cloudflare's shared egress: ~5 of 6 verifications failedROBINHOOD_RPC_URL first, public and Blockscout fallbacks, retries, rank: false
Robinhood RPC CORSPOST responses carry a duplicated access-control-allow-origin: *,*; browsers drop themBrowser RPC goes through /api/rpc
USDG has no version()Wrong domain = every signature "invalid"Domain "Global Dollar", "1", confirmed against DOMAIN_SEPARATOR()
Drizzle correlated subqueriesInterpolated columns render unqualified; a per-listing count silently returned 0Explicit aliases in raw SQL (src/lib/server/queries.ts)
wrangler tailDelivered no events during debugging503 bodies carry a detail naming the failing step
ENSv2 getEnsResolverReturns a shared shim resolver, not the name's real oneRead the registry's resolver(node) when the resolver itself matters
createAppKit behind typeof windowuseAppKit() throws during prerenderCalled at module scope (src/components/Providers.tsx)
Optional wallet SDK imports@x402/* and mppx deep imports break the webpack buildAliased to false in next.config.ts
next/font variablesDefined on <body>, :root tokens can't see themFont variables on <html>
Logo URLs ending in .pngA CDN that negotiates by Accept served AgentFuel's icon-512.png as WebP, which the share-card renderer drops: the card had no logoCard logos are fetched without image/webp in Accept (fetchListingLogo(l, { forCard: true })); CARD_DESIGN bumps card URLs so X re-fetches
Ajv in the MCP SDK on WorkersAjv compiles validators with new Function, which Workers blockThe server uses the SDK's CfWorkerJsonSchemaValidator
Node on IPv6-broken networksfetch hangs connecting over IPv6node --dns-result-order=ipv4first for scripts

Reference values

Robinhood Chainchain ID 4663, CAIP-2 eip155:4663, explorer https://robinhoodchain.blockscout.com
USDG0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168, 6 decimals, issued by Paxos
ENS coin type (Robinhood Chain)2147488311
x402Fi settlement wallet0x79678f054624B50B6d2fB7b43D45c9402181ABEA (gas only)
HoodfiX402Registrar0x64A6439a05aa4c91c3ACE97842a98148888A2534
HoodFi registrar0x56be5565acc823f4195c2cf3b9046C083633209a
HoodFi L2 registry0xf2bABA012244bdD7445129597350054E1B3aEe5C
x402 Identity registrar (Ethereum)0xeb9e9ea385fe28b51a3f9a7d93fb893e0a1f9633
HEY review signer0x38DD416262A6dAE08470E4564A01cfE363143269 (check it at heyresearch.xyz/api/v1/security-review/signer)

Legal

x402Fi is operated by Only Buy Bitcoin LLC under the laws of Delaware, USA. It is software, not a bank, money transmitter, payment processor, exchange or custodian. USDG is issued by Paxos; x402Fi is not affiliated with Paxos, Robinhood, ENS, Coinbase or the x402 project.

License

Apache-2.0, see LICENSE and NOTICE. © 2026 Only Buy Bitcoin LLC. Contact: contact@x402fi.dev

No installation packages available.

Remote

streamable-http
https://x402fi.dev/mcp