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(preflight): map the x402 preflight surface and announce it to holders
nirholas0ada8b17ebb3
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex b575dfd25..50c7e05b2 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -66,6 +66,7 @@ bottom.| Unified Crypto API aggregator — storefront + OpenAPI | Registry [api/v1/_providers.js](api/v1/_providers.js) (`providerCatalog()`), front door [api/v1/x/[...slug].js](api/v1/x/%5B...slug%5D.js) `→ /api/v1/x/<provider>/<endpoint>`, discovery `→ GET /api/v1/x`, storefront [pages/crypto-api.html](pages/crypto-api.html) `→ /crypto-api`, OpenAPI 3.1 [api/openapi-json.js](api/openapi-json.js) `→ /openapi.json`, docs § in [docs/api-reference.md](docs/api-reference.md#unified-api--apiv1x-aggregator), dir guide [api/v1/README.md](api/v1/README.md) | Live | Third-party crypto/DeFi/on-chain APIs (CoinGecko, DefiLlama × 2, Jupiter, DexScreener, Solana RPC, OpenAI-compatible) re-offered as one bill: free per-IP tier → BYOK pass-through → three.ws plan → x402 pay-per-call, in that order. Everything (OpenAPI paths, the `/crypto-api` live table, the docs quota table) renders from `providerCatalog()` at request/page-load time — no hand-enumeration, so a new provider descriptor shows up everywhere with zero page edits. Test: [tests/openapi-aggregator.test.js](tests/openapi-aggregator.test.js). Not to be confused with the separate `/api/crypto/*` bundle below (different campaign, different registry). Spec: x402-catalog campaign (retired 2026-07-28; readable in git history) || 3D Vision (let an agent see a model) | [api/_lib/3d-vision.js](api/_lib/3d-vision.js), route [api/3d/look.js](api/3d/look.js) `→ /api/3d/look`, MCP tool `look_at_model` in [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) and on every OKX forge endpoint ([api/_okx3d/forge.js](api/_okx3d/forge.js)), SDK [packages/see/](packages/see) (`@three-ws/see`) | Live | Every text-to-3D API answers with a URL to a binary an AI agent cannot open, so the agent that generated a model has no way to check its own work; that blindness is why agentic 3D stalls at one shot. This renders any public GLB from up to six angles (three-quarter, front, side, back, top, bottom; the default four are the smallest set that answers "is this good") and hands the frames back as **MCP image content blocks**, which a multimodal client renders into the conversation, so the model literally looks at its own output and can regenerate naming the fault it saw. Reuses the platform's headless renderer ([api/_lib/avatar-render.js](api/_lib/avatar-render.js)) with the `full-body` preset so props and creatures are not cropped like humanoids, renders frames sequentially because the browser is shared, and reports a partial turntable rather than failing. Geometry comes from the existing free inspector and is best-effort: a hiccup costs the numbers, never the frames. Free and keyless on REST and MCP, and free for OKX buyers on the paid forge endpoints, so an agent can confirm it got what it paid for. Docs: [docs/3d-vision.md](docs/3d-vision.md). Tests: [tests/3d-vision.test.js](tests/3d-vision.test.js) || Free 3D API + docs | [api/3d/index.js](api/3d/index.js) `→ /api/3d`, [api/3d/openapi.js](api/3d/openapi.js) `→ /api/3d/openapi.json`, landing page [public/3d.html](public/3d.html) `→ /3d`, reference doc [docs/3d-api.md](docs/3d-api.md) `→ /docs/3d-api` | Live · docs surface | Front door + OpenAPI 3.1 for the free, keyless 3D API. Catalog assembler [api/_lib/3d-catalog/index.js](api/_lib/3d-catalog/index.js) merges `api/_lib/3d-catalog/*.js` descriptors (currently `generate`, `inspect`) via a static import barrel (production source of truth) plus an additive dev-time directory glob; new descriptor = drop the file AND add its barrel import line; skips malformed, never throws; OpenAPI built from the same catalog via [api/_lib/3d-catalog/openapi.js](api/_lib/3d-catalog/openapi.js). Index does HTML/JSON content negotiation and advertises the paid ladder (Forge Pro, Rigged Avatars). Docs page: hero, live endpoint table, runnable quickstart with a live "Run inspect" console, embedded `<model-viewer>` GLB preview, and the free→paid ladder. Free endpoints: [api/3d/generate.js](api/3d/generate.js) (prompt 12), [api/3d/inspect.js](api/3d/inspect.js) (prompt 13). GPT Store Actions surface: [api/3d/studio.js](api/3d/studio.js) `→ /api/3d/studio`, a store-compliant twin of `generate` that strips the x402/upgrade block, drops internal ids, and runs the [api/_mcp-studio/safety.js](api/_mcp-studio/safety.js) age-13+ content gate before any GPU work; backs the "three.ws 3D Studio" custom GPT ([prompts/store-submissions/_generated/openai-actions.yaml](prompts/store-submissions/_generated/openai-actions.yaml) + [openai-gpt-config.md](prompts/store-submissions/_generated/openai-gpt-config.md), store-submission prompt 12). Spec: x402-overhaul campaign (retired 2026-07-28; readable in git history) |+| x402 Preflight (signed payability attestations) | Format core [api/_lib/x402/preflight.js](api/_lib/x402/preflight.js), server [api/x402/preflight.js](api/x402/preflight.js) `→ /.well-known/x402-preflight`, page [pages/preflight.html](pages/preflight.html) `→ /preflight` + [src/preflight-page.js](src/preflight-page.js), client SDK + CLI [packages/x402-preflight](packages/x402-preflight), MCP tool [api/_mcp3d/tools/preflight.js](api/_mcp3d/tools/preflight.js), spec [specs/x402-preflight.md](specs/x402-preflight.md), docs [docs/x402-preflight.md](docs/x402-preflight.md) | Live | The reliability layer x402 is missing. x402 says what a resource costs; nothing says whether the seller can still SETTLE it, so a buyer discovers an empty seller fee wallet only after signing. Born from the 2026-08-28 incident where three.ws was that seller: sponsor at 0.000899107 SOL against a 0.02 floor, 95 payment attempts, 0 settled, 3 hours. A seller publishes a signed, time-bounded ed25519 attestation of per-network payability, built from the same `gatherX402SettleHealth()` sensor healthz uses plus the live sponsor floor guard, so every field is measured rather than declared. `payable` is three-valued (a seller that cannot measure must say `unknown`, never `true`), every rate ships with its window and sample, `alternates` names the rails that DO work so a client re-routes in the same round trip, and `retry_after` stops a fleet synchronising into a retry storm. Verification enforces expiry, so a healthy attestation cannot be replayed through an outage. The open format is unencumbered: any x402 seller can serve one, any client can verify one, nothing routes through three.ws. Tests: [tests/x402-preflight.test.js](tests/x402-preflight.test.js) (38, including a cross-implementation digest check that the browser SDK and the node server sign byte-identical bytes). || Paid Market Data API (x402, 17 endpoints) | Registry [api/_lib/market-data/registry.js](api/_lib/market-data/registry.js), fetchers [api/_lib/market-data/fetch.js](api/_lib/market-data/fetch.js), factory [api/_lib/market-data/endpoint.js](api/_lib/market-data/endpoint.js), routes `api/x402/market-*.js` `→ /api/x402/market-<category>`, free index [api/x402/market.js](api/x402/market.js) `→ /api/x402/market`, catalog projection [api/_lib/service-catalog/services/market-data.js](api/_lib/service-catalog/services/market-data.js), docs [docs/market-data-api.md](docs/market-data-api.md) `→ /docs/market-data-api` | Live | Every free /markets feed (coins, coin profile, price history, categories, exchanges, derivatives, global+Fear&Greed, ETH gas, trending, DeFi TVL, chains, ~15k yield pools, stablecoins, fees/revenue, DEX volumes, hacks) wrapped as pay-per-call x402 endpoints at $0.001 USDC (Solana/Base), plus the $0.005 one-call `market-pulse` bundle. One registry drives the live 402s, the discovery-doc listings, and the free index — zero drift by construction; the fetchers delegate to the SAME exported builders the free pages use (`api/coin/*`, `api/defi/*`), so paid data always matches the site. Params rejected pre-settle (422) and upstream outages (503) never charge the buyer. Tests: [tests/market-data-api.test.js](tests/market-data-api.test.js). || Datapoint fabric (x402, 480k+ endpoints) | Registry [api/_lib/market-data/datapoints.js](api/_lib/market-data/datapoints.js), dynamic route [api/x402/d/[...path].js](api/x402/d/%5B...path%5D.js) `→ /api/x402/d/<family>/<id>/<metric>`, free catalog [api/x402/d/index.js](api/x402/d/index.js) `→ /api/x402/d`, discovery slice `buildDatapointItems` in [api/wk.js](api/wk.js), docs § in [docs/market-data-api.md](docs/market-data-api.md#the-datapoint-fabric--480000-standalone-endpoints) | Live | Every individual market datapoint as its OWN standalone paid endpoint — one URL = one value = one $0.0005 USDC x402 micro-payment (override `X402_PRICE_DATAPOINT_<FAMILY>`). 9 families × 68 metrics × live id spaces ≈ 484k addressable endpoints (~17.5k coins × 20, ~15.5k pools × 7, ~6k protocols × 6, chains, stablecoins, exchanges, global/gas/fear-greed) served by ONE dynamic route reading the registry; ids are runtime values, nothing hardcodes a third-party asset. Path that cannot exist → 404/422 with NO 402 issued; unknown id/outage rejects pre-settle. Free catalog enumerates families, metrics, prices, and pages each family's full live id space (200/page) so crawlers can walk the universe; the .well-known discovery doc carries a curated runtime-derived slice (~83 concrete resources). Tests: [tests/market-datapoints.test.js](tests/market-datapoints.test.js). || Pole Club (x402 micro-tips drive a live 3D room) | Page [pages/club.html](pages/club.html) `→ /club`, stage app [src/club.js](src/club.js) with [src/club-camera.js](src/club-camera.js), [src/club-crowd.js](src/club-crowd.js), [src/club-dances.js](src/club-dances.js), [src/club-audio.js](src/club-audio.js), [src/club-venue.js](src/club-venue.js), [src/club-perf.js](src/club-perf.js), [src/club-sequence.js](src/club-sequence.js); walk-in [src/club-entrance.js](src/club-entrance.js) + cover gate [src/club-gate.js](src/club-gate.js) (shared express flag [src/shared/club-express.js](src/shared/club-express.js)); paid endpoints [api/x402/club-cover.js](api/x402/club-cover.js) `→ /api/x402/club-cover` and [api/x402/dance-tip.js](api/x402/dance-tip.js) `→ /api/x402/dance-tip`; free reads [api/club/leaderboard.js](api/club/leaderboard.js), [api/club/tips.js](api/club/tips.js), [api/club/tips-stream.js](api/club/tips-stream.js) `→ /api/club/tips/stream` (SSE), [api/club/presence.js](api/club/presence.js); payouts [api/\_lib/club/payouts.js](api/_lib/club/payouts.js) via the `/api/cron/club-payouts` job; assets [public/club/](public/club) | Live | The platform's showcase of x402 as a live interaction loop rather than a billing detail: a $0.01 USDC cover charge at the door (with an on-chain bouncer that reads the paying wallet's ban list and prior visits, and a device-cached pass so one cover lasts the night), then $0.001 USDC per routine at three poles. A settled tip is what puts a dancer on the pole, so the payment IS the interaction. Third-person walk-in through alley → gallery → clubhouse → stage before the room opens; dancers are ordinary gallery avatars retargeted onto the shared clip library, swappable per pole. Tips land live over SSE with REST backfill on reconnect, and per-dancer earnings accrue to `club_dancer_wallets` for the payout sweep. `/club?demo` is the express entry that skips the cover for QA and recordings. |@@ -222,6 +223,7 @@ bottom.| Seeker / Saga dApp Store app | [solana-mobile/](solana-mobile): TWA wrapper [solana-mobile/twa/](solana-mobile/twa), Publisher Portal listing copy [solana-mobile/publish/](solana-mobile/publish), MWA wallet + Seeker detection [solana-mobile/src/](solana-mobile/src) | In-repo · signed APK + assetlinks live · awaiting owner's Publisher Portal submission | Everything needed to package three.ws as a Solana Mobile app and publish it to the on-chain dApp Store. Targets Seeker first; compatible with Saga Gen 1 and Gen 2. Docs: [solana-mobile/README.md](solana-mobile/README.md) || iOS App Store app | [ios/](ios): Capacitor shell + config [ios/capacitor.config.ts](ios/capacitor.config.ts), Xcode project [ios/native/App/](ios/native/App), web-side native bridge [ios/src/native-bridge.js](ios/src/native-bridge.js), offline shell [ios/shell/](ios/shell), listing copy [ios/publish/](ios/publish), app association handler in [api/wk.js](api/wk.js) | In-repo · project builds and the web half ships on every deploy · awaiting an Apple Developer organization account | three.ws as a native iOS app (`ws.three.app`). A Capacitor 8 shell whose WKWebView runs the live `https://three.ws`, so the app is never a version behind the site; what makes it an app is the native layer around it. `ios/src/native-bridge.js` ships with the SITE, not the .ipa (Capacitor injects its bridge into the remote page, so `window.Capacitor` exists on three.ws only inside the app): it supplies the `navigator.share` WKWebView does not have, routes off-site links to an in-app Safari sheet instead of stranding the app's only WebView, handles universal links and `threews://` wallet returns, holds the launch screen until the first real frame, and marks `html.ios-app`. The `three-ws-ios-native-bridge` plugin in [vite.config.js](vite.config.js) copies it into `dist/` content-hashed and injects it into every built page except the third-party embed entries (671 pages, `/viewer` and `/ar` included, which a `transformIndexHtml` could not reach because they are copied verbatim from `public/`). `GET /.well-known/apple-app-site-association` is served from the API rather than a static file because Apple demands an exact path, a JSON content type and no redirect; it answers `503 not_configured` until `APPLE_TEAM_ID` is set rather than publishing an association that would fail silently on device. Docs: [ios/README.md](ios/README.md), [docs/ios-app.md](docs/ios-app.md), App Review posture [ios/docs/REVIEW-RISK.md](ios/docs/REVIEW-RISK.md), submission [ios/docs/SUBMISSION.md](ios/docs/SUBMISSION.md). || Walk Avatar browser extension | [extensions/walk-avatar/](extensions/walk-avatar) — MV3 `manifest.json`, `background.js` | In-repo · Chrome Web Store release checklist staged ([RELEASE.md](extensions/walk-avatar/RELEASE.md)) | Walks your three.ws avatar across any site and reads pages aloud — a browsing companion built on the same rig as the [walk-sdk](walk-sdk). Ships its own store-required [PRIVACY.md](extensions/walk-avatar/PRIVACY.md), [PERMISSIONS.md](extensions/walk-avatar/PERMISSIONS.md), and [TERMS.md](extensions/walk-avatar/TERMS.md). |+| Checkout companion browser extension | [extensions/checkout-companion/](extensions/checkout-companion) (MV3: [extract.js](extensions/checkout-companion/extract.js), [content.js](extensions/checkout-companion/content.js), [panel.js](extensions/checkout-companion/panel.js), [background.js](extensions/checkout-companion/background.js)), analysis [api/_lib/companion/checkout.js](api/_lib/companion/checkout.js), endpoint [api/companion/checkout.js](api/companion/checkout.js) | In-repo | The companion at the moment money moves: on a checkout page it reports the total against the price you were shown, money the page did not itemise, fees named and summed, whether the charge repeats, and the cancellation terms. **Arithmetic is never the model's job** (integer minor units, computed server-side) and **no finding is ever a legal verdict** (`sanitizeModelFindings()` drops any that claims an amount or calls something illegal). With no model reachable the arithmetic findings still stand. The extension **never reads an input**: `collectText`/`collectAmounts` refuse form fields, iframes and editable regions structurally, and redaction runs in the browser before anything is sent; only the hostname travels and nothing about the page is stored. Docs: [docs/checkout-companion.md](docs/checkout-companion.md). Tests: [tests/companion-checkout.test.js](tests/companion-checkout.test.js), [tests/checkout-extract.test.js](tests/checkout-extract.test.js) || Desktop companion app | [apps/desktop/](apps/desktop) — Electron main [src/main.js](apps/desktop/src/main.js), preload [src/preload.cjs](apps/desktop/src/preload.cjs), stage [src/renderer/](apps/desktop/src/renderer) | In-repo · packaged with electron-builder (`npm run dist`), not yet published | A transparent, click-through, always-on-top character that strolls across the bottom of the desktop and walks over to deliver what cleared the user's bar. Subscribes to `/api/companion/stream` with the same bridge token the CLI stores, and drives the published [walk embed](pages/walk-embed.html) over its postMessage contract, so it carries no 3D code of its own. Not an npm workspace: it installs and builds on its own (see [apps/desktop/README.md](apps/desktop/README.md)). || DCC tool integrations (Blender, ComfyUI) | [integrations/](integrations) — [integrations/blender/](integrations/blender), [integrations/comfyui/](integrations/comfyui), shared Python client [integrations/_pyclient/](integrations/_pyclient) | In-repo | First-party plugins that drive the public Forge pipeline (`/api/forge`) from inside the tools artists already use, so a model is generated without leaving the DCC. Docs: [integrations/README.md](integrations/README.md) || Base58 difficulty model (the honest math) | [src/solana/vanity/base58-distribution.js](src/solana/vanity/base58-distribution.js), dispatch in [src/solana/vanity/validation.js](src/solana/vanity/validation.js); ported copies in [solana-agent-sdk/src/vanity/verify.ts](solana-agent-sdk/src/vanity/verify.ts) and [mcp-server/src/lib/base58-distribution.js](mcp-server/src/lib/base58-distribution.js), held in agreement by [tests/vanity-model-parity.test.js](tests/vanity-model-parity.test.js) | In-repo | The exact probability that a random Solana address matches a vanity pattern, and the single source of truth behind every quote, price, rarity tier, bounty payout and signed receipt. Base58 is a positional encoding of a 256-bit integer, so the *leading* character is not uniform: the 40 symbols `K`-`z` are 17.2x harder to lead with than `5`-`H`, a 58x spread the old flat 58ⁿ model erased. Models are versioned (`base58-exact/v2`, superseding `58^effectiveLength`) and receipts name theirs, so attestations issued before the correction still verify. Spec: [docs/PROTOCOL-vanity.md](docs/PROTOCOL-vanity.md#41-difficulty-model-versioning) |diff --git a/data/changelog.json b/data/changelog.jsonindex 9f206c68a..b255ee750 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,25 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security. `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-08-28",+ "title": "Your agent reads the checkout before you pay",+ "summary": "A new browser extension puts the companion on the one screen where it is worth the most: the payment page. It tells you the total against the price you were actually shown, names money the page never itemised, adds up the fees, and reads the fine print for the things that catch people out, a trial that turns into an annual charge, a renewal at a different price, a cancellation notice period. Every amount it quotes is computed rather than read off a language model, so the arithmetic still works when nothing else does, and it never calls a charge illegal or a scam because that is not a call it is in a position to make. It never reads a form field: your card number, security code and address are structurally unreadable to it, personal data is stripped in your own browser before anything is sent, only the site's hostname travels, and nothing about the page is stored anywhere.",+ "tags": [+ "feature",+ "security"+ ],+ "link": "/companion"+ },+ {+ "date": "2026-08-28",+ "title": "x402 Preflight: check whether a seller can take your money before you pay",+ "summary": "Paying an AI agent for a service tells you the price, but nothing tells you whether that seller can still complete the transaction. If its own fee wallet has run dry, you find out only after you have signed and paid, and the money and the moment are both gone. Preflight is a small, signed statement any seller can publish saying which payment networks it can currently settle on, how well recent payments have gone, and which other network to use instead when one is down. It expires within a minute, so nobody can wave an old healthy report through an outage, and it is signed, so a seller that says it can deliver has gone on record. three.ws now publishes one, and there is a free page, a command-line tool, an agent tool and an open-source client for reading anyone else's. The format is open: no permission needed, nothing routed through us.",+ "tags": [+ "feature",+ "sdk"+ ]+ },{"date": "2026-08-28","title": "Your 3D agent now runs in a terminal, with nothing installed",