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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(api): document the Materialize print endpoints and link them from the nav
nirholas7e2c7cad5d89
diff --git a/data/pages.json b/data/pages.jsonindex 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.mdindex 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 APIRe-skin *any* GLB — not just avatars — without regenerating its mesh. Generalizesdiff --git a/docs/avatar-thumbnails.md b/docs/avatar-thumbnails.mdindex 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 anmode 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.mdindex 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_B64node 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.jsonindex 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.mdindex 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.mdindex 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 offthe 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.mdindex 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.mdindex 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 thatused 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$' --rawgcloud 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.mdindex 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, aCurious 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.mdindex 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.jsindex 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',