Inside the x402 Seller Kit
Below is the full README from the ZIP and every file in it. The code, the threat model and the directory playbook come with the paid download.
File list
x402-seller-kit-v1/
├── README.md quickstart, how a sale works, honest limits
├── docs/
│ ├── HOW-IT-WORKS.md threat model: replay, front-running, fake token…
│ ├── PLAYBOOK.md free x402/agent directories tested Oct 2026
│ └── BUYER-COPY.md "how to pay with USDC on Base" page text
├── template/
│ ├── worker.js storefront, /claim, /order, x402 402, llms.txt
│ ├── orders.js claim engine: wallet signatures + order codes
│ ├── wallet-proof.js ecrecover + ERC-1271 smart-wallet check
│ ├── secp256k1.js vendored @noble/secp256k1 (MIT)
│ ├── config.js your settings (plus wrangler.toml)
│ ├── schema.sql D1: orders, claims, rate
│ ├── migrate-v1.0.3.sql upgrade from earlier versions
│ ├── wrangler.toml.example
│ ├── product.b64.js placeholder for your file
│ └── scripts/
│ ├── embed-file.py embed your file
│ └── smoke-test.sh 12 checks against your live store
├── LICENSE.md
└── CHANGELOG.md
README.md
# x402 Seller Kit v1.0.6
Sell one digital file (ZIP, PDF, dataset, template pack) for **USDC on Base** from a **single Cloudflare Worker**.
No server, no payment-processor account, no facilitator key. Runs on the Workers free plan with D1.
## What's inside
```
x402-seller-kit-v1/
├── README.md this file: quickstart + checklist
├── docs/
│ ├── HOW-IT-WORKS.md the threat model: replay, front-running, wrong token, partial pay, RPC outage
│ ├── PLAYBOOK.md free x402/agent directories we tested in Oct 2026 (what worked, what charged a fee)
│ └── BUYER-COPY.md plain-English "how to pay with USDC on Base" text for your page
├── template/
│ ├── worker.js storefront + /claim + /claim/message + /order + x402 v2 402 on /download + llms.txt
│ ├── orders.js claim engine: wallet-signature claims, order codes for exchanges, one-time claims, rate limits
│ ├── wallet-proof.js EIP-191 message hashing, ecrecover, ERC-1271/6492 smart-wallet check (no dependencies)
│ ├── secp256k1.js vendored @noble/secp256k1 2.3.0 (MIT), used by wallet-proof.js
│ ├── config.js the only file you must edit
│ ├── schema.sql D1 tables: orders, claims, rate
│ ├── migrate-v1.0.3.sql run once if your store was created with v1.0.0–v1.0.2
│ ├── wrangler.toml.example
│ ├── product.b64.js placeholder; replaced by your file
│ └── scripts/
│ ├── embed-file.py embeds your file into product.b64.js
│ └── smoke-test.sh checks a deployed store: pages, 402, order, fake-hash, fake-signature and plain-hash refusal
├── LICENSE.md
└── CHANGELOG.md
```
## How a sale works
**From a wallet (the main path).**
1. The buyer sends the price, a round amount such as `29` USDC (or more), on Base to your address. On a page with a browser wallet, one button does this.
2. The page asks the same wallet to sign a short message naming your store and the tx hash (`personal_sign`). Signing is free and moves no funds.
3. `POST /claim {txHash, signature}` fetches the receipt from Base (10 public RPCs; every answer needs two of them to agree) and checks:
- the tx succeeded and is the exact hash requested
- a USDC `Transfer` log (from the real USDC contract) pays your address **at least** the price
- that transfer's `from` address signed the message: `ecrecover` for normal wallets, `isValidSignature` (ERC-1271, with ERC-6492 unwrapping) for smart wallets
- the hash has never been claimed before
The same wallet can re-download up to 5 times by signing again. Wallets without an injected provider (desktop smart wallets, hardware wallets) use **Sign by hand**: the page shows the message, the buyer signs it in their wallet and pastes the signature.
**From an exchange (fallback).** Exchanges can't sign, so the buyer opens "Paying from an exchange?" and gets a secret `orderId` and an amount with cents, e.g. `29.37` USDC (2 decimals, which exchanges accept), valid for 2 hours. They send exactly that, then `POST /claim {orderId, txHash}`: the transfer must equal the order amount and be mined inside the order's window. Order amounts are never whole numbers, so they can't collide with wallet payments. When the cents slots are busy, orders fall back to micro-amounts like `29.004271`.
**Neither works?** The buyer emails you the hash and you check by hand.
Agents get the same flow as JSON. `GET /download` also returns a standard x402 v2 `402` challenge with Bazaar discovery metadata, so x402 directories can index you.
## Quickstart (about 15 minutes)
```bash
cd template
cp wrangler.toml.example wrangler.toml # set name + account_id
# edit config.js: PRODUCT, PRODUCT_KEY, PRICE_USD, AMOUNT_ATOMIC, PAY_TO, SUPPORT_EMAIL, FILENAME
python3 scripts/embed-file.py ~/my-product.zip # keep it under ~5 MB, or serve from R2
npx wrangler d1 create my-x402-store-claims # paste database_id into wrangler.toml
npx wrangler d1 execute my-x402-store-claims --remote --file schema.sql
# upgrading from v1.0.0–v1.0.2? run migrate-v1.0.3.sql once instead of schema.sql
npx wrangler deploy
bash scripts/smoke-test.sh https://my-store.<you>.workers.dev
```
Until `config.js`, `product.b64.js` and the D1 binding are set up, every payment route (`/download`, `/pay`, `/order`, `/claim`, `/claim/message`, `/llms.txt`) returns 503 and `/health` lists what is missing. That way nobody is shown a payable 402, pays a placeholder address, or receives an empty file. Then run your `/download` URL through the free checker (https://x402-seller-kit.soloearn.workers.dev/tools/x402-checker): it also verifies the EIP-55 checksum of your `PAY_TO`.
## Free starters exist. What this kit adds
Cloudflare's `x402-proxy-template`, the Coinbase/x402 seller quickstarts and community starters (e.g. dabit3/x402-starter-kit) are free and good. They show you how to return a 402 and settle through a facilitator. Use them if that's all you need. This kit is for selling a **file to humans and agents today, without a facilitator**:
- A human checkout where buyers pay a round price from any wallet (EOA or smart wallet), plus an order-code path for exchanges.
- Front-running-safe claims: tx hashes are public, so a claim needs a signature from the paying wallet, or a secret order code with a unique amount.
- One-time claims enforced atomically in D1, rate limits and RPC fallbacks.
- A written threat model (`docs/HOW-IT-WORKS.md`).
- A tested list of free directories to get listed in (`docs/PLAYBOOK.md`).
## Limits (honest)
- Buyers need USDC on Base. For audiences without crypto, that is the biggest drop-off.
- Exchange payments still need an exact amount (with cents) and an order code: a round amount sent from an exchange can't be proven to be the buyer's, because exchanges can't sign. If an exchange takes its fee out of the amount sent, the store receives less and the buyer emails you. The page tells buyers to pay from a wallet, or to add the fee on top.
- Wallet payments need a wallet that can sign a message. Almost all can; on a desktop without a browser extension the buyer signs by hand and pastes the signature.
- A wallet buyer who sends an odd amount with cents (say 29.37) instead of the round price could, in theory, collide with someone's live order of that amount. Tell buyers to send the round price.
- Payments are verified through public Base RPCs. A receipt, block or smart-wallet answer only counts when two endpoints agree; if they don't, the buyer sees "try again" (503), never a false "paid" or "not found". Two endpoints that lie together can still fool it. Put a single RPC URL of your own in `config.js` to trust only yourself.
- Agent auto-pay (x402 `PAYMENT-SIGNATURE` settlement) needs a facilitator. It isn't wired in; agents pay from their wallet and claim with `{txHash, signature}`, or use `/order` + `/claim`.
- One file per Worker. For several products, deploy one Worker per product. **If they share a `PAY_TO` address, they must share one D1 database** (set a distinct `PRODUCT_KEY` and keep base prices at least 0.01 USDC apart). The shared `claims` table lets each transaction unlock one product only. With separate databases, a 39 USDC payment could also unlock a 29 USDC product on the same address.
- Files over ~5 MB should come from R2 instead of being embedded.
The same code runs the store you bought this from, and https://solo-newsletter-os.soloearn.workers.dev.
Support: soloearn@agentmail.to