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
fix(mcp,api): tighten the MCP auth and payment gates and the media read handlers
nirholas78362cbe13ca
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 7389cc03b..46bee73f5 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,6 +18,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Memory seeding reads Farcaster with no vendor key, and X now works from the app credentials we already hold**: The memory-seeding demo asks a GitHub, X or Farcaster handle what it can learn about you in public, then writes a short memory seed your agent can carry. Two of those three connectors were showing a "connector not configured" card to everyone, because each insisted on a vendor key nobody had set. Farcaster now reads through the same failover the rest of the platform uses: an indexer when a key exists, and a public Farcaster hub with no key at all otherwise, so it returns real profiles and casts on any deployment. Anything the keyless lane genuinely cannot know, such as follower counts, is now shown as unknown instead of zero. The X connector accepts the app key and secret the platform already stores, exchanging them for a read-only token itself, so it no longer needs a separate token provisioned by hand. A mistyped Farcaster name now comes back as not found rather than as an upstream outage, and all four endpoints are documented in the API reference for the first time. (`/demos/memory-seed`) `[fix, improvement, docs]`- **Mistyped filters on the revenue, checkout and ring endpoints answer plainly instead of failing**: The public revenue feed, the checkout SKU API and the ring report all took values straight from the URL into the database. A timestamp that was not a timestamp, a checkout id that was not an id, and the query fell over: the caller got an opaque "something went wrong" with a support reference, and our own alerting logged a fault that was only ever a typo. All three now say what was wrong, in words, with the right status code. The ring report also stops treating an unrecognised period as "show me everything", which quietly answered the wrong question and ran the most expensive query it has. The revenue feed now echoes back the endpoint filter it actually applied rather than the raw text it was sent, and the paid-call lookup only accepts something shaped like a real transaction signature. (`/x402-revenue`) `[fix]`- **Robinhood Chain worlds survive a hiccup in the live feed instead of going dark**: The in-world trading terminal inside a Robinhood Chain world polls the chain feed every five seconds, and the Worlds lobby lists those coins from the same feed. A single event that arrived without its payload, or with a timestamp the chain wrote in an unexpected format, took both requests down with a server error: the terminal showed a dead tape, and the lobby's Robinhood Chain tab quietly emptied with nothing on screen to say why. Bad events are now skipped and the rest of the tape still renders, a price that is genuinely missing stays blank rather than printing as a real $0 trade, and a launch with no readable contract address no longer produces a card that leads nowhere. Asking for trades with an address that is not a contract address now gets a clear error back instead of an empty list that read as "this coin has never traded". (`/worlds`) `[fix]`+- **Scrolling the activity feed past a bad cursor no longer breaks the whole feed**: An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain "that is not a timestamp" so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows. (`/community`) `[fix]`- **Shared agent links keep their preview card through a chain hiccup**: The preview card for an on-chain agent is rendered on demand from the chain and the agent's manifest. When either read was slow or briefly unavailable, the card answered as if the agent did not exist, and social sites cached that answer for up to an hour, so a link to a real agent unfurled with no image at all. The card is now served either way and only kept for a minute when a read fell short, so the next crawl picks up the real thing. Alongside it, ten agent endpoints (the preview card and page, the oEmbed provider, memory sync, the action log, ask, delegate and team tasks) now answer a mistyped agent id with a clear, specific error instead of a generic server failure. `[fix, improvement]`- **Sharing an agent link posts the agent's picture again**: Pasting a link to an agent into a chat app, a social post or a group thread is supposed to unfurl into a card with the agent's name, its description and a picture of it. For every agent that actually has an avatar picture, which is nearly all of them, the page that builds that card was crashing instead, so the link unfurled as a bare URL with nothing attached. The card now renders with the agent's own thumbnail, falls back to a freshly rendered portrait when an agent has no thumbnail yet, and an unknown or malformed agent link sends the visitor to the app instead of erroring. `[fix]`- **Skill marketplace: installs are locked to your own clicks, and edits keep their star rating**: Three fixes to the skills marketplace. Installing or removing a skill now carries the same one-time security token every other account action does, so a page you happen to have open elsewhere can no longer quietly add skills to your account behind your back. Editing one of your published skills used to answer back with its rating blanked out, which made the detail panel show 'No ratings yet' on a skill people had actually rated until you reloaded; it now reports the real average and count. And when a skill you were paging past gets deleted or made private mid-scroll, 'Load more' stops cleanly instead of looping the first page of results back into the grid over and over. (`/marketplace`) `[fix, security]`diff --git a/api/_lib/solana/connection.js b/api/_lib/solana/connection.jsindex cdd0c8012..3673a92d2 100644--- a/api/_lib/solana/connection.js+++ b/api/_lib/solana/connection.js@@ -1038,8 +1038,27 @@ export function shouldRotate(status) {// failover signal), so it is upstream weather, never a caller defect. Matching// the wrapper rather than any single vendor code keeps this true for the next// provider that invents one.+//+// `StructError` is in the set for the same reason, one layer up. classifyRpcBody+// above catches the 200 bodies it can recognize as garbage (empty, HTML,+// unparseable, an envelope with neither result nor error), but it deliberately+// accepts envelopes that are valid JSON-RPC yet NOT what web3.js will parse:+// a numeric `id`, a missing `jsonrpc`, or an `error` whose `message` is not a+// string all satisfy classifyRpcBody and then fail web3.js's superstruct check+// (createRpcResult pins `id: string()` and `jsonrpc: literal('2.0')`). Loosening+// classifyRpcBody is not the fix, because the same guard serves the pass-through+// proxy in api/solana-rpc.js, where those envelopes are perfectly good answers.+// So the lane-level throw has to be readable here instead. Production+// 2026-08-13T10:32Z, one treasury-topup tick 500ed on exactly this:+// [api] unhandled Error: failed to get balance of account Wwwu...WwW:+// StructError: Expected the value to satisfy a union of `type | type`,+// but received: [object Object]+// Every superstruct call in web3.js validates something the NODE sent (RPC+// responses, subscription notifications, parsed account data), never a caller+// argument, so a StructError reaching us is always "we could not read the+// answer", which is the same upstream weather as a 429.export function isTransientRpcError(err) {- return /\b(429|500|502|503|504)\b|-32429|max usage reached|rate.?limit|quota|exhausted|timed?\s*out|fetch failed|socket hang up|ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|all solana rpc endpoints failed|all rpc endpoints exhausted|solana rpc provider error/i.test(+ return /\b(429|500|502|503|504)\b|-32429|max usage reached|rate.?limit|quota|exhausted|timed?\s*out|fetch failed|socket hang up|ECONNRESET|ETIMEDOUT|ECONNREFUSED|EAI_AGAIN|all solana rpc endpoints failed|all rpc endpoints exhausted|solana rpc provider error|StructError|Expected the value to satisfy/i.test(String(err && err.message ? err.message : err),);}diff --git a/api/_mcp/auth.js b/api/_mcp/auth.jsindex b9349a02b..31005cc8e 100644--- a/api/_mcp/auth.js+++ b/api/_mcp/auth.js@@ -172,7 +172,7 @@ export async function authenticateRequest(x402Ctx,};} catch (err) {- await sendX402Error(res, { resourceUrl, accepts: requirements }, err);+ await sendX402Error(res, { resourceUrl, accepts: requirements, challenge }, err);return null;}}diff --git a/api/_mcp/payments.js b/api/_mcp/payments.jsindex 5e853e67d..e42a26417 100644--- a/api/_mcp/payments.js+++ b/api/_mcp/payments.js@@ -7,9 +7,17 @@ import { reportServerError } from '../_lib/http.js';// this module. See payment-identifier-server.js for the full rationale.export { reservePaymentProof } from '../_lib/x402/payment-identifier-server.js';-export async function sendX402Error(res, { resourceUrl, accepts }, err) {+// `challenge` (optional) is the endpoint's own service metadata, the same object+// it hands authenticateRequest/handleSse. It MUST be threaded through here too:+// a payment that fails verification or settlement re-issues the 402, and without+// it that retry envelope described the main /api/mcp server to a payer who+// called a dedicated endpoint (the Bazaar, the 3D studio, Granite). Confirmed+// live on 2026-08-16: /api/mcp-bazaar answered a bad payment with the main+// server's description and no serviceName/tags/iconUrl.+export async function sendX402Error(res, { resourceUrl, accepts, challenge }, err) {if (err instanceof X402Error) {- if (err.status === 402) return await send402(res, { resourceUrl, accepts, error: err.message });+ if (err.status === 402)+ return await send402(res, { resourceUrl, accepts, ...(challenge || {}), error: err.message });res.statusCode = err.status;res.setHeader('content-type', 'application/json; charset=utf-8');res.end(JSON.stringify({ error: err.code, error_description: err.message }));diff --git a/api/avatar-og.js b/api/avatar-og.jsindex 26ece4894..1706bd1e9 100644--- a/api/avatar-og.js+++ b/api/avatar-og.js@@ -21,8 +21,8 @@import { sql } from './_lib/db.js';import { getAvatar } from './_lib/avatars.js';-import { cors, wrap } from './_lib/http.js';-import { publicUrl, putObject, isLegacyOgThumbnailKey } from './_lib/r2.js';+import { cors, method, wrap } from './_lib/http.js';+import { putObject } from './_lib/r2.js';import { renderGlbToPng } from './_lib/render-glb.js';import { thumbBackdropFor } from './_lib/avatar-thumbs.js';@@ -46,6 +46,10 @@ const _renderLocks = new Map();export default wrap(async (req, res) => {if (cors(req, res, { methods: 'GET,OPTIONS' })) return;+ // A crawler only ever GETs (or HEADs, which method() folds into GET). Gate the+ // rest: the miss path launches chromium and writes to R2, so an unguarded POST+ // is a free way to make the origin do the most expensive work it has.+ if (!method(req, res, ['GET'])) return;const url = new URL(req.url, 'http://x');const avatarId = url.searchParams.get('id') || extractIdFromPath(url.pathname);@@ -65,24 +69,23 @@ export default wrap(async (req, res) => {});}- // Cached thumbnail — either client-uploaded (customizer save) or a- // previous server render. Either way it's a real R2 object; redirect.- // Exception: a legacy poisoned key (absolute, origin-pointing, written by the- // pre-fix ogKeyFor) would 302 to a 404, so clear it and fall through to a- // fresh render that writes the corrected bucket key.+ // Cached thumbnail — either client-uploaded (customizer save) or a previous+ // server render. Either way it's a real R2 object; redirect.+ //+ // Legacy poisoned keys (absolute, origin-pointing `*_og.png`, written by the+ // pre-fix ogKeyFor) never reach this branch: `thumbnailUrl()` in+ // api/_lib/r2.js already refuses to resolve them and hands back null. Do NOT+ // re-run that check against `thumbnail_url` here: it is a bucket URL, so a+ // perfectly good server-rendered thumbnail (`.../u/uid/x/abc_og.png`) matches+ // the poisoned-key shape too, and the endpoint ends up wiping its own cache+ // on every crawl. The healing write for a genuinely poisoned key lives in+ // renderAndCache's write-back guard instead.if (avatar.thumbnail_url) {- if (isLegacyOgThumbnailKey(avatar.thumbnail_url)) {- await sql`- update avatars set thumbnail_key = null, updated_at = now()- where id = ${avatar.id} and deleted_at is null- `.catch(() => {});- } else {- res.statusCode = 302;- res.setHeader('location', avatar.thumbnail_url);- res.setHeader('cache-control', CACHE_REDIR);- res.end();- return;- }+ res.statusCode = 302;+ res.setHeader('location', avatar.thumbnail_url);+ res.setHeader('cache-control', CACHE_REDIR);+ res.end();+ return;}// Private avatars have no public model_url, so headless chromium can't@@ -155,11 +158,15 @@ async function renderAndCache({ avatar }) {});// Single UPDATE — bypasses ownership/visibility checks in// updateAvatar() because this is an internal cache write, not a- // user-initiated edit. Guarded by `thumbnail_key is null` so a- // concurrent customizer-save snapshot isn't clobbered.+ // user-initiated edit. Guarded so a concurrent customizer-save snapshot+ // isn't clobbered: it only writes over an empty slot, or over a legacy+ // poisoned key (an absolute, origin-pointing `*_og.png` from the pre-fix+ // ogKeyFor). Without that second arm a poisoned row could never be+ // repaired, so it would re-render through chromium on every single crawl.await sql`update avatars set thumbnail_key = ${ogKey}, updated_at = now()- where id = ${avatar.id} and deleted_at is null and thumbnail_key is null+ where id = ${avatar.id} and deleted_at is null+ and (thumbnail_key is null or thumbnail_key ~* '^https?://.*_og[.]png$')`;return png;})();diff --git a/api/bounties.js b/api/bounties.jsindex 8afccd68a..efdf03d92 100644--- a/api/bounties.js+++ b/api/bounties.js@@ -3,6 +3,7 @@ import { cors, json, error, readJson, wrap, method, rateLimited } from './_lib/himport { getSessionUser } from './_lib/auth.js';import { requireCsrf } from './_lib/csrf.js';import { limits } from './_lib/rate-limit.js';+import { parseLimit, parseOffset } from './_lib/http-params.js';import { enrichLikes } from './_lib/bounty-likes.js';import { solUsdPrice } from './_lib/avatar-wallet.js';@@ -12,8 +13,11 @@ export default wrap(async (req, res) => {if (req.method === 'GET') {const url = new URL(req.url, 'http://localhost');const tab = url.searchParams.get('tab') || 'trending';- const limit = Math.min(parseInt(url.searchParams.get('limit') || '30', 10), 50);- const offset = Math.max(parseInt(url.searchParams.get('offset') || '0', 10), 0);+ // Shared clamps, not hand-rolled ones: `parseInt('abc')` is NaN, and NaN+ // survives Math.min/Math.max unchanged, so `?limit=abc` used to reach+ // Postgres as `LIMIT NaN` and 500. See api/_lib/http-params.js.+ const limit = parseLimit(url.searchParams, { fallback: 30, max: 50 });+ const offset = parseOffset(url.searchParams);// Optional: identify the caller so submission cards know what they've liked.const userId = (await getSessionUser(req).catch(() => null))?.id || null;diff --git a/api/characters.js b/api/characters.jsindex e9fd11469..524fca5aa 100644--- a/api/characters.js+++ b/api/characters.js@@ -9,7 +9,7 @@*/import { sql } from './_lib/db.js';-import { cors, json, method, wrap, rateLimited } from './_lib/http.js';+import { cors, error, json, method, wrap, rateLimited } from './_lib/http.js';import { clampInt } from './_lib/http-params.js';import { limits, clientIp } from './_lib/rate-limit.js';import { thumbnailUrl } from './_lib/r2.js';@@ -27,10 +27,15 @@ export default wrap(async (req, res) => {const q = (url.searchParams.get('q') || '').trim().slice(0, 80);const sort = url.searchParams.get('sort') === 'chats' ? 'chats' : 'new';- const cursorDate = cursor ? new Date(cursor) : null;+ // The cursor is echoed back from `next_cursor`, so anything unparseable is a+ // hand-edited URL. Reject it at the boundary: `new Date('junk').toISOString()`+ // throws a RangeError, which surfaced as a 500 on a caller mistake.+ if (cursor && Number.isNaN(Date.parse(cursor))) {+ return error(res, 400, 'bad_request', 'cursor must be an ISO timestamp');+ }const qLike = q ? '%' + q + '%' : null;- const cursorIso = cursorDate ? cursorDate.toISOString() : null;+ const cursorIso = cursor ? new Date(cursor).toISOString() : null;const sortByChats = sort === 'chats';// The CASE-based sort references the derived `chat_count`. Postgres onlydiff --git a/api/ibm-mcp.js b/api/ibm-mcp.jsindex 2b54b21c1..f9bdf2751 100644--- a/api/ibm-mcp.js+++ b/api/ibm-mcp.js@@ -124,7 +124,11 @@ export default wrap(async (req, res) => {} catch (err) {return sendX402Error(res,- { resourceUrl: x402Ctx.resourceUrl, accepts: x402Ctx.requirements },+ {+ resourceUrl: x402Ctx.resourceUrl,+ accepts: x402Ctx.requirements,+ challenge: GRANITE_CHALLENGE,+ },err,);}diff --git a/api/mcp-3d.js b/api/mcp-3d.jsindex 0d87142a7..f0ba03c12 100644--- a/api/mcp-3d.js+++ b/api/mcp-3d.js@@ -116,7 +116,11 @@ export default wrap(async (req, res) => {} catch (err) {return sendX402Error(res,- { resourceUrl: x402Ctx.resourceUrl, accepts: x402Ctx.requirements },+ {+ resourceUrl: x402Ctx.resourceUrl,+ accepts: x402Ctx.requirements,+ challenge: STUDIO_CHALLENGE,+ },err,);}diff --git a/api/mcp-agent.js b/api/mcp-agent.jsindex 5333a67d6..9842da285 100644--- a/api/mcp-agent.js+++ b/api/mcp-agent.js@@ -109,7 +109,11 @@ export default wrap(async (req, res) => {} catch (err) {return sendX402Error(res,- { resourceUrl: x402Ctx.resourceUrl, accepts: x402Ctx.requirements },+ {+ resourceUrl: x402Ctx.resourceUrl,+ accepts: x402Ctx.requirements,+ challenge: AGENT_CHALLENGE,+ },err,);}diff --git a/api/mcp-bazaar.js b/api/mcp-bazaar.jsindex 9c4af8399..00ee9fa78 100644--- a/api/mcp-bazaar.js+++ b/api/mcp-bazaar.js@@ -110,7 +110,11 @@ export default wrap(async (req, res) => {} catch (err) {return sendX402Error(res,- { resourceUrl: x402Ctx.resourceUrl, accepts: x402Ctx.requirements },+ {+ resourceUrl: x402Ctx.resourceUrl,+ accepts: x402Ctx.requirements,+ challenge: BAZAAR_CHALLENGE,+ },err,);}diff --git a/data/changelog.json b/data/changelog.jsonindex fab492c24..d704de1f0 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,15 @@{"$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-16",+ "title": "Scrolling the activity feed past a bad cursor no longer breaks the whole feed",+ "summary": "An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain \"that is not a timestamp\" so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows.",+ "tags": [+ "fix"+ ],+ "link": "/community"+ },{"date": "2026-08-16","title": "Agent share cards survive an unconfigured bucket, and a mistyped payment mint is refused instead of listed",diff --git a/data/examples.json b/data/examples.jsonindex 2ea6f44ed..5b73303ac 100644--- a/data/examples.json+++ b/data/examples.json@@ -2,10 +2,10 @@"$comment": "Generated by scripts/build-examples-index.mjs from what is on disk. Do not edit by hand; run npm run build:examples.","generated_by": "scripts/build-examples-index.mjs","counts": {- "total": 43,+ "total": 45,"html_demos": 11,"projects": 10,- "packages": 22+ "packages": 24},"examples": [{@@ -226,6 +226,37 @@"readme": "concierge-sdk/examples/README.md","owner": "concierge-sdk"},+ {+ "id": "package:packages/kol-mcp",+ "kind": "package",+ "group": "Package examples",+ "title": "@three-ws/kol-mcp",+ "description": "Track one smart trader from any AI agent - a tracked KOL wallet's portfolio P&L (realized/unrealized, win rate, top holding) and its trades on a given mint. Read-only over the live public three.ws KOL API. No key, no signer, no payment.",+ "path": "packages/kol-mcp/examples",+ "files": [+ "list-tools.mjs",+ "wallet-card.mjs"+ ],+ "run": "node packages/kol-mcp/examples/list-tools.mjs",+ "runKind": "command",+ "readme": null,+ "owner": "packages/kol-mcp"+ },+ {+ "id": "package:packages/loom-mcp",+ "kind": "package",+ "group": "Package examples",+ "title": "@three-ws/loom-mcp",+ "description": "Loom - the three.ws community 3D-creation gallery from any AI agent. Browse the public feed of community-forged GLB creations, fetch one with its viewer URL, and submit your own. Public API, no key required.",+ "path": "packages/loom-mcp/examples",+ "files": [+ "list-tools.mjs"+ ],+ "run": "node packages/loom-mcp/examples/list-tools.mjs",+ "runKind": "command",+ "readme": null,+ "owner": "packages/loom-mcp"+ },{"id": "package:packages/marketplace-mcp","kind": "package",diff --git a/docs/examples.md b/docs/examples.mdindex 320a6d7e1..98792bdb2 100644--- a/docs/examples.md+++ b/docs/examples.md@@ -735,7 +735,7 @@ genuinely invested in the user's progress.## Every runnable example in the repo-The repo ships 43 examples: 11 web component demos, 10 end-to-end projects, and 22 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).+The repo ships 45 examples: 11 web component demos, 10 end-to-end projects, and 24 package example sets. This table is generated from what is on disk, so it cannot list one that was deleted or miss one that was added. The machine-readable version is [data/examples.json](../data/examples.json).### Example projects@@ -761,6 +761,8 @@ The repo ships 43 examples: 11 web component demos, 10 end-to-end projects, and| [`avatar-sdk/examples`](../avatar-sdk/examples) | A self-contained page, no build step. It loads the SDK's @three-ws/avatar/agent entry from a CDN, awaits ensureAgent3D() to register the <agent-3d> element, and renders the real three.ws default avatar using the documented src and kiosk attributes. | `npm run dev, then open /avatar-sdk/examples/index.html` || [`packages/avatar-schema/examples`](../packages/avatar-schema/examples) | JSON Schema and validator for three.ws on-chain avatar manifests - the canonical, hash-anchored format any cross-chain client can use to resolve an avatar. | Reference files, nothing to execute || [`concierge-sdk/examples`](../concierge-sdk/examples) | Runnable examples for every way to use the concierge. The HTML files load the SDK from ../dist, build it first (npm run build in the package root), then serve this folder (npx serve .) and open each file. | `npm run dev, then open /concierge-sdk/examples/custom-avatar.html` |+| [`packages/kol-mcp/examples`](../packages/kol-mcp/examples) | Track one smart trader from any AI agent - a tracked KOL wallet's portfolio P&L (realized/unrealized, win rate, top holding) and its trades on a given mint. Read-only over the live public three.ws KOL API. No key, no signer, no payment. | `node packages/kol-mcp/examples/list-tools.mjs` |+| [`packages/loom-mcp/examples`](../packages/loom-mcp/examples) | Loom - the three.ws community 3D-creation gallery from any AI agent. Browse the public feed of community-forged GLB creations, fetch one with its viewer URL, and submit your own. Public API, no key required. | `node packages/loom-mcp/examples/list-tools.mjs` || [`packages/marketplace-mcp/examples`](../packages/marketplace-mcp/examples) | Two runnable examples. Both spawn this package's own MCP server over stdio (the same node src/index.js entry point the README documents), speak real MCP JSON-RPC to it, and read the live public marketplace. | `node packages/marketplace-mcp/examples/browse-marketplace.mjs` || [`mcp-server/examples`](../mcp-server/examples) | Two zero-dependency walkthroughs of the MCP Streamable HTTP lifecycle against the live three.ws server at https://three.ws/api/mcp (MCP 2025-06-18, JSON-RPC 2.0). | `node mcp-server/examples/client.mjs` || [`page-agent-sdk/examples`](../page-agent-sdk/examples) | Run these from the package root with any static server so the import map can resolve the unbundled source from ../src: | `npm run dev, then open /page-agent-sdk/examples/custom-avatar.html` |diff --git a/docs/media-api.md b/docs/media-api.mdindex ef502f234..3fbd4ea93 100644--- a/docs/media-api.md+++ b/docs/media-api.md@@ -807,8 +807,13 @@ Fields are `null` until the stage that produces them completes; on failure| Malformed `?job=` | `400 invalid_job` (missing entirely: `400 missing_job`) || Worker not deployed on this environment | `503 unconfigured` || Worker rejected the job | `502 segment_failed` |+| Worker unreachable while polling | `502 segment_status_failed` || Rate limit | `429` with `Retry-After` |+A poll that answers `502 segment_status_failed` carries no `status` field, so a+polling client should keep polling: the worker was briefly unreachable, which is+not the same as the job dying.+### curl```bash@@ -855,8 +860,13 @@ auth; rate-limited per IP.| Malformed `?job=` | `400 invalid_job` (missing entirely: `400 missing_job`) || Worker not deployed on this environment | `503 unconfigured` || Worker rejected the job | `502 rembg_failed` |+| Worker unreachable while polling | `502 rembg_status_failed` || Rate limit | `429` with `Retry-After` |+A poll that answers `502 rembg_status_failed` carries no `status` field, so a+polling client should keep polling: the worker was briefly unreachable, which is+not the same as the job dying.+### curl```bashdiff --git a/prompts/swarm-100/api-seed-01.md b/prompts/swarm-100/api-seed-01.mddeleted file mode 100644index 8d689dfaf..000000000--- a/prompts/swarm-100/api-seed-01.md+++ /dev/null@@ -1,104 +0,0 @@-# API audit: api/seed batch 01 (4 files)--How to run: paste this file's repo path into a fresh Claude Code chat in this-repository and say "run this work order". This file is fully self-contained:-it depends on no other prompt file anywhere. If neighboring files in-prompts/swarm-100/ are gone, that work is done; if present, ignore them.-Every claim below rots; step 0 re-measures, and what you measure wins.--## Operating clause (binding)--- Read CLAUDE.md first. Its rules override everything, including this file.-- Finish 100% in this session. Never end the turn with a question, an option- list, or an unexecuted plan. A judgment call goes in one line of the final- report; it never becomes a question that halts work.-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real- funds or any irreversible on-chain write, git push or a production deploy,- committing content that references a crypto project other than $THREE, and- destroying unrecoverable data.-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no- commented-out code. Real APIs and real integrations only.-- The em-dash and en-dash characters are banned in everything you write.-- Concurrent agents share this worktree: stage explicit paths only (never a- bare add-everything), and commit finished work promptly.-- Before committing, run: npm run check:rules -- --paths <files you touched>.- It must exit 0.--## Step 0: re-derive the current state--1. Confirm each file below still exists; deleted ones are done, skip them.-2. For each, decide routability: grep its path in vercel.json and read how- server/index.mjs maps filesystem handlers. Routed files get an endpoint- audit; internal modules get a code and test audit.-3. Start a local server for endpoint checks: node server/index.mjs with .env- loaded, on a free PORT if 3000 is busy.--## Task: audit these api files, then fix everything found--Files in this batch:--- api/seed/farcaster.js-- api/seed/github.js-- api/seed/synthesize.js-- api/seed/x.js--For every routed handler:--1. Exercise it with curl against the local server: the success path returns- real data with the correct status; malformed input returns a 4xx JSON- error, never a stack trace or an HTML error page; auth is enforced where- the code intends it; CORS matches neighboring handlers.-2. Hard-rule scan: no mock fallbacks, no fake-data arrays, no stubbed- responses, no unfinished markers. Errors are handled at the boundary and- internal code trusts itself.-3. Do not spend funds or sign anything on-chain while probing. Payment and- trading handlers get their validation and error paths exercised, never a- live settlement.--For every internal (non-routed) module:--4. Something must import it; if nothing does, delete it as dead code (verify- with a repo-wide grep first).-5. Its main path and one failure path must be covered in tests/; add the- missing test if not.--## Definition of done--- [ ] Every listed file has recorded evidence: a curl transcript for routed- handlers, a passing test or a deletion for internal modules.-- [ ] Zero hard-rule violations remain in these files.-- [ ] vitest run passes; npm run check:rules -- --paths <touched files>- exits 0.--## Never blocked--| Blocker | Resolution (act, do not ask) |-|---|---|-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |-| Playwright browser missing | npx playwright install chromium |-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |--## Close out (required)--1. Verify every Definition of done line with the actual command output in- front of you. Never claim a line you did not verify.-2. Commit with explicit paths and a subject that describes the diff (house- style: type(scope): what changed and why a reader cares).-3. Delete this prompt file in that same commit:-- git rm prompts/swarm-100/api-seed-01.md-- The shrinking directory is this campaign's only progress ledger; there is- no progress log to update.-4. Final report: what step 0 measured, what changed (file list), evidence per- Definition of done line, and any one-line judgment calls. No trailing- questions, no unexecuted plans.--If a line genuinely cannot pass inside this session (an external party must-respond, or an owner-gated action is the final step), finish everything else,-leave this file in place, and state exactly which line remains and who owns-it. Never delete this file on a partial.diff --git a/public/changelog.json b/public/changelog.jsonindex 935e7470a..5d857697b 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-16T08:12:02.988Z",+ "generated_at": "2026-08-16T16:02:33.886Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -134,6 +134,16 @@"fix"]},+ {+ "date": "2026-08-16",+ "type": "update",+ "title": "Scrolling the activity feed past a bad cursor no longer breaks the whole feed",+ "summary": "An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain \"that is not a timestamp\" so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows.",+ "link": "/community",+ "tags": [+ "fix"+ ]+ },{"date": "2026-08-16","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex 26d2132cb..15046265c 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -102,6 +102,14 @@<category>fix</category><description>The in-world trading terminal inside a Robinhood Chain world polls the chain feed every five seconds, and the Worlds lobby lists those coins from the same feed. A single event that arrived without its payload, or with a timestamp the chain wrote in an unexpected format, took both requests down with a server error: the terminal showed a dead tape, and the lobby's Robinhood Chain tab quietly emptied with nothing on screen to say why. Bad events are now skipped and the rest of the tape still renders, a price that is genuinely missing stays blank rather than printing as a real $0 trade, and a launch with no readable contract address no longer produces a card that leads nowhere. Asking for trades with an address that is not a contract address now gets a clear error back instead of an empty list that read as "this coin has never traded".</description></item>+ <item>+ <title>Scrolling the activity feed past a bad cursor no longer breaks the whole feed</title>+ <link>https://three.ws/community</link>+ <guid isPermaLink="false">2026-08-16:Scrolling the activity feed past a bad cursor no longer breaks the whole feed</guid>+ <pubDate>Sun, 16 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>An audit of the account endpoints found one real break and two smaller ones. The activity feed on /community and your personal feed ask for the next page of results by passing the last item’s timestamp back; if that value arrived malformed, from a hand-edited link or a stale bookmark, the database rejected it and the entire feed came back as a server error with nothing to act on. It now answers with a plain "that is not a timestamp" so the page can recover and reload from the top. The referral code editor stated its length rule with a typographic dash that read as a minus sign on some devices, and now spells it out. The purchase history endpoint also documented the wrong default view: it always merges your purchases and your sales, which is what the dashboard shows.</description>+ </item><item><title>Shared agent links keep their preview card through a chain hiccup</title><link>https://three.ws/changelog</link>diff --git a/public/examples.json b/public/examples.jsonindex ddd90a2cc..7fc7e328e 100644--- a/public/examples.json+++ b/public/examples.json@@ -2,10 +2,10 @@"$comment": "GENERATED by scripts/mirror-examples-index.mjs from data/examples.json. Do not edit; run `npm run build:examples`.","generated_by": "scripts/build-examples-index.mjs","counts": {- "total": 43,+ "total": 45,"html_demos": 11,"projects": 10,- "packages": 22+ "packages": 24},"examples": [{@@ -226,6 +226,37 @@"readme": "concierge-sdk/examples/README.md","owner": "concierge-sdk"},+ {+ "id": "package:packages/kol-mcp",+ "kind": "package",+ "group": "Package examples",+ "title": "@three-ws/kol-mcp",+ "description": "Track one smart trader from any AI agent - a tracked KOL wallet's portfolio P&L (realized/unrealized, win rate, top holding) and its trades on a given mint. Read-only over the live public three.ws KOL API. No key, no signer, no payment.",+ "path": "packages/kol-mcp/examples",+ "files": [+ "list-tools.mjs",+ "wallet-card.mjs"+ ],+ "run": "node packages/kol-mcp/examples/list-tools.mjs",+ "runKind": "command",+ "readme": null,+ "owner": "packages/kol-mcp"+ },+ {+ "id": "package:packages/loom-mcp",+ "kind": "package",+ "group": "Package examples",+ "title": "@three-ws/loom-mcp",+ "description": "Loom - the three.ws community 3D-creation gallery from any AI agent. Browse the public feed of community-forged GLB creations, fetch one with its viewer URL, and submit your own. Public API, no key required.",+ "path": "packages/loom-mcp/examples",+ "files": [+ "list-tools.mjs"+ ],+ "run": "node packages/loom-mcp/examples/list-tools.mjs",+ "runKind": "command",+ "readme": null,+ "owner": "packages/loom-mcp"+ },{"id": "package:packages/marketplace-mcp","kind": "package",diff --git a/public/features.json b/public/features.jsonindex 28b5601fa..2460e3ca9 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-16T07:55:40.634Z",+ "generated_at": "2026-08-16T16:02:33.852Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",diff --git a/public/llms-full.txt b/public/llms-full.txtindex 309ea4d66..1ebbb5676 100644--- a/public/llms-full.txt+++ b/public/llms-full.txt@@ -3177,7 +3177,7 @@ The subsystem that turns a photo (or a generated reference image) into a rigged,URL: https://three.ws/docs/avatar-thumbnails-Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage at 100%, and how to run the backfill yourself.+Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage near 100%, and how to run the backfill yourself.### Docs · The additive wardrobediff --git a/public/llms.txt b/public/llms.txtindex 4af584317..2d85560a3 100644--- a/public/llms.txt+++ b/public/llms.txt@@ -563,7 +563,7 @@ Docs, tutorials, and reference.- [Docs · Avatar inspector](https://three.ws/docs/avatar-inspector): Every avatar you meet in a three.ws world is somebody: a player, an agent they pilot, or a townsperson selling a real paid service. Press I on anyone to see their reputation, wallet, and profile without leaving the world.- [Docs · The avatar pipeline](https://three.ws/docs/avatar-pipeline): End to end, how a text prompt or an image becomes a rigged, animated 3D avatar: generation, auto-rigging, skin weighting, and the universal animation system that drives the result on any humanoid skeleton.- [Docs · Selfie to avatar reconstruction](https://three.ws/docs/avatar-reconstruction): The subsystem that turns a photo (or a generated reference image) into a rigged, animation-ready 3D avatar. How it differs from the text-to-3D forge lane, what the quality gates check, and how failures are recovered.-- [Docs · Avatar thumbnails](https://three.ws/docs/avatar-thumbnails): Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage at 100%, and how to run the backfill yourself.+- [Docs · Avatar thumbnails](https://three.ws/docs/avatar-thumbnails): Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage near 100%, and how to run the backfill yourself.- [Docs · The additive wardrobe](https://three.ws/docs/avatar-wardrobe): Dress any avatar from the garment catalogue. The subtractive half recolours or hides layers a GLB already contains; the additive half fits new garments onto a body that never had them, and this documents both.- [Docs · Avatar Studio builder](https://three.ws/docs/character-studio): Avatar Studio is the browser-based avatar builder, an MIT-licensed fork that lives in character-studio/. Design a customised humanoid (body, hair, face, clothing, accessories) with point-and-click controls, then export it rigged as GLB or VRM.- [Docs · Concierge, an AI chat widget with a 3D face](https://three.ws/docs/concierge): A floating launcher that opens a chat panel where a rigged 3D avatar blinks, idles, and lip-syncs while it answers your visitors. Grounded in your live page content, with voice in and out, in one script tag.diff --git a/public/sitemap/index.html b/public/sitemap/index.htmlindex e8d68c0fe..4e1caf8f5 100644--- a/public/sitemap/index.html+++ b/public/sitemap/index.html@@ -3880,7 +3880,7 @@<a href="/docs/avatar-thumbnails"><span class="sm-title">Docs · Avatar thumbnails</span><span class="sm-path">/docs/avatar-thumbnails</span>- <span class="sm-desc">Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage at 100%, and how to run the backfill yourself.</span>+ <span class="sm-desc">Where an avatar's preview image comes from, the one rule every code path obeys (never publish a thumbnail URL whose object does not exist), the crons that keep coverage near 100%, and how to run the backfill yourself.</span></a></li><li>diff --git a/tests/api/activity-feed.test.js b/tests/api/activity-feed.test.jsindex 3b0952dfc..a750d3802 100644--- a/tests/api/activity-feed.test.js+++ b/tests/api/activity-feed.test.js@@ -229,6 +229,18 @@ describe('GET /api/users/me/feed?scope=all', () => {expect(body.next).toBe('2026-07-11T09:00:00Z');});+ it('rejects a cursor that is not a timestamp with a 400, before any query runs', async () => {+ const { res, body } = await call({ scope: 'all', before: "';--" });+ expect(res.statusCode).toBe(400);+ expect(body.error).toBe('validation_error');+ // The cursor is interpolated into a timestamptz comparison, so an+ // uncastable value used to abort the whole fan-out as a 500. Nothing may+ // reach the stores now.+ expect(listRecentCreations).not.toHaveBeenCalled();+ expect(listDioramas).not.toHaveBeenCalled();+ expect(listRecentRestyles).not.toHaveBeenCalled();+ });+it('returns a well-formed empty feed when nothing has happened, never 500s', async () => {sqlQueue.push([]); // avatarssqlQueue.push([]); // agents@@ -258,6 +270,17 @@ describe('GET /api/users/me/feed?scope=following', () => {sqlQueue.push(follows);}+ it('rejects a malformed cursor with a 400 on the personal feed too', async () => {+ authState.session = VIEWER;+ // A sentinel row proves the guard fired ahead of the following_count+ // query rather than after it: nothing may be consumed off the queue.+ sqlQueue.push([{ following_count: 3 }]);+ const { res, body } = await call({ scope: 'following', before: 'not-a-date' });+ expect(res.statusCode).toBe(400);+ expect(body.error).toBe('validation_error');+ expect(sqlQueue.length).toBe(1);+ });+it('emits model, world and restyle events from the people the viewer follows', async () => {authState.session = VIEWER;queueFollowingScope({diff --git a/tests/transient-rpc-provider-error.test.js b/tests/transient-rpc-provider-error.test.jsindex 84b689aff..f8b623692 100644--- a/tests/transient-rpc-provider-error.test.js+++ b/tests/transient-rpc-provider-error.test.js@@ -39,6 +39,33 @@ describe('isTransientRpcError: provider errors are upstream weather', () => {expect(isTransientRpcError('solana rpc provider error -16401')).toBe(true);});+ it('classifies the web3.js response-shape failure that 500ed treasury-topup again', () => {+ // Production 2026-08-13T10:32:04Z. classifyRpcBody had already passed the+ // body (it was well-formed JSON-RPC), but web3.js's superstruct check+ // rejected it: createRpcResult pins `id: string()` and+ // `jsonrpc: literal('2.0')`, so a lane echoing a numeric id or a+ // non-string error.message throws here instead of answering. The sweep+ // rethrew it as a hard 500 and took the engine self-heal down with it.+ const err = new Error(+ 'failed to get balance of account WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW: ' ++ 'StructError: Expected the value to satisfy a union of `type | type`, but received: [object Object]',+ );+ expect(isTransientRpcError(err)).toBe(true);+ });++ it('classifies the same failure wherever web3.js validates a node answer', () => {+ // Every superstruct call in web3.js validates something the NODE sent, so+ // the shape recurs on other reads. Same day, same cause, different caller:+ // [sdk-bridge] getBondingCurveState failed: StructError: …+ for (const m of [+ 'getBondingCurveState failed: StructError: Expected the value to satisfy a union of `type | type`, but received: [object Object]',+ 'StructError: Expected the value to satisfy a union of `type | type`, but received: [object Object]',+ 'Expected the value to satisfy a union of `type | type`, but received: [object Object]',+ ]) {+ expect(isTransientRpcError(new Error(m))).toBe(true);+ }+ });+it('still classifies the pre-existing transient shapes', () => {for (const m of ['Server responded with 429 Too Many Requests',