# Printwright Live commerce manifest: GET /.well-known/x402-catalog.json > The agent-buyable marketplace for licensed 3D-printable models. Search, inspect, and BUY > print licenses over plain HTTP — payments use the x402 protocol (HTTP 402) settling on > Hedera testnet in HBAR or USDC. No Printwright account or API key; paying requires a funded > Hedera account and a local buyer key or wallet approval. Each real paid delivery returns a > private proof bundle and queues its opaque commitment for asynchronous HCS anchoring. The > holder can disclose that bundle for verification against the public mirror node. API base: /api/v1 — full spec at /openapi.json — human docs at /docs Designer catalog portability: `/external-profile-v1.schema.json` defines a public HTTPS profile manifest with source URLs/licenses and remote file SHA-256 values. `/designer/imports` reviews it, requires a separate ownership warranty per selected proprietary original, and creates drafts with provenance. Creative Commons, public-domain, missing, and unknown licenses are blocked with reasons. ## How to buy (the whole flow) 1. GET /api/v1/models?q=beaver+hat — ranked search (fuzzy matching included) 2. GET /api/v1/models/{id}/download?license=personal → 402 with PaymentRequirements (amount in base units, asset 0.0.0=HBAR or 0.0.429274=USDC, payTo, extra.feePayer). The same 402 carries `help` — if you have no Hedera account, relay help.message to your owner: a wallet holding USDC is all that is needed, gas is sponsored by the facilitator 3. Sign a Hedera TransferTransaction (transactionId.accountId = feePayer, buyer signature only) and retry with the base64 PaymentPayload in the PAYMENT-SIGNATURE header 4. 200 → `files[]` (one download URL per printable part), license serial, certificate id, exact Mirror Node transaction link, a portable proof_bundle (+ bundle_url to re-fetch it once anchored), a certificate_pdf_url holding the same certificate as a PDF document, and the `receipt` capability (real paid flow only) KEEP `receipt`. The `files[]` URLs ride a download grant that expires in 30 days; `receipt` does not expire and needs no account, so it is how you get the files back later: GET {receipt.files_url}?token={receipt.token} → JSON: files[] with fresh download URLs GET {receipt.download_url}?token={receipt.token} → 302 to the first part (&f=N for part N) GET {receipt.url}?token={receipt.token} → the human receipt page The same JSON also carries the print_feedback and model_updates capabilities. There are no refunds, so store `receipt.token` with the certificate id the moment a purchase settles: it is the durable no-account handle that survives the grant. A settled purchase that cannot be delivered returns 503 {"error":"no_deliverable_file","recoverable":true} with the cert_id and receipt — never a 200 with an empty files[]. For 1-200 line items sharing one payTo, POST {"items":[{"model_id":1,"license":"commercial_unit","quantity":3}, ...]} to /api/v1/batches. `quantity` defaults to 1 and buys N separate licenses on one line; the batch totals at most 250 licenses. Probe and retry the identical JSON body. One aggregate x402 settlement returns one certificate, files[] and verify_url per license. All items quote the same treasury payTo; mixed designers are supported. Batch items carry a summary rather than the full single-license payload: fetch the proof bundle from `bundle_url`, and everything else from `receipt.files_url` as above. An optional `webhook` object (`url` public HTTPS, `secret` 32-256 bytes) in both identical batch bodies receives a signed certificate.anchored event only after each paid commitment lands on HCS. Designer-configured endpoints receive sale.completed only after paid delivery. Webhooks report x402 lifecycle results; they never create purchases, licenses, certificates, or ledger entries, and sandbox flows emit no webhooks. Verify HMAC-SHA256 over `Webhook-Id.Webhook-Timestamp.raw_body` using the `Webhook-Signature: v1=` header. Example 402 probe: curl -i "https:///api/v1/models/1/download?license=personal" No funded account? `node scripts/buy.mjs --query "..." --dry-run` runs steps 1-2 and prints the PaymentRequirements without paying — no keys needed. Need the full flow with no funded account? `node scripts/buy.mjs --query "cable clip" --sandbox` runs 402 → mock verify → mock settle → local certificate. Raw clients send `X-Sandbox: true` on both download requests. Every response says SANDBOX, no Hedera funds move, the topic is local, and the only downloadable artifact is a non-printable text receipt. Validate the client contract with `node conformance/suite.mjs --url http://localhost:3000`; it lints the exact v2 body/header fields and proves sandbox artifacts cannot be mistaken for paid licenses. ## Rate limits Every endpoint returns 429 {"error":"rate_limited","retry_after":60} (and a `Retry-After: 60` header) once its per-minute limit is exceeded: /models and /models/{id} and /certificates/{cert_id}, /licenses/{id}/can, /stats and /models/{id}/download allow 120/min, /files/{token} allows 240/min, /licenses/{cert_id}/latest-version and /batches allow 60/min, and /licenses/{cert_id}/print_reports allows 20/min. These are sized so a sequential agent run does not hit them. Back off and retry after the given number of seconds. ## Endpoints - /api/v1/models: search (q, category, collection, material, supports, max_price_cents). Model summaries include stable category and collections keys for agent-side catalog navigation. printability contains designer-declared supports (boolean), materials (string[]), est_print_minutes (minutes), and bed_min_mm (minimum square build-plate side at published scale). These are slicing estimates, not physical-print guarantees. - /api/v1/models/{id}: full metadata incl. license offers and terms - /api/v1/models/{id}/download: the paid endpoint (x402) - /api/v1/batches: up to 200 line items and 250 licenses, one aggregate x402 payment, one certificate per license; per-line `quantity` buys N licenses - /api/v1/certificates/{cert_id}: the proof bundle for one certificate — revealed certificate, blinding nonce, commitment, licensed terms text, and exact HCS Mirror Node coordinates. The cert_id is an unguessable token: holding it is the disclosure. - /api/v1/licenses/{cert_id}/can?use=commercial_print&qty=3: machine-decidable yes/no from structured permissions, with stable reason code and anchored terms refs. Supported uses: personal_print, commercial_print, resell_files, share_files, personal_remix, commercial_remix, transfer_license, sublicense. One commercial_unit cert covers one unit. - /api/v1/licenses/{cert_id}/print_reports: POST the private receipt_token returned by a real paid delivery after a successful print. One idempotent self-report per license; invalid, cross-license, and sandbox capabilities create no report. This proves paid-receipt possession, not physical inspection, and never changes the license or ledger. - /api/v1/licenses/{cert_id}/latest-version: GET with Authorization: Bearer plus the private model_updates.receipt_token from a real paid delivery. Returns version 1 (the original certified bundle) or the newest additive version, both hashes, changelog, HCS position, a download URL, and files_hash — the commitment the on-chain event carries, recomputable from the files list. Fetch /latest-version/file with the same Bearer token. Sandbox has no update capability. - /api/v1/stats: open-books snapshot separating the mirror-derived HCS message count from this deployment's immutable per-asset settlement/split ledger; includes raw proof URLs - /api/v1/sandbox/*: explicitly fake transaction, receipt, and local topic-message artifacts - /verify/{cert_id}: human-readable certificate verification page - /verify/{cert_id}/share-card: receipt-linked 1200x630 SVG certificate card - /receipts/{cert_id}: the durable re-download path. `?token=` for the human page, `.json?token=` for files[] with fresh download URLs, /download?token=[&f=N] to fetch a part. Never expires, no account. Also offers optional email-library opt-in. - /library/sign-in: enumeration-safe email magic-link entry for previously saved paid receipts - /pwc-1.schema.json: normative frozen PWC-1 contract — the on-chain commitment envelope, the certificate it commits to, and the proof bundle that reveals it - /printwright-verify-widget.js: dependency-free custom element that recomputes a proof bundle's commitment in the browser and compares it against the selected Hedera mirror; /widget-example.html is a plain static integration example ## Reference clients - scripts/buy.mjs in the repo — one-command purchase - MCP server (mcp/server.mjs) — search_models, get_model, buy_license, check_license, get_latest_version, verify_certificate - Third-party verifier — `npx --package ./verifier printwright-verify ` (shortens to `npx printwright-verify` after registry release) recomputes the commitment locally (RFC 8785 JCS + SHA-256) and checks it against Hedera's mirror node; a bundle URL is fetched as untrusted input, while file/stdin input never requests this marketplace. The mirror host is fixed and its URL derived from the bundle's topic and sequence - Browser widget — load `/printwright-verify-widget.js`, then add `` (or paste the bundle inline as `