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

README.md

# x402 Seller Kit v1.0

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 + /order + /claim + x402 v2 402 on /download + llms.txt
│   ├── orders.js              order/claim engine (unique amount + secret orderId, one-time claims, rate limits)
│   ├── config.js              the only file you must edit
│   ├── schema.sql             D1 tables: orders, claims, rate
│   ├── 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, plain-hash refusal
├── LICENSE.md
└── CHANGELOG.md
```

## How a sale works
1. The buyer clicks **Get my order**. `POST /order` returns a secret `orderId` and a unique exact amount, e.g. `29.004271` USDC. The order is stored in D1 with a 2-hour pay window.
2. The buyer sends exactly that amount of USDC on Base to your address, from any wallet or exchange.
3. The buyer pastes the tx hash. `POST /claim {orderId, txHash}` fetches the receipt from Base (5 RPC fallbacks), then checks all of the following:
   - the tx succeeded
   - **one** USDC `Transfer` log (from the real USDC contract) pays your address **exactly** the order amount
   - the tx was mined inside the order's window
   - the hash has never been claimed before
   If every check passes, the file streams back. The same order and hash can re-download up to 5 times, which covers failed downloads.

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-store-claims          # paste database_id into wrangler.toml
npx wrangler d1 execute my-store-claims --remote --file schema.sql
npx wrangler deploy
bash scripts/smoke-test.sh https://my-store.<you>.workers.dev
```

## 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 that works from any wallet or exchange.
- Front-running-safe claims: the order code plus a unique amount, because tx hashes are public.
- 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.
- Exact amounts: an exchange that subtracts its fee from the amount sent, or that won't accept 6 decimals, will produce a mismatch. The buyer then emails you and you check by hand. The page copy tells buyers how to avoid this.
- Agent auto-pay (x402 `PAYMENT-SIGNATURE` settlement) needs a facilitator. It isn't wired in; agents use `/order` + `/claim`.
- One file per Worker. For several products, deploy one Worker per product sharing one D1 (set a distinct `PRODUCT_KEY` and keep base prices at least 0.01 USDC apart).
- 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