API routes

Server-rendered HTML (§14.1). The text is in the server response, not fetched by script.

Free, cacheable, unauthenticated. Computed fields and self-reported fields are separately namespaced (FR-52).

With a valid X-Wallet-Signature this also returns owned, entitled and price_kind. Without one it is version data only: ?address= alone never reveals entitlement state (FR-20). scan is the latest release's trust report in three numbers ("PRD Trust Report.md" §5) — absent, never zeroed, when there is no report to read.

FR-15. Every release, with changelog, diff summary, scan verdict and the prices in force. Creators cannot delete entries, failing releases are published too, and a retired listing keeps its log (FR-43). Pages newest-first by cursor.

402 then 200. Send the payment authorization in PAYMENT-SIGNATURE; access is granted only after the facilitator's settle returns a transaction hash (FR-22). A free listing returns 200 immediately (FR-24), as does a holder whose purchase was stamped all_versions (FR-16).

FR-19 / FR-46. Owned versions stay fetchable forever, including after the listing retires.

FR-32. Requires X-Wallet-Signature: entitlement state is never disclosed without a signature (FR-40).

FR-6 and §19. accepted_terms_version on POST /api/creators must equal the top-level version. buyer_terms carries the same three fields for the terms a buyer is bound by.

FR-33. Generated from the zod schemas.

One cheap round trip to the database, the dependency every paid path shares. status is ok or degraded; the facilitator, GitHub and Storage are deliberately not probed. Never cached. This is the status target in /.well-known/api-catalog.

RFC 9727. A linkset (application/linkset+json) naming this document, /docs and /api/terms, anchored on the API and on the MCP server. The home page and every manifest page carry RFC 8288 Link headers pointing here, so an agent needs one HEAD request and no prior knowledge of §9.

FR-30. The paste-ready preamble that tells a downstream agent to check GET /api/v/… before each run, as text/markdown. The wording differs for update_price_micro = 0 (updates included) and > 0.

FR-31. JSON-RPC 2.0 over Streamable HTTP, stateless. Five tools: how_to_buy (free, no wallet: whether the listing is for sale, the price, the listing page, the skill and the endpoint — the tool a client that cannot sign answers with), get_listing (wraps GET /api/label/:owner/:slug), check_version (wraps GET /api/v/:owner/:slug), purchase (wraps GET /api/r/:owner/:slug; takes a pre-signed PAYMENT-SIGNATURE and returns the 402 body as structured content when unpaid) and fetch_release (wraps GET /api/r/:owner/:slug/v/:version). The last four call the same core module (§11); purchases are recorded with source: mcp. GET opens the notification stream and DELETE ends a session. Connect with npx @modelcontextprotocol/inspector --transport http --server-url ${APP_URL}/api/mcp.

FR-2. Send Idempotency-Key: <uuid> and the identical 201 replays for 24 hours, so a dropped response does not strand you without your API key. Rate limit: 5 per hour per IP.

FR-5. Both need step_up — a signature from the *currently* bound payout address. A payout change must be signed over a challenge minted with new_payout_address=<the new address> on GET /api/auth/challenge, so the signature names where the money will go. A payout change takes effect after 48 hours and sweeps continue to the old address until then; an abuse-contact change also takes 48 hours and is announced to the old contact.

Rail B (source: hosted) provisions a private repo and adds ssh_public_key as a write deploy key for that repo only (FR-7, §14.6); the 201 carries the remote, the default branch and github.com's SSH host key fingerprints so the next call is git push. Rail A (source: github) needs installation_id plus either github_repo_id or repo: "owner/name", and the repository must be private — a public one is refused with 422 public_repo (FR-10). Caps: 3 unpublished listings per creator (D2c).

The authenticated creator's own listings, newest first. Every entry carries the same pricing block as GET /api/listings/{id} (FR-13).

latest_release is the newest release with scan = pass (FR-9), and newest_release is the newest of any verdict when the two differ — the release that failed is the one whose report a creator needs. Both carry scan_report, the full trust report including the path and line of a secret ("PRD Trust Report.md" §4.4); it is served here and nowhere else, and never on the list route. Another creator's id returns 404, never 403.

FR-16: price changes apply to future purchases only. Explicit API values are never rounded (FR-12).

FR-8. Also the recovery path for a dropped webhook, and the only path for a tag pushed before the listing existed. With no ref and no version, cuts the repository's newest vX.Y.Z tag that has not been cut yet; version is required when a ref is given and that ref is untagged.

FR-11. MIT, Apache-2.0, BSD-3-Clause or MPL-2.0, committed to main. The attestation is made by the registering operator (D4).

FR-7 / FR-5. Step-up required. One public key, one repo (§14.6): the new key is added before the old one is removed.

FR-42. Needs a licence pass, at least one passing release, a description, and — on Rail A — a repository that is still private (FR-10). A 409 listing_not_ready carries details.blocking[] with every unmet requirement at once. Publishing a live listing is an idempotent 200.

FR-43. Terminal. Holders keep every version they own; the manifest and release log stay up, marked no longer sold. A hosted repo is archived, not deleted.

FR-44. Step-up required. Releases with at least one purchase are retained — they are the product (FR-46).

FR-29. Sale rows carry version, kind, amount and time — never the buyer address, never the transaction hash (FR-40).

FR-26. Payouts go only to the bound payout address; there is no to parameter. Normally the daily cron does this and you never call it.

FR-20. Single use, 5-minute expiry. A challenge is bound to one purpose — address_proof on registration, step_up on a payout change, rotate_key, or wallet_ownership for the X-Wallet-Signature header — and a signature is refused on any other path (W2.2). purpose is required; there is no default. A payout rebind additionally requires new_payout_address: the signed message names the incoming address, and the signature authorises that one change only.

FR-4. No Authorization header: the signature from the bound payout address is the credential. The old key is revoked immediately.

FR-8. push (version tags), release (published), installation and installation_repositories. The signature is verified over the raw body; deliveries older than 5 minutes are refused; X-GitHub-Delivery is deduplicated; the listing is resolved by installation and repo id, never by name. Every outcome after a valid signature is a 2xx, so a failure never teaches GitHub to disable the hook.

FR-26 / FR-28. Vercel Cron.

FR-28. Reconciles the receiving address's on-chain balance and every recorded tx hash against chain. Variance halts sweeps.