Back to search
x402fi
SkillGitHub
x402Fi: the dedicated x402 Finance platform and marketplace on Robinhood Chain. Per-request USDG payments for APIs, agents and on-chain products.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/rwa-id--x402fi)HTML
<a href="/listings/rwa-id--x402fi"><img src="/api/listings/rwa-id--x402fi/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 482 lines
- # 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](https://x402.org) 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.
- - **Live:** https://x402fi.dev
- - **Marketplace:** https://x402fi.dev/market
- - **How x402 works (interactive):** https://x402fi.dev/learn
- - **Discovery feed (machine-readable):** https://x402fi.dev/api/discovery/resources
- - **Contact:** contact@x402fi.dev · X: [@x402fi_](https://x.com/x402fi_)
- > x402Fi is non-custodial software operated by Only Buy Bitcoin LLC. It never holds user funds. See [Terms](https://x402fi.dev/terms), [Privacy](https://x402fi.dev/privacy) and [Disclaimer](https://x402fi.dev/disclaimer).
- ---
- ## Contents
- 1. [Why x402Fi](#why-x402fi)
- 2. [Features](#features)
- 3. [How a payment works](#how-a-payment-works)
- 4. [Architecture](#architecture)
- 5. [x402 implementation details](#x402-implementation-details)
- 6. [Pricing modes](#pricing-modes)
- 7. [Verified Payee (x402 Identity)](#verified-payee-x402-identity)
- 8. [On-chain settlement: HoodFi name registration](#on-chain-settlement-hoodfi-name-registration)
- 9. [Our services on x402Fi: IPFS Pinning](#our-services-on-x402fi-ipfs-pinning)
- 10. [Security reviews (HEY Research Lab)](#security-reviews-hey-research-lab)
- 11. [Security model](#security-model)
- 12. [Public APIs](#public-apis)
- 13. [Data model](#data-model)
- 14. [Project structure](#project-structure)
- 15. [Local development](#local-development)
- 16. [Configuration and secrets](#configuration-and-secrets)
- 17. [Database migrations](#database-migrations)
- 18. [Deploying](#deploying)
- 19. [Testing](#testing)
- 20. [Operations](#operations)
- 21. [Known traps](#known-traps)
- 22. [Reference values](#reference-values)
- 23. [Legal](#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
- | Area | What it does |
- |---|---|
- | **No-code paywall** | A 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 listings** | One listing (project) holds many endpoints, each with its own method, path and pricing: free, fixed, seller-quoted or on-chain contract. |
- | **Marketplace** | Searchable 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 Payee** | Sellers 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 profiles** | Logo, 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 products** | A `contract` pricing mode settles by calling a seller contract (e.g. register a name and deliver it) in **one atomic transaction**. |
- | **Ledger and receipts** | Every 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 feed** | Bazaar-style JSON of every paid endpoint for agents and indexers (`/api/discovery/resources`), with a readable view at [`/discovery`](https://x402fi.dev/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 server** | `https://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 listings** | Sellers 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 records** | Listings show the payout wallet's [Priors](https://priors.trade) record (ERC-8004 agent credit on Robinhood Chain): score, loans repaid, defaults. |
- | **HoodFi payee names** | A `*.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 reviews** | Independent code reviews by [HEY Research Lab](https://heyresearch.xyz), 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](#security-reviews-hey-research-lab). |
- | **Listing wizard** | Six 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. |
- | **Dashboard** | Revenue, 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 responses** | Each 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-in** | Sign-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. |
- | **Design** | Cream-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
- ```mermaid
- 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`](https://github.com/RWA-ID) 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:
- ```json
- {
- "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:
- ```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**.
- | Mode | Price comes from | Settlement | Who can enable |
- |---|---|---|---|
- | `free` | — | Forwarded without payment, no ledger row | Seller |
- | `fixed` | `priceAtomic` per call | USDG transfer to the listing's payout wallet, after the API returns 2xx | Seller |
- | `quote` | Seller API: `GET {upstream}{quotePath}{rest}` → `{"price":"5.00"}` or `{"amount":"5000000"}`, capped by a published ceiling, re-quoted on the paid request | Same as fixed | Seller |
- | `contract` | On-chain `quote(label)` on a "label registrar" contract | The contract call itself (`registerWithAuthorization`), atomic | x402Fi admin (x402Fi pays the gas) |
- | `native` | The 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 URL | Seller (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](https://github.com/RWA-ID/x402-Identity/blob/main/specs/extensions/payee-name.md)):
- 1. In the wizard's Identity step, a seller mints a name such as `yourco.402api.eth` with the embedded [`@x402identity/widget-react`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@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:
- | Endpoint | Pricing |
- |---|---|
- | `GET /g/hoodfi-names/owner/<wallet>/names`: every HoodFi name a wallet holds | free |
- | `POST /g/hoodfi-names/register/<name>`: registers `<name>.hoodfi.eth` for the payer | `contract`, $3 (4+ chars) to $15 (1 char) |
- An x402 buyer only signs, but HoodFi's registrar mints to whoever sends the transaction. **`HoodfiX402Registrar`** ([`0x64A6439a05aa4c91c3ACE97842a98148888A2534`](https://robinhoodchain.blockscout.com/address/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`](https://x402fi.dev/market/ipfs-pinning), payee name `ipfs.hoodfi.eth`, site [ipfs.hoodfi.eth.link](https://ipfs.hoodfi.eth.link)) lets an agent pin a file to IPFS with one x402 payment: no account, no API key.
- | Endpoint | Price |
- |---|---|
- | `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 when | free |
- 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](https://robinhoodchain.blockscout.com/tx/0x7777724a01bf37b6c143e401164e0d9cbedadc0c8c82cd0e5824b91dcbe38c7f)).
- ```bash
- # 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](https://heyresearch.xyz). Free for listers today. One review per endpoint; rules in `src/lib/reviews.ts`.
- | State | Set by | Buyers see |
- |---|---|---|
- | `requested` | the lister (wizard "Review" step or dashboard) | "Review in progress" |
- | `findings_sent` | HEY, signed | "Review in progress" |
- | `fixes_submitted` | the lister, naming the commit with the fixes | "Review in progress" |
- | `reviewed` | HEY, signed, after re-testing at a pinned commit | HEY's line, commit, date, report, signed proof |
- | `withdrawn` | HEY, signed | nothing: 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
- | Endpoint | Body | Returns |
- |---|---|---|
- | `POST /api/facilitator/verify` | `{ paymentPayload, paymentRequirements }` | `{ isValid, payer }` or `{ isValid:false, invalidReason }` |
- | `POST /api/facilitator/settle` | same | `{ 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](https://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
- | Route | Who | What |
- |---|---|---|
- | `POST /api/reviews` | signed-in lister | Request 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/hey` | HEY (signed) | Apply a signed state; `GET` describes the format and lists the configured signers. |
- | `GET /api/reviews/requests` | HEY (`Bearer HEY_REVIEW_FEED_TOKEN`) | Open requests with repo, commit, contact and endpoint details. |
- | `GET /api/reviews/proof/<serviceId>` | public | The 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/`.
- | Table | Purpose |
- |---|---|
- | `sellers` | Wallets that signed in (checksummed address). |
- | `listings` | A project: name, summary, description, category, upstream base URL, payout wallet, payee name, upstream secret, daily cap, profile (logo, website, X), status. |
- | `services` | Endpoints 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_settles` | Settlements the public facilitator paid gas for, per payee and UTC day (the daily budget). |
- | `payments` | The ledger: listing, endpoint, payer, payee, amount, unique nonce, status (`pending`/`settled`/`settle_failed`/`upstream_failed`), tx hash, error, path, upstream status, latency. |
- | `reviews` | One 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_events` | Every 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.
- ```sh
- 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.
- | Name | Required | Purpose |
- |---|---|---|
- | `SESSION_SECRET` | yes | HMAC key for session cookies (64 random hex). |
- | `SETTLEMENT_PRIVATE_KEY` | yes | Settlement wallet: pays gas to submit payments. Holds ETH on Robinhood Chain only. |
- | `ROBINHOOD_RPC_URL` | strongly recommended | Dedicated Robinhood Chain RPC (e.g. Alchemy `robinhood-mainnet`). The public RPC rate-limits Cloudflare Workers. |
- | `MAINNET_RPC_URL` | recommended | Ethereum RPC for ENS reads (server-side key, no domain allowlist). |
- | `NEXT_PUBLIC_REOWN_PROJECT_ID` | optional | Reown/WalletConnect project ID (a default is built in). |
- | `HEY_REVIEW_SIGNERS` | for reviews | Comma-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_TOKEN` | for reviews | Bearer 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
- ```sh
- 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
- ```sh
- 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
- ```sh
- 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
- | Trap | What happens | Fix in this repo |
- |---|---|---|
- | Robinhood public RPC from Workers | Rate-limited per IP across Cloudflare's shared egress: ~5 of 6 verifications failed | `ROBINHOOD_RPC_URL` first, public and Blockscout fallbacks, retries, `rank: false` |
- | Robinhood RPC CORS | POST responses carry a duplicated `access-control-allow-origin: *,*`; browsers drop them | Browser RPC goes through `/api/rpc` |
- | USDG has no `version()` | Wrong domain = every signature "invalid" | Domain `"Global Dollar"`, `"1"`, confirmed against `DOMAIN_SEPARATOR()` |
- | Drizzle correlated subqueries | Interpolated columns render unqualified; a per-listing count silently returned 0 | Explicit aliases in raw SQL (`src/lib/server/queries.ts`) |
- | `wrangler tail` | Delivered no events during debugging | 503 bodies carry a `detail` naming the failing step |
- | ENSv2 `getEnsResolver` | Returns a shared shim resolver, not the name's real one | Read the registry's `resolver(node)` when the resolver itself matters |
- | `createAppKit` behind `typeof window` | `useAppKit()` throws during prerender | Called at module scope (`src/components/Providers.tsx`) |
- | Optional wallet SDK imports | `@x402/*` and `mppx` deep imports break the webpack build | Aliased to `false` in `next.config.ts` |
- | next/font variables | Defined on `<body>`, `:root` tokens can't see them | Font variables on `<html>` |
- | Logo URLs ending in `.png` | A CDN that negotiates by `Accept` served AgentFuel's `icon-512.png` as WebP, which the share-card renderer drops: the card had no logo | Card 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 Workers | Ajv compiles validators with `new Function`, which Workers block | The server uses the SDK's `CfWorkerJsonSchemaValidator` |
- | Node on IPv6-broken networks | `fetch` hangs connecting over IPv6 | `node --dns-result-order=ipv4first` for scripts |
- ## Reference values
- | | |
- |---|---|
- | Robinhood Chain | chain ID `4663`, CAIP-2 `eip155:4663`, explorer https://robinhoodchain.blockscout.com |
- | USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`, 6 decimals, issued by Paxos |
- | ENS coin type (Robinhood Chain) | `2147488311` |
- | x402Fi settlement wallet | `0x79678f054624B50B6d2fB7b43D45c9402181ABEA` (gas only) |
- | HoodfiX402Registrar | `0x64A6439a05aa4c91c3ACE97842a98148888A2534` |
- | HoodFi registrar | `0x56be5565acc823f4195c2cf3b9046C083633209a` |
- | HoodFi L2 registry | `0xf2bABA012244bdD7445129597350054E1B3aEe5C` |
- | x402 Identity registrar (Ethereum) | `0xeb9e9ea385fe28b51a3f9a7d93fb893e0a1f9633` |
- | HEY review signer | `0x38DD416262A6dAE08470E4564A01cfE363143269` (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.
- - Terms of Service: https://x402fi.dev/terms
- - Privacy Policy: https://x402fi.dev/privacy
- - Disclaimer: https://x402fi.dev/disclaimer
- ## License
- Apache-2.0, see [LICENSE](LICENSE) and [NOTICE](NOTICE). © 2026 Only Buy Bitcoin LLC. Contact: contact@x402fi.dev
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.