Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

docs(api): document the Materialize print endpoints and link them from the nav

nirholas7e2c7cad5d89
diff --git a/data/pages.json b/data/pages.json
index 4b76ddad4..726129726 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -976,6 +976,14 @@
"priority": 0.6,
"changefreq": "weekly"
},
+ {
+ "path": "/materialize",
+ "title": "Materialize",
+ "description": "Turn any 3D model into a real printed object. Live printability analysis and automatic repair, a true-scale AR preview on your own desk, an itemized price from the mesh's own measured volume, and USDC checkout on Solana.",
+ "priority": 0.8,
+ "changefreq": "weekly",
+ "added": "2026-09-02"
+ },
{
"path": "/inspect",
"title": "Model Inspector",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index dc99a1854..9cd6f48a3 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1802,6 +1802,195 @@ buys from is documented under `POST /api/x402/forge` in the x402 section.
---
+## Materialize print API
+
+Turn any 3D model into a real, physical object: analysis, preparation, an
+itemized price, checkout in USDC on Solana, tracked fulfillment, and a
+certificate of authenticity attested on-chain. Product guide:
+[Materialize](./materialize.md). Wire contracts:
+[specs/PRINT_PIPELINE.md](../specs/PRINT_PIPELINE.md).
+
+Analysis and quoting are **free and keyless**. Only checkout costs money.
+
+### Catalog
+
+```http
+GET /api/print/catalog
+```
+
+Materials, size presets, finishes, shipping zones and the pricing parameters
+every quote is computed from. The public output omits the platform margin
+fields. This is the source of truth for `materialId`; do not hardcode ids.
+
+```json
+{
+ "version": 1,
+ "currency": "USDC",
+ "chain": "solana",
+ "materials": [
+ {
+ "id": "resin-standard",
+ "name": "Standard resin",
+ "class": "resin",
+ "minWallMm": 0.6,
+ "minHeightMm": 15,
+ "maxHeightMm": 180,
+ "leadTimeDays": 5,
+ "colorCapable": false,
+ "finishes": [{ "id": "as-printed", "name": "As printed", "fee": 0 }]
+ }
+ ],
+ "sizePresets": [{ "id": "desk", "heightMm": 120 }],
+ "shipping": { "zones": [{ "id": "us" }, { "id": "eu" }, { "id": "cn" }, { "id": "row" }] }
+}
+```
+
+### Analyze and quote
+
+```http
+POST /api/print/quote
+```
+
+One endpoint, two modes. Omit `materialId` and it is a pure analysis: the
+printability report, free, no price. Include one and it also returns the
+itemization and a signed quote token.
+
+| Field | Type | Notes |
+|---|---|---|
+| `creationId` | string | A three.ws creation id. One of this or `glbUrl` is required. |
+| `glbUrl` | string | A public `.glb` URL instead. |
+| `materialId` | string | From the catalog. Omit for analysis only. |
+| `finishId` | string | Optional, from the material's finishes. |
+| `targetHeightMm` | number | Printed height. Bounded by the material and the mesh. |
+| `quantity` | integer | Default `1`. Breaks at 5 and 20. |
+| `country` | string | ISO 3166-1 alpha-2, for shipping. |
+| `hollow` | boolean | Hollow the solid where it is geometrically safe. Changes the price. |
+| `note` | string | Optional note for the operator. Read by the fabrication gate. |
+
+```bash
+curl -s https://three.ws/api/print/quote \
+ -H 'content-type: application/json' \
+ -d '{"creationId":"6f1b...","materialId":"resin-standard","targetHeightMm":120,"quantity":1,"country":"US"}'
+```
+
+```json
+{
+ "report": {
+ "version": 1,
+ "manifold": true,
+ "shells": 1,
+ "volume_cm3": 71.4,
+ "bbox_mm": { "x": 62.1, "y": 120, "z": 48.3, "diagonal": 143.2 },
+ "min_wall_mm": 1.42,
+ "recommended_min_height_mm": { "resin": 120, "sls_nylon": 120, "full_color": 169 },
+ "score": 96,
+ "deductions": []
+ },
+ "fits": [{ "materialId": "resin-standard", "ok": true, "minHeightMm": 51, "maxHeightMm": 180 }],
+ "screening": { "verdict": "allow", "stage": "quote", "policy_url": "/docs/materialize#content-policy" },
+ "quote": {
+ "version": 1,
+ "currency": "USDC",
+ "lines": [
+ { "id": "setup", "label": "Build setup, Standard resin", "amount": 6 },
+ { "id": "material", "label": "Standard resin", "detail": "71.4 cm3 at 0.55 USDC per cm3.", "amount": 39.27 },
+ { "id": "shipping", "label": "Shipping to United States and Canada", "amount": 12.4 }
+ ],
+ "total": 57.67,
+ "leadTimeDays": 12
+ },
+ "token": "pq1.eyJ2IjoxLC...",
+ "expiresInSeconds": 86400
+}
+```
+
+| Status | Code | Meaning |
+|---|---|---|
+| `200` | | Report, and a quote when a material was given. A mesh that violates the material's constraints returns `quote: null` with a `rejection` naming the measured number, the required number and the fix. |
+| `413` | `too_large` / `too_complex` | Over 100 MB or 2M triangles. |
+| `422` | `invalid_model` / `no_geometry` | Not a parseable mesh, or no triangles to print. |
+| `451` | `fabrication_refused` | The fabrication gate refused it. The body carries `category`, `label`, `allowed` and `policy_url`. See the [content policy](./materialize.md#content-policy). |
+| `502` | `fetch_failed` | The model URL did not serve the file. |
+
+### Prepare
+
+```http
+POST /api/print/prepare
+```
+
+Reconstructs the mesh as a closed solid, fills holes, scales it to
+`targetHeightMm`, optionally hollows it with drain holes, and writes the
+manufacturing files (binary STL, 3MF with vertex colour when the source had a
+texture, and the repaired GLB) to durable storage. Returns permanent URLs plus
+the post-repair report, so you can see exactly what changed.
+
+### Order (human checkout)
+
+```http
+POST /api/print/orders # session + CSRF
+GET /api/print/orders/:id # the order and its full timeline
+```
+
+Body: the quote `token` plus a `shipping` object (`name`, `line1`, `line2`,
+`city`, `region`, `postal_code`, `country`, `phone`). Minimum fields only: this
+is the sole personal data the platform stores for a print, it is never logged,
+and it never enters an analytics event.
+
+### Order (agent checkout, x402)
+
+```http
+POST /api/x402/print-order
+```
+
+The agent lane. The quote token and the address are validated **before** any 402
+is issued, so a malformed order is refused for free with a `422` and never
+charges. The 402 then quotes that token's exact total rather than a list price,
+because every print is its own object.
+
+```bash
+curl -s -X POST https://three.ws/api/x402/print-order \
+ -H 'content-type: application/json' \
+ -d '{
+ "token": "pq1....",
+ "shipping": { "name": "Ada Lovelace", "line1": "12 Analytical Way", "city": "London", "postal_code": "EC1A 1AA", "country": "GB" }
+ }'
+```
+
+```json
+{
+ "ok": true,
+ "order_id": "c1b0a2d4-7e33-4f01-9a55-2b7c1d0e9f4a",
+ "status": "screening",
+ "paid_usdc": "48.20",
+ "track_url": "/materialize/orders/c1b0a2d4-7e33-4f01-9a55-2b7c1d0e9f4a"
+}
+```
+
+Track it with `GET /api/print/orders/:id`, which needs no account.
+
+### Certificates
+
+```http
+GET /api/print/certs/:id
+```
+
+The certificate for a shipped print: the SHA-256 of the exact manufactured file
+and of the viewable GLB, the edition number, and the Solana memo signature that
+carries both. The human page is `/cert/:id`. A `signature` of `null` means the
+attestation is still in flight, not that the certificate is fake.
+
+### Operator and provider surfaces
+
+`POST /api/print/ops/{queue|order|adapters|transition|submit|tracking|cancel|refund}`
+is the operator console API and is allowlist-gated.
+`POST /api/print/webhook/:provider` is where a fulfillment partner reports in;
+every delivery is HMAC-verified against the raw bytes before it is parsed and
+claimed for idempotency before it is applied. Neither is a public integration
+surface; both are specified in
+[specs/PRINT_PIPELINE.md](../specs/PRINT_PIPELINE.md).
+
+---
+
## Material Studio API
Re-skin *any* GLB — not just avatars — without regenerating its mesh. Generalizes
diff --git a/docs/avatar-thumbnails.md b/docs/avatar-thumbnails.md
index ed0d84b14..ec5fb85e3 100644
--- a/docs/avatar-thumbnails.md
+++ b/docs/avatar-thumbnails.md
@@ -241,9 +241,7 @@ service, so `--env-file=.env.local` alone exits with `S3_BUCKET is unset` for an
mode that renders or adopts. Export them into the shell first:
```bash
-eval "$(gcloud run services describe three-ws-api --region us-central1 \
- --project aerial-vehicle-466722-p5 --format=json \
- | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const e of JSON.parse(s).spec.template.spec.containers[0].env||[])if(e.name.startsWith("S3_")&&e.value)console.log(`export ${e.name}=${JSON.stringify(e.value)}`)})')"
+eval "$(node scripts/read-service-env.mjs '^S3_')"
```
Then any of the commands above runs as written.
diff --git a/docs/configuration.md b/docs/configuration.md
index 686426346..2bd19ec4a 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -355,7 +355,7 @@ node scripts/gen-solana-signer-key.mjs --var COIN_TREASURY_SECRET_KEY_B64
node scripts/gen-solana-signer-key.mjs --vanity www
```
-**Fund the printed public key with SOL** before the relayer can pay fees. `--write` refuses to clobber an existing value, so rotating means removing the old line first. In production, add the value to the Cloud Run service (`gcloud run services update three-ws-api --region us-central1 --update-env-vars <NAME>=<base64>`) — never commit the secret. Note that `gcloud run services describe three-ws-api` is the authoritative view of production env; a `vercel env pull` export returns empty for secret-type vars and must not be trusted.
+**Fund the printed public key with SOL** before the relayer can pay fees. `--write` refuses to clobber an existing value, so rotating means removing the old line first. In production a relayer key is a credential, so it goes in Secret Manager rather than on the service as a literal: `node scripts/migrate-plaintext-secrets.mjs --only <NAME> --apply` moves an existing one, and `docs/ops/wallet-key-migration.md` has the commands for publishing a new version. Never commit the secret. Read production's current value with `node scripts/read-service-env.mjs '^<NAME>$' --raw`; a `vercel env pull` export returns empty for secret-type vars and must not be trusted.
---
diff --git a/docs/nav.json b/docs/nav.json
index e69e6fa9a..12c9a935e 100644
--- a/docs/nav.json
+++ b/docs/nav.json
@@ -129,6 +129,10 @@
"label": "The Forge pipeline (deep dive)",
"path": "forge-pipeline"
},
+ {
+ "label": "Materialize: print it for real",
+ "path": "materialize"
+ },
{
"label": "Image to 3D",
"path": "image-to-3d"
diff --git a/docs/ops/README.md b/docs/ops/README.md
index 7997303ef..67ec4b68e 100644
--- a/docs/ops/README.md
+++ b/docs/ops/README.md
@@ -28,7 +28,7 @@ Start with [gcp-production.md](gcp-production.md); it is the complete operationa
| [runtime-flags.md](runtime-flags.md) | DB-backed feature flags that flip platform behavior without a redeploy. |
| [x402-discovery-listings.md](x402-discovery-listings.md) | Getting paid endpoints listed and ranked on x402scan, the Bazaar, and other directories. |
| [seo-keyword-plan.md](seo-keyword-plan.md) | Verified keyword landscape and content calendar (snapshot dated 2026-07-17). |
-| [wallet-key-migration.md](wallet-key-migration.md) | Incident record: stranded pool-agent wallets after the WALLET_ENCRYPTION_KEY migration. |
+| [wallet-key-migration.md](wallet-key-migration.md) | Incident record: stranded pool-agent wallets after the WALLET_ENCRYPTION_KEY migration. Also the standing runbook for where production's credentials live in Secret Manager, how to publish a new version, and the owner-gated master-wallet rotation. |
| [stranded-wallets.md](stranded-wallets.md) | The standing owner decision on custodial wallets sealed by that rotation: measured list, why recovery is impossible, what crediting or writing off the customer balances costs, and the commands for each. |
| [forge-multiview-migration-handoff.md](forge-multiview-migration-handoff.md) | Historical hand-off for the forge multi-view migrations (June 2026); superseded by gcp-production.md. |
| [examples-repo-export.md](examples-repo-export.md) | How the public `three-ws/examples` satellite repo is assembled and published from this monorepo. |
diff --git a/docs/ops/forge-error-triage.md b/docs/ops/forge-error-triage.md
index 9623dfed0..c336b2962 100644
--- a/docs/ops/forge-error-triage.md
+++ b/docs/ops/forge-error-triage.md
@@ -158,6 +158,6 @@ Without it, it exits 2 and prints the command that reads production's value off
the Cloud Run service:
```bash
-gcloud run services describe three-ws-api --region us-central1 \
- --project aerial-vehicle-466722-p5 --format=yaml | grep -A1 DATABASE_URL
+# DATABASE_URL is a Secret Manager reference, so describe alone shows no value.
+node scripts/read-service-env.mjs '^DATABASE_URL$' --raw
```
diff --git a/docs/ops/llm-lanes.md b/docs/ops/llm-lanes.md
index 967e4c81b..69279b4a0 100644
--- a/docs/ops/llm-lanes.md
+++ b/docs/ops/llm-lanes.md
@@ -225,9 +225,10 @@ curl -s -o /dev/null -w '%{http_code}\n' -X POST \
-d '{"anthropic_version":"vertex-2023-10-16","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}' \
"https://aiplatform.googleapis.com/v1/projects/aerial-vehicle-466722-p5/locations/global/publishers/anthropic/models/claude-sonnet-5:rawPredict"
-# What production actually has set:
-gcloud run services describe three-ws-api --region us-central1 \
- --project aerial-vehicle-466722-p5 --format=yaml | grep -A1 API_KEY
+# What production actually has set (every API key is a Secret Manager
+# reference since 2026-09-02, so read them through the resolver):
+node scripts/read-service-env.mjs '_API_KEY$' --names # which secret backs each
+node scripts/read-service-env.mjs '^OPENAI_API_KEY$' --raw # one value
```
---
diff --git a/docs/ops/redis.md b/docs/ops/redis.md
index 394acdd35..419b14fac 100644
--- a/docs/ops/redis.md
+++ b/docs/ops/redis.md
@@ -284,8 +284,8 @@ The dead store's REST URL and token are needed for migration. Try in order:
cred was overwritten, the old value is still readable from the revision that
used it:
```bash
- gcloud run services describe three-ws-api --region us-central1 \
- --project aerial-vehicle-466722-p5 --format=yaml | grep -A1 UPSTASH
+ node scripts/read-service-env.mjs '^UPSTASH' --names # which secret backs each
+ node scripts/read-service-env.mjs '^UPSTASH_REDIS_REST_TOKEN$' --raw
gcloud run revisions list --service three-ws-api --region us-central1 \
--project aerial-vehicle-466722-p5 # then `describe <old-revision>` for its env
```
diff --git a/docs/start-here.md b/docs/start-here.md
index c4b39ca8f..29ffc8597 100644
--- a/docs/start-here.md
+++ b/docs/start-here.md
@@ -66,6 +66,8 @@ Generations don't need a babysitter, either: start a forge job, close the tab, a
Curious what happens between the prompt and the model? [How the Forge works](./how-forge-works.md) tells the story in plain language; [the Forge pipeline](./forge-pipeline.md) is the full engineering deep dive.
+Want the model in your hands rather than on a screen? [Materialize](./materialize.md) prints any generation in resin, nylon, colour sandstone or steel and ships it to your door, paid in USDC on Solana, with a certificate of authenticity attested on-chain. An AI agent can order one too, over x402, without a human in the loop.
+
---
## Ready to build?
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index f3adc0e50..b3b388d9d 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -327,7 +327,7 @@ Organized by symptom. Find your problem, check the likely causes, follow the fix
**Fix steps:**
-1. Set `JWT_SECRET` once and don't rotate it unless needed. In production it lives on the Cloud Run service env (`gcloud run services describe three-ws-api --region us-central1` to inspect), it must be the same value across all revisions.
+1. Set `JWT_SECRET` once and don't rotate it unless needed. In production it lives in Secret Manager, referenced by the Cloud Run service (`node scripts/read-service-env.mjs '^JWT_SECRET$' --raw` to read it), and it must be the same value across all revisions.
2. Session duration is 30 days. A session used when fewer than 7 days remain is rotated to a fresh 30-day token (a rolling refresh window), so actively returning users stay signed in indefinitely.
---
@@ -510,7 +510,7 @@ Run `npm run db:status` first to preview which migrations are pending.
--freshness=1h --limit 20 --format="value(textPayload)"
```
Deploys ship via `npm run deploy:gcp` (run `npm run build` first for frontend changes), the full runbook lives in the repo at `docs/ops/gcp-production.md`. On a self-hosted fork, check whatever your host surfaces as function/process logs.
-2. The most common cause is a missing environment variable. All required vars must be set: `DATABASE_URL`, `JWT_SECRET`, `PUBLIC_APP_ORIGIN`. The `env.js` module throws on startup if required vars are absent. In production, inspect and set them on the Cloud Run service: `gcloud run services describe three-ws-api --region us-central1` / `gcloud run services update three-ws-api --region us-central1 --update-env-vars KEY=value`.
+2. The most common cause is a missing environment variable. All required vars must be set: `DATABASE_URL`, `JWT_SECRET`, `PUBLIC_APP_ORIGIN`. The `env.js` module throws on startup if required vars are absent. In production, read them with `node scripts/read-service-env.mjs '^DATABASE_URL$|^JWT_SECRET$|^PUBLIC_APP_ORIGIN$' --names` (credentials are Secret Manager references, so `describe` alone shows no value) and set a non-secret one with `gcloud run services update three-ws-api --region us-central1 --update-env-vars KEY=value`. A credential goes in Secret Manager instead: see `docs/ops/wallet-key-migration.md`.
---
diff --git a/public/nav-data.js b/public/nav-data.js
index e38284319..96790cefd 100644
--- a/public/nav-data.js
+++ b/public/nav-data.js
@@ -168,6 +168,12 @@ export const NAV_GROUPS = [
href: '/avatar-engines',
desc: 'Every engine for high-quality & photoreal 3D avatars — technique, license & how three.ws uses each',
},
+ {
+ title: 'Materialize',
+ href: '/materialize',
+ badge: 'New',
+ desc: 'Any 3D model becomes a real printed object: printability analysis, true-scale AR, and USDC checkout on Solana',
+ },
{
title: 'CA → x402',
href: '/ca2x402',