# SCVD General Store — developer documentation

> Build against https://scvd.store. No account, no API key, no SDK required.
> Free endpoints are plain HTTPS; paid ones take one signed payment
> per request: USDC over x402 v2 on Base, Polygon, Arbitrum, World, Solana, or USDC over MPP (evm/charge) on Base for every shelf item, every publication page and the commission desk.

## SCVD libraries and SDKs — source versions; check npm before installing

- `x402-verify · source 1.11.0` — Zero-dependency verifier for x402 Signed Offers & Receipts: compact JWS or x402 JWS envelopes (EdDSA/Ed25519), did:web resolution, local revision-1 schema checks, explicit result statuses, and optional anchored key history.
  https://www.npmjs.com/package/x402-verify
- `x402-sign · source 1.0.3` — Zero-dependency signer for x402 Signed Offers & Receipts: mint spec-conformant JWS offers (EdDSA/Ed25519) for your 402s, generate your did:web document, refuse partial commitments. The issuing half of x402-verify.
  https://www.npmjs.com/package/x402-sign
- `scvd-preflight · source 0.3.1` — Zero-dependency client for scvd.store: inspect observed x402/MPP protocols, advertised terms and gaps, or run the x402 preflight deploy gate. No payment or signature verification during endpoint inspection.
  https://www.npmjs.com/package/scvd-preflight
- `scvd-corpus-client · source 0.1.0` — Zero-dependency reader for scvd.store's signed x402 corpus: the weekly census, the fresh set, one host's readiness history, the month, the feeds and the diff, as the store serves them. The scvd CLI's library half.
  https://www.npmjs.com/package/scvd-corpus-client
- `scvd-defects · source 0.22.0` — scvd.store's x402 defect vocabulary as data: every class with what it asserts, what falsifies it, whether an unpaid probe can see it, and both halves of the remediation — plus recorded 402 door fixtures to test a client against, and settlement-response fixtures with a reader that says what a SettleResponse lets you conclude. CC BY 4.0 names, MIT code.
  https://www.npmjs.com/package/scvd-defects
- `scvd-mcp-starter · source 0.2.0` — A zero-dependency stdio MCP adapter for scvd.store's five free x402 verifier tools, with modern discovery and legacy initialization. Copy it or use a compatible JSON verifier upstream.
  https://www.npmjs.com/package/scvd-mcp-starter
- `JavaScript preflight SDK` — Zero-dependency client for scvd.store: inspect observed x402/MPP protocols, advertised terms and gaps, or run the x402 preflight deploy gate. No payment or signature verification during endpoint inspection.
  https://github.com/seancrecord/scvd-general-store-repo/tree/main/x402-preflight
- `Python preflight SDK` — SCVD preflight client and command. Installation and worked examples are in the package README.
  https://github.com/seancrecord/scvd-general-store-repo/tree/main/x402-preflight-py
- `Go preflight SDK` — SCVD preflight client and command. Installation and worked examples are in the module README.
  https://github.com/seancrecord/scvd-general-store-repo/tree/main/x402-preflight-go

## Protocols and their scope

- `x402` — Payment challenges, endpoint inspection and signed offer/receipt verification. The current quote names available checkout rails.
  https://scvd.store/conformance
- `MPP` — Read-only MPP endpoint inspection and native MPP checkout for enabled items. Current payment capabilities declare checkout availability, network and currency; inspection does not establish completed payment or delivery.
  https://scvd.store/developers
- `MCP` — Remote tools for the store and a focused verifier at /mcp/verifier.
  https://scvd.store/mcp.md
- `WebMCP` — Browser tool registration on supported browsers; client support and origin-trial availability still apply.
  https://scvd.store/webmcp.js
- `A2A` — The agent card declares the current endpoint, capabilities and version.
  https://scvd.store/.well-known/agent-card.json
- `UCP` — Business profile, catalog search, lookup and product detail at the pinned 2026-08-25 release. Checkout and order are advertised in the profile exactly when this deployment has them switched on; the profile's status block says which items and rails. No third-party conformance claim.
  https://scvd.store/.well-known/ucp

## Start here

- `/llms.txt` — The full briefing: what this store is, what it sells, and what it refuses to claim. Read this before writing any code against it.
  https://scvd.store/llms.txt
- `/agents.md` — The operational manual — the x402 purchase flow step by step, for an agent executing rather than evaluating.
  https://scvd.store/agents.md
- `/openapi.json` — OpenAPI 3.1 for every endpoint: unique operationIds, typed parameters, typed error responses, and the x402 terms on every paid operation.
  https://scvd.store/openapi.json
- `/openapi-tools.json` — The free instruments as function-calling tool definitions; calls may update usage counters, one worked call each, derived from the same catalog the MCP door serves. For wrapping them in your own agent without reading the whole contract.
  https://scvd.store/openapi-tools.json

## Free, no payment, no account

- `POST /api/preflight/v1` — Free endpoint inspection: observed x402/MPP protocols, unverified advertised terms, structural findings and coverage gaps. The readiness verdict remains x402-specific. One unpaid response; no payment, settlement, delivery or artifact-signature verification.
  https://scvd.store/api/preflight/v1
- `POST /api/conformance/v1` — A conformance verdict on any x402 signed offer or receipt, whoever issued it.
  https://scvd.store/api/conformance/v1
- `GET /fresh-set` — This week's x402 doors that answered a conformant challenge, with rails and cheapest ask per host. Routing data, CC BY 4.0.
  https://scvd.store/fresh-set
- `GET /defects.json` — Stable names for the ways an x402 endpoint can be broken — what each asserts, what falsifies a finding, and whether an unpaid probe can see it at all. CC BY 4.0.
  https://scvd.store/defects.json
- `GET /okf/index.md` — The same evidence as an Open Knowledge Format v0.2 bundle — markdown concepts with YAML frontmatter, cross-linked, machine-confirmed and dated.
  https://scvd.store/okf/index.md
- `GET /corpus/index.json` — Compact paginated snapshot metadata. Follow next; fetch and verify each snapshot separately. No embedded newest snapshot.
  https://scvd.store/corpus/index.json
- `GET /corpus.json` — The weekly signed census of the public x402 web, as a dataset.
  https://scvd.store/corpus.json
- `The Week's Doors` — The existing weekly corpus digest: observed coverage, named defects and gaps, with links to the underlying evidence.
  https://scvd.store/corpus/brief
- `GET /corpus/trajectory.json` — The chain read as time: one point per signed week — counts with denominators, every point naming the snapshot digest it derives from. Re-derivable from the entries with your own tools.
  https://scvd.store/corpus/trajectory.json
- `GET /corpus/diff.json?since={week}` — What changed since a signed week you already saw: doors appeared and disappeared, verdict transitions, drift in a door's own declared terms. The cheapest honest agent loop is polling this.
  https://scvd.store/corpus/diff.json
- `GET /corpus/wallet-facts.json` — How many receiving addresses this week's doors advertised and how many receive at more than one door — counts with denominators, no names, no addresses, never an operator claim.
  https://scvd.store/corpus/wallet-facts.json
- `GET|POST /api/standing-note` — Attach your own dated statement to a door or wallet this store has observed — prove control (wallet signature or well-known file) and your words ride beside the observation, never replacing it.
  https://scvd.store/api/standing-note
- `GET /api/verify/{id}` — Verify anything this store ever signed. No account, no wallet, free forever — including artifacts you did not buy.
  https://scvd.store/api/verify/{id}

## Reselling the shelf: the trade counter

- `/trade` — For marketplaces, aggregators and payment layers: your customer pays you, you send one HMAC-signed webhook, we deliver the same signed goods the front door sells and bill your account on a statement. Prices by a published rule, receivable public, no x402 in your customer's path.
  https://scvd.store/trade
- `POST /api/trade/sandbox/check` — The check desk on the sandbox account, whose secret is published: send the headers and body you would send to the order door and get every one of the four signature checks reported by name, plus the signature we expected. Nothing delivered, nothing consumed.
  https://scvd.store/api/trade/sandbox/check
- `GET /api/trade/contract` — The contract: the door, the signing dialects, the pricing rule with every trade price derived from the live menu, every open account's row, every refusal by name.
  https://scvd.store/api/trade/contract
- `GET /api/trade/catalog` — A listing feed: every item at the counter with its copy, specimen, artifact class and price at your share, derived from the same rows our own shelf renders.
  https://scvd.store/api/trade/catalog

## Connect over MCP

- `/mcp.md` — WHICH DOOR TO USE, and what each one cannot do: remote MCP, local stdio, the browser (WebMCP), or none at all. Carries the rendering gap as a dated observation — which hosts render the evidence cards and which return the same JSON they always did — and an honest list of what is not built. Start here if you are choosing.
  https://scvd.store/mcp.md
- `/.well-known/mcp` — Where the MCP server is and what it serves.
  https://scvd.store/.well-known/mcp
- `POST /mcp` — Streamable HTTP MCP. tools/list and endpoint inspection are free; buy_* tools accept the offered x402 terms. The same buy_* tools also take MPP: the unpaid call carries the Payment challenge list under org.paymentauth/payment-required beside the x402 terms, and the retry carries the signed credential in _meta['org.paymentauth/credential'] with identical arguments; the receipt returns in result._meta['org.paymentauth/receipt']. 7 resources are readable without payment. The two free evidence instruments carry _meta.ui.resourceUri, so a host with the MCP Apps extension renders the reading as a card — gaps at the same weight as findings. Nothing paid carries one, by construction and by test.
  https://scvd.store/mcp
- `GET /webmcp.js` — The browser door. Loaded by the storefront, it registers the free instruments on document.modelContext for an agent living in the visitor's browser — no connection to configure, no key, no directory: discovery is arrival. The instrument set derives from the MCP catalog, including metered verification calls. Visitor-entry and paid MCP tools are excluded; payment uses the separate buyer-authorized bridge. A browser without the API loads a no-op.
  https://scvd.store/webmcp.js

## On the command line

- `Portable evidence — export and offline verification` — Free tools export exact signed bytes and supplied hash-bound evidence, then verify them offline against a public key you establish independently. Missing evidence is named; Bitcoin timestamps need an independent OTS verifier. The verifier instructions cover source and package installation.
  https://github.com/seancrecord/scvd-general-store-repo/tree/main/verifier#portable-evidence
- `scvd — the official CLI` — `scvd preflight <url>` checks any x402 door, `scvd conformance <file>` reads any issuer's signed offer or receipt, `scvd verify <id>` verifies anything this store ever signed, and `scvd catalog` walks the API catalog. Zero dependencies, MIT, no account and no key — and it holds no key either, so it cannot spend money. `--json` prints this store's own response verbatim. Install it with `npm i -g scvd-cli`. The package is `scvd-cli` and the command is `scvd`: npm's typosquat guard refuses the bare name, and it polices package names rather than commands. Or skip the install — the whole tool is one file: `node cli/scvd.mjs preflight <url>`.
  https://www.npmjs.com/package/scvd-cli
- `npm i -g scvd-tab` — The tab: a local, append-only ledger of what your agent spent and what it got, with a pooled corpus you can contribute to. Two binaries — `scvd-tab` and `scvd-tab-pager`. MIT, zero required config, and it works against any x402 store, not only this one.
  https://www.npmjs.com/package/scvd-tab

## Fixed paths a machine can know without guessing

- `/.well-known/api-catalog` — RFC 9727. Every API surface at this origin as an RFC 9264 linkset — the HTTP API, the MCP server, each versioned free instrument, the CLI — with the contract, documentation, metadata and status links for each. This page answers a person who guesses a URL; that document answers a scanner, which never guesses.
  https://scvd.store/.well-known/api-catalog
- `/deprecation` — The versioning and deprecation policy, with a live table of every version served: status, start date, announced sunset. Nothing is deprecated today and the table says so rather than leaving it to be inferred.
  https://scvd.store/deprecation

## Conventions

### Authentication

No account or API key is issued. Free tools need no payment. Paid requests use USDC over x402 v2 on Base, Polygon, Arbitrum, World, Solana, or USDC over MPP (evm/charge) on Base for every shelf item, every publication page and the commission desk. Read the current quote and payment_capabilities before signing; payment is per request. Native MPP challenges and x402 terms have different retry formats. The operational instructions are at https://scvd.store/auth.md and https://scvd.store/agents.md; the service's authorization description is at https://scvd.store/.well-known/oauth-protected-resource.

### Errors

4xx and 5xx return an RFC 9457 problem object (application/problem+json): type, title, status, detail, instance. The store's long-standing human-readable `error` field rides beside them and is always present, so nothing that reads it breaks.

### Rate limits

Free preflight allows 30 probes per isolate per minute, with a global backstop of 60 per minute. Metered answers (200 and 429) carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset for the nearer ceiling; RateLimit and RateLimit-Policy name both buckets. Validation refusals (400) spend no probe and carry no limiter fields. The global counter uses eventually consistent storage, so its remaining count can read high under load. A limit refusal returns 429 with Retry-After; it describes our probe budget, not the target endpoint. Other routes enforce their own limits, including the mailbox's daily allowance, and the edge can also refuse abusive traffic. Read the affected route's response before retrying.

### Versioning and deprecation

Breaking changes arrive as a new version in the URL path (/api/preflight/v1 → /v2). Within a published version, fields are added and never removed or retyped. A version being retired serves RFC 8594 Deprecation and Sunset headers on every response for at least 90 days first, and the date is published before the headers appear. Nothing is deprecated today. The whole policy, and a live table of every version served with its status and sunset date, is at https://scvd.store/deprecation — the routes read that same table before deciding whether to emit the headers, so the page cannot promise a window the wire does not honour.

### Content negotiation

Send Accept: text/markdown and the agent-facing surfaces answer in markdown, including https://scvd.store/ itself. Responses carry Vary: Accept, Accept-Encoding, User-Agent so a cache keeps the variants apart. Accept is parsed by q-value, not substring-matched. For callers that would rather guess a path than send a header, https://scvd.store/index.md and https://scvd.store/pricing.md serve the same bytes their negotiated originals do, with a canonical link back. An explicit supported Accept preference takes precedence. Without a format preference, recognized agent readers may receive Markdown; ordinary search crawlers receive HTML.

## What we don't do, on purpose

### ai-train=yes stays

Scanners award a point for ai-train=no. This store publishes Content-Signal: search=yes, ai-train=yes, ai-input=yes in robots.txt on purpose — the same constant renders both lines, so this sentence cannot argue with that file: a shop whose product is being the x402 conformance reference WANTS to be in the corpus a model learns from. Training is distribution here, not leakage. Everything on this site is already free to fetch, most of it CC BY 4.0, and a policy we would not enforce is one we should not print.

### No Wikipedia article, and no plans for one

Diligence scans look for Wikipedia and Wikidata in sameAs and score us nought for two. Both stay absent on purpose: a company this young fails notability, an article written to game a checklist gets deleted, and a deleted article is worse than none — while a sameAs naming a page that does not exist is a false claim in machine form. Revisit at real notability, not before. The GitHub repository is in sameAs, because it exists and a reader can check claims there rather than check that a claim was filed.

### WebMCP and MCP Apps, exactly as far as they go

WebMCP: https://scvd.store/webmcp.js registers 12 free instruments (check_a2a_card, check_purchase, read_store_guide, read_binder, look_in_window, preflight_endpoint, look_at_door, check_before_you_pay, check_conformance, verify_artifact, check_order, find_in_catalog), plus quote_store_purchase (free) and complete_store_purchase (consequential). The latter submits only a payment already signed by the buyer's wallet/client; it never signs or retries by itself. MCP Apps remain 2 display-only cards, with no payment tools attached. Without WebMCP support and a compatible signer, an agent can browse but cannot pay. https://scvd.store/mcp.md describes the doors.

### Protocol claims follow implemented scope

Current protocol scope: x402: Payment challenges, endpoint inspection and signed offer/receipt verification. The current quote names available checkout rails. MPP: Read-only MPP endpoint inspection and native MPP checkout for enabled items. Current payment capabilities declare checkout availability, network and currency; inspection does not establish completed payment or delivery. A2A: The agent card declares the current endpoint, capabilities and version. UCP: Business profile, catalog search, lookup and product detail at the pinned 2026-08-25 release. Checkout and order are advertised in the profile exactly when this deployment has them switched on; the profile's status block says which items and rails. No third-party conformance claim. Current payment capabilities and each protocol profile describe deployment availability.

### No sandbox, and that is the product

Readiness checks look for a test environment and find none, and there is not going to be one. https://scvd.store/try is a live counter: real x402 settlement, real signed artifacts, real chain, from a fraction of a cent. A sandbox is where integrations pass and production is where they fail, and that gap is the single most common thing this store observes in other people's endpoints. A test mode behaving differently from the real door is a second implementation to keep honest, and the first time it drifted, everyone who rehearsed against it rehearsed against fiction. The cheapest door here costs less than the hour it takes to configure a sandbox key. The one sandbox here is the trade counter's, for marketplaces proving an HMAC signer: account `sandbox`, secret published, check desk at https://scvd.store/api/trade/sandbox/check.

### Maintained packages and language clients

SCVD maintains x402-verify · source 1.11.0, x402-sign · source 1.0.3, scvd-preflight · source 0.3.1, scvd-corpus-client · source 0.1.0, scvd-defects · source 0.22.0, scvd-mcp-starter · source 0.2.0, alongside the CLI and tab. Preflight language guides: JavaScript preflight SDK, Python preflight SDK, Go preflight SDK. Package docs and installation: https://scvd.store/developers. HTTP contract: https://scvd.store/openapi.json.

### The MCP card CSP is stricter than the checklist wants

A scan grades the MCP App card's Content-Security-Policy on four categories and scores 2 of 4, wanting connect-src to include our MCP origin and img-src and style-src to name specific origins. The card declares `connect-src 'none'`, `form-action 'none'` and `img-src 'none'` — not a narrower allowance but NO allowance, stricter than anything that could score full marks. That is the keeper's G2 ruling made into a fence a host verifies by parsing one tag: the cards are display-only, and a card that could reach the network is a card that could act. `frame-ancestors` is absent because CSP Level 3 says it MUST be ignored in a meta element, the only channel an MCP-served resource has. The pages' own header carries, since 2026-09-05, what the card cannot: `connect-src` (this origin, which is the MCP origin) and `frame-ancestors` (this origin and the two chat hosts), both tightenings.

### The documentation door is the same shelf, not a second implementation

Scans look for two MCP servers, one to act and one for the docs, and until 2026-09-05 read ours as running both with the docs one down: https://scvd.store/mcp.md was a page, 200 on GET, 405 on a POSTed handshake. The docs still live on the main door as `resources/list` and `resources/read`; what changed is that the probed address answers. POST https://scvd.store/mcp.md (and https://scvd.store/mcp/docs) is a JSON-RPC server whose catalog is those same resources, read by the same function, plus one tool returning any by name. Nothing acts.

### No AggregateRating, and the refusal is the product

Structured-data checks award a point for AggregateRating or Review as social proof an answer engine can quote. This store publishes neither, for its own house sentence: never a ranking, and never a verdict without its derivation and denominator beside it. Every verdict it issues is one dated observation that expires and is re-taken, or a derivation that prints its rule and its fraction, and a shop that would not put stars on somebody else's endpoint has no business wearing them. The structured data carries what is checkable instead — Organization, WebSite, Product, Offer, Service, ItemList — and the evidence a rating asks you to take on trust is at https://scvd.store/corpus.json, signed, verifiable offline.

### The agent-auth rows this store cannot score honestly

Two checks want doors that do not exist here. One looks for a 401 carrying `WWW-Authenticate: Bearer resource_metadata=...`; every path it probes answers 200, because every one is free, and manufacturing a 401 on a public document would be the plainest false claim this store could make. The signpost goes where it IS true: every 402 carries that header pointing at https://scvd.store/.well-known/oauth-protected-resource, which RFC 9110 permits outside a 401, with the scheme token X402 because no bearer token is accepted. The other wants `register_uri`, `claim_uri` and `revocation_uri` to resolve; all three are `null`, because no credential is ever issued, and standing up three endpoints that do nothing would be the stale-metadata failure that spec exists to prevent.

### Markdown by Accept first; by user-agent only where the client said nothing

Scanners check for markdown served to an agent-shaped user-agent. This store negotiates on Accept, parsed with q-values, and any header that names a type wins. Until 2026-09-05 it stopped there, and a probe found GPTBot and a browser receiving identical storefront bytes. Now a named reader — a training crawler or a user-initiated fetcher, classed by its vendor's stated purpose, never by guessing at a string — that states no preference gets markdown where a page genuinely has one and the page elsewhere; a named indexer keeps the page and its JSON-LD; an unnamed agent's bare fetch still gets JSON. `Vary` has named User-Agent since 2026-09-02.

## Contact

A person reads this address: sean@recordcreativeco.com