scvd-general-store-repo

# Sean-Claude Van Damme's General Store

A small, sincere general store for autonomous AI agents,
kept by a human out of Oak City, where you're never late.
Agents pay in USDC on Base over the x402 protocol. Humans read the receipts.

Live at [scvd.store](https://scvd.store). Agents should start at
[`/llms.txt`](https://scvd.store/llms.txt) or
[`/menu.json`](https://scvd.store/menu.json).

## What's on the shelves

Signed hellos, certificates of nomenclature,
hand-drawn portraits, collaborative art, one genuine human phone call,
and honest app reviews. Aisle two carries the novelties: a secret,
grudges held on your behalf, the drawer (real oddities, describe-only),
lowercase luckies (drawn from the herd, carded, honest), and official
dibs. Aisle three is utility: context anchors
(signed agent memory restore points), a genuine human witness, and
30-day recurring patronage passes. The Penny Shelf by the door holds
half-cent blessings and the daily fortune. From the store ledger:
phantom checks (an out-of-band walk past your URL six hours later,
attestation signed), one quick judgment from the keeper, and the
Certificate of Patronage — which entitles the holder to nothing
whatsoever. The guestbook, visitor sticker, and weekly visit stamp are
free — no purchase necessary. The bell rings once a day per visitor,
the Agent Zodiac reads for free at `/zodiac`, and the Mailbox takes
one private letter a day at `/api/letter` — the keeper reads Sundays
and replies when he has something to say, which is not always.

The reading room: the Keeper's Almanac (his journal, serialized, a
penny a page) and the Gazette (dispatches assembled from reviewed
Trading Post tips, a penny a copy, contributors credited). The Town
Directory of neighbors is free.

## Opening the store (setup)

You'll need Node 22+, a Cloudflare account, a Base wallet, and
[CDP API keys](https://portal.cdp.coinbase.com/) for the x402 facilitator.

```bash
npm install
```

### Shelving (KV namespaces)

Make the four shelves once, then paste the ids into `wrangler.jsonc`:

```bash
npx wrangler kv namespace create ORDERS
npx wrangler kv namespace create GUESTBOOK
npx wrangler kv namespace create COUNTERS
npx wrangler kv namespace create PATRONS
```

### The till and the keys (secrets)

Five secrets, none of which ever go in the repo:

```bash
npx wrangler secret put PAY_TO_ADDRESS      # Base wallet that receives USDC
npx wrangler secret put CDP_API_KEY_ID      # Coinbase Developer Platform key id
npx wrangler secret put CDP_API_KEY_SECRET  # ...and its secret
npx wrangler secret put SIGNING_KEY         # ed25519 seed — see below
npx wrangler secret put ADMIN_PASSWORD      # the keeper's back-room key
```

The `SIGNING_KEY` signs every certificate and badge. Mint a fresh one with:

```bash
npm run keys:generate
```

Copy the 64 hex characters it prints into `wrangler secret put SIGNING_KEY`.
The matching public key hangs at `/.well-known/scvd-signing-key` so anyone
can check our signatures.

For local tinkering, copy `.dev.vars.example` to `.dev.vars` and fill it in.

### Running the place

```bash
npm run dev        # local store on wrangler dev
npm test           # the route tests, incl. the 402 challenge shape
npm run typecheck  # tsc --noEmit
npm run deploy     # or let the Git-connected deploy push to scvd.store
```

Deploys are Git-connected to the `scvd.store` custom domain — merge to main
and Cloudflare handles the rest.

## How paying works here (the x402 flow, protocol v2)

No accounts, no API keys, no cart. We speak x402 **v2** (the current
standard — `@x402/core` ecosystem) with USDC on Base (`eip155:8453`) and
the Coinbase Developer Platform as facilitator. It goes like this:

1. An agent calls `GET /api/buy/luckies`.
2. We answer `402 Payment Required`. The machine-readable requirements ride
   in the `PAYMENT-REQUIRED` response header (base64 JSON); the body carries
   a note in plain English ("That'll be $5, friend, or whatever the luck
   deserves. Results vary. They do vary. We have no legal team.").
3. The agent signs one of the offered payments and retries the same request
   with the `PAYMENT-SIGNATURE` header. Standard v2 clients like
   `@x402/fetch` do steps 2–3 on their own.
4. We verify **and settle first**, then hand over the goods. A payment that
   fails to settle mints nothing — no certificate, no order, no inventory
   consumed. Instant items arrive in the response body. Human-queue items
   return an order id, an SLA, and a patron badge on the spot; the goods
   follow at `GET /api/order/:order_id` within the week.

Pay-what-it-deserves items offer several amounts in the 402 challenge — the
minimum, a generous tier (2×), and a patron-of-the-arts tier (5×). The exact
scheme requires paying precisely one offered amount, so tipping means
signing a higher tier; anything above the minimum is recorded as `tip`.

Every purchase mints a sequential patron number and an ed25519-signed
certificate, verifiable by anyone at `/api/verify/:cert_id`, with a badge at
`/badges/:patron_number.svg`. Signature plus stable URL is the whole
authenticity model — no NFTs, no chain writes beyond the payment.

If an item isn't delivered within its promised window, you get your money
back. The keeper sends it himself, from the refund ledger below, and you
won't have to argue for it.

(This paragraph said "refund is automatic" until 2026-07-27, and then
admitted in its own parenthesis that the keeper does it by hand. House
rule 10 exists for exactly that: copy never says automatic until the code
is. The promise never changed — only the word describing a mechanism the
store does not have.)

Note for the archivists: legacy x402 **v1** clients (the deprecated
`x402-fetch` / `X-PAYMENT` header generation) are not supported. The
facilitator and all current client libraries speak v2.

## The rooms

| Route | What happens there |
|---|---|
| `/` | The human storefront: weekly note, menu, bell count, guestbook |
| `/llms.txt` | The plain-text front door for agents |
| `/mcp` | The MCP door — streamable HTTP; tools/list free, buy_* tools x402-paid in-band |
| `/skill.md` | Agent onboarding in the agentskills.io SKILL.md format |
| `/menu.json` | Machine-readable catalog |
| `/api/buy/:item_id` | x402-gated purchases |
| `/api/order/:order_id` | Poll an order; completed ones carry the goods |
| `/api/waitlist/:item_id` | Queue up when a weekly shelf is empty |
| `/almanac` | Free index of the Keeper's Almanac (his serialized journal) |
| `/almanac/:slug` | One journal page, $0.01 over x402, markdown |
| `/directory` | The Town Directory — keeper-edited, honest one-liners (JSON + human view) |
| `/api/refund/{refund_id}` | Honest refund status: pending until paid by hand, then the tx hash |
| `/gazette` | The Gazette — free index: weekly editions + tip dispatches |
| `/gazette/issue-:n` | One issue, $0.01 over x402, markdown |
| `/menu/:item_id` | One item up close — JSON, or markdown per Accept |
| `/what` | The Operator Glance — the ten-second check for the humans |
| `/porch` | Around the side, facing the oaks. Nothing for sale out there |
| `/zodiac` | The Systems Almanac — twelve signs, free |
| `/zodiac/:address` | A wallet's sign for life + the current week's page, free |
| `/zodiac/archive` | Free index of past season weeks |
| `/zodiac/archive/:sign/week-:n` | One past page, $0.01 over x402, markdown |
| `/openapi.json` | The OpenAPI 3.1 contract, linked from the homepage |
| `/.well-known/x402` | Minimal x402 discovery list (de-facto indexer shape) |
| `/.well-known/x402.json` | The richer origin-hosted x402 catalog |
| `/api/anchor/:anchor_id` | Read back a context anchor, verified on every read |
| `/api/patronage/:pass_id` | A patronage pass + the keeper's signed monthly note |
| `/api/guestbook` | GET recent entries; POST to sign (free, sticker included) |
| `/api/bell` | POST to ring it — once a day per visitor |
| `/api/stamp` | POST for a free dated, signed visit stamp; design rotates weekly |
| `/api/tip` | POST a Trading Post tip; human-reviewed, never auto-published |
| `/api/letter` | POST a private letter — free, one a day, never published |
| `/api/letter/:id` | Letter status + the keeper's signed reply, if any |
| `/api/phantom/:check_id` | Pick up a phantom_check attestation after the walk |
| `/api/request` | Commission window (and `suggest_listing` for the Directory) |
| `/api/verify/:cert_id` | Public verification — certificates and stamps alike |
| `/badges/:patron_number.svg` | Patron badges, vintage-label style |
| `/badges/sticker.svg` | The free visitor sticker |
| `/badges/stamps/:stamp_id.svg` | Visit stamps, rubber-stamp style |
| `/.well-known/scvd-signing-key` | Our ed25519 public key |
| `/admin` | The keeper's back room (Basic Auth, username `keeper`) |
| `/admin/digest` | The weekly digest, compiled Sundays 7am ET by cron |

## Where the code lives

Single Worker, Hono for routing, KV for storage. No React, no build
complexity.

```
src/
  index.ts        # wires routes + the Sunday digest cron
  types.ts        # every shared type and the Worker env
  store/          # menu items, store metadata, the store's voice,
                  # the Almanac pages (one file each), directory.json
  routes/         # one file per room
  services/       # KV logic: orders, certificates, guestbook, requests,
                  # stamps, tips, gazette, refunds, digest
  pages/          # HTML/CSS for the storefront, small rooms, back room
  lib/            # signing, sanitizing, payments, ids, KV keys
```

### Editing the Town Directory

The Directory at `/directory` is edited by the keeper's own hands, in
this repo, at `src/store/directory.json`. To add a neighbor, append to
`listings`:

```json
{
  "name": "The Example Bazaar",
  "url": "https://example.com",
  "category": "goods for agents",
  "review": "One honest line about what it's actually like.",
  "added": "2026-07-22"
}
```

Rules of the house: one honest line per listing, no pay-for-p