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-reference): correct the billing endpoints and log the changes for holders
nirholas82c07c3fcab9
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 531bd684d..276352b72 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -11,6 +11,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **Arming an Oracle agent for live trading no longer rounds your trade size up**: The arm page clamps the risk knobs on the server so a bad number can never reach the trading loop, and those clamps have a floor: the smallest trade the loop will place is 0.001 SOL. That floor was being applied in the wrong direction. Ask to arm a live agent with a per-trade size of zero, and instead of being told no, you were armed for real spending at 0.001 SOL a trade with a half-SOL daily ceiling you never asked for. The check meant to catch this looked at the number after the clamp had already raised it, so it could never fire. Arming live now refuses any per-trade size below the floor, and any daily cap smaller than a single trade, and tells you which number to fix; nothing is armed until you do. Clamping a too-large number back down to the ceiling is unchanged, and simulate runs keep the same forgiving behaviour as before. The arm page also shows the reason a save was rejected instead of one generic line, so an ownership problem no longer reads the same as a bad trade size, and a failed Telegram test now prints what Telegram actually said. (`/oracle/arm`) `[fix, security]`- **Avatars can move their lips again: the Audio2Face lane is back**: Every call that turns speech into facial animation had been failing with an upstream not-found error, so a talking avatar spoke with a frozen face and the one-shot say() path returned nothing usable. The hosted model id the lane pointed at had stopped resolving for our NVIDIA account. It now points at the hosted Audio2Face NIM that is actually live, verified end to end: a synthesized clip drives a 30 fps ARKit blendshape track whose jaw genuinely opens and closes with the words. The discovery helper that finds these model ids was missing the name NVIDIA publishes them under, which is why the outage looked like a configuration mystery; it now finds them. `[fix]`- **Docs pages stop opening with a wall of raw metadata, and the AWS pages say where the Marketplace listing actually stands**: Nine documentation pages are written as article drafts, so each one starts with a small block of publishing metadata: the title, where it is meant to run, its tags. That block is meant for the tooling, not for you, but the docs reader had no idea what it was and rendered it as an enormous heading at the very top of the article, above the actual writing. It is now recognised and hidden, on the page and in the Copy page text, so those articles begin where they should. Reading the same pages closely turned up claims that had drifted: several said three.ws was already live on AWS Marketplace and billing usage to your AWS invoice. The integration is built and deployed, but the listing itself has not been published yet and the pricing decision is a free subscription with no AWS metering, so the AWS pages now say exactly that and point at the page that tracks the status. The MCP article's vanity-address tool was also listed at a metered price of up to fifty cents; it is a flat five cents per grind, which is what the code has always charged. (`/docs/aws-marketplace`) `[docs, fix]`+- **Eight build tutorials now match what the platform actually does**: An audit of eight tutorials found instructions that could not work. The AI-brain tutorial described a model line-up that had been superseded: it never mentioned the Claude 5 family (Sonnet 5, Opus 5, Fable 5), which are live and selectable, and it recommended Sonnet 4.6 as the default. It also sent you to screens that do not exist, telling you to add API keys under a gear icon in My Agents and to change models, sampling knobs, and streaming under a Brain menu. Provider keys actually live in the AI Provider Keys panel on your account page, the model is a field on the agent's embed policy, and streaming has no off-switch. The promised usage tab with token charts and threshold emails did not exist either; the tutorial now documents the real per-agent usage read and points at the monthly quota and per-minute rate limit, which are the controls actually enforced before your money is spent. It also now explains that a visitor can never escalate your agent onto a paid model. The custom-GLB tutorial was worse for anyone following along: it linked a Studio address that no longer resolves, and four of its commands invoked gltf-transform subcommands that have never existed, so converting an FBX, renaming animation clips, and the full Mixamo walkthrough all failed at the first step. Those are replaced with the converter the platform itself uses and a clip-renaming script that was run against a real avatar to confirm it works. Its Draco flag was wrong, its upload path pointed at the wrong page, and it still warned that an avatar without an idle clip would stand frozen in a T-pose, which stopped being true when animation retargeting became universal. Finally, the page-events tutorial listed the wrong fallback order for emote animations. (`/tutorials/connect-ai-brain`) `[docs, fix]`- **Oracle stops answering "nothing is happening" when the database is the thing that is down**: Several Oracle reads shared a habit: if the database was unreachable for a few seconds, they answered normally with an empty result. The movers panel said nothing was moving, the stats hero said no coin had ever been scored and no agent was armed, a coin's conviction sparkline came back flat, and the machine-readable signal endpoint told autonomous agents there were no plays, which is exactly the cue for an agent to stand down. Every one of those answers was then cached at the edge for a minute or two, so a blip lasting seconds kept showing a dead market long after the database was back. Those endpoints now tell the difference between a connectivity failure and an ordinary query fault: the first is reported honestly as a temporary outage with a retry hint and is never cached, the second still degrades to the empty answer it always did. The social ingest got the sharper end of the same bug: it used to reply that a batch had been accepted while reporting zero mints written, a receipt for a write that never landed. It now fails loudly so the sender retries. Shared conviction cards behave too: one built during an outage is no longer pinned to a coin's link preview for 15 minutes. (`/oracle`) `[fix, improvement]`- **Plan checkout: a paid upgrade can only ever settle on real mainnet, and a late payment is no longer stranded**: Paying for a plan creates a quote, you send the funds, then the server checks the chain before it upgrades you. Three things in that path were wrong. The checkout side has always refused test-network quotes in production, because test-network dollars are free from a faucet, but the confirm side still let a caller name the test network itself, and it is the confirm side that decides which chain it looks at and which dollar it accepts. Both ends now read the same setting, so a production upgrade can only ever be settled by real funds on mainnet. Second, an Ethereum-side payment has to wait twelve blocks before it counts, which meant funds sent near the end of a session could land on-chain and then be refused for arriving late, with the money already gone; that lane now honors the same one-hour grace window the Solana lane has, so an on-chain payment is always claimable. Third, confirming an Ethereum payment could reach a Solana quote and mark it expired, and asking to buy a skill from a malformed agent id answered a generic server error instead of telling you what was wrong with the request. (`/pricing`) `[fix, security]`- **Seeding an agent from GitHub is locked to your own click, and a mistyped pick no longer costs you six hours**: Three fixes to the GitHub memory lane, the one that reads the profile, repositories, and READMEs you tick and distills them into what your agent knows about your work. First: writing or deleting those memories now requires the one-time token the site attaches to your own actions, so another site cannot make your browser re-seed or wipe an agent behind your back. Every neighbouring memory action already worked this way; this one did not. Second: seeding is allowed once every six hours per agent, and that window used to be spent by attempts that never read anything, so ticking nothing and pressing Seed, or picking a repository that had been renamed since the list loaded, locked you out for six hours over a correctable mistake. The window is now taken only once your selection checks out, immediately before anything is actually read. Third: when every model provider is busy at once, the seed used to fail with a bare internal error and a support reference; it now says plainly that nothing was read, that your existing memories are untouched, and roughly how long until you can try again. (`/docs/github-memory-seeding`) `[security, fix]`diff --git a/data/changelog.json b/data/changelog.jsonindex 8c56da694..b16e6dd47 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,16 @@{"$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-15",+ "title": "Eight build tutorials now match what the platform actually does",+ "summary": "An audit of eight tutorials found instructions that could not work. The AI-brain tutorial described a model line-up that had been superseded: it never mentioned the Claude 5 family (Sonnet 5, Opus 5, Fable 5), which are live and selectable, and it recommended Sonnet 4.6 as the default. It also sent you to screens that do not exist, telling you to add API keys under a gear icon in My Agents and to change models, sampling knobs, and streaming under a Brain menu. Provider keys actually live in the AI Provider Keys panel on your account page, the model is a field on the agent's embed policy, and streaming has no off-switch. The promised usage tab with token charts and threshold emails did not exist either; the tutorial now documents the real per-agent usage read and points at the monthly quota and per-minute rate limit, which are the controls actually enforced before your money is spent. It also now explains that a visitor can never escalate your agent onto a paid model. The custom-GLB tutorial was worse for anyone following along: it linked a Studio address that no longer resolves, and four of its commands invoked gltf-transform subcommands that have never existed, so converting an FBX, renaming animation clips, and the full Mixamo walkthrough all failed at the first step. Those are replaced with the converter the platform itself uses and a clip-renaming script that was run against a real avatar to confirm it works. Its Draco flag was wrong, its upload path pointed at the wrong page, and it still warned that an avatar without an idle clip would stand frozen in a T-pose, which stopped being true when animation retargeting became universal. Finally, the page-events tutorial listed the wrong fallback order for emote animations.",+ "tags": [+ "docs",+ "fix"+ ],+ "link": "/tutorials/connect-ai-brain"+ },{"date": "2026-08-15","title": "The Agent Exchange stops offering a purchase its wallet cannot pay for",diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 6fba90919..fdf648a34 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -5745,6 +5745,117 @@ verbatim and re-served on every read. A violation is a `422`---+## IPFS Pinning API++Puts bytes on IPFS and reports whether they are still held there. Both actions+live in `api/pinning/[action].js`.++The pinning credential is server-held and never reaches the browser, which is+the whole reason this endpoint exists: the Avatar Studio mint flow+(`character-studio/src/library/mint-utils.js`) posts an avatar here instead of+talking to a pinning provider directly. Providers are tried in order, Pinata+first and web3.storage second, matching `api/_lib/ipfs-pin.js`.++### Pin a file++```+POST /api/pinning/pin+```++Authenticated: a session cookie or a bearer token. Rate limited to 30 pins per+hour per user.++| Field | Required | Meaning |+|---|---|---|+| `sourceUrl` | yes | Either a `data:` URL carrying the bytes inline, or an `https://` URL on the platform's own storage domain. Any other host is a `400`. |+| `kind` | yes | `glb` or `manifest`. Anything else is a `400`. |+| `filename` | no | The name filed at the provider. Reduced to `A-Za-z0-9._-` and capped at 128 characters; a value that survives none of that, or is not a string, falls back to `avatar.glb` or `manifest.json` by `kind`. Omitted on a storage-URL pin, the object's own key is used. |++Three size ceilings apply, and they are different numbers because they bound+different things:++| Ceiling | Value | Applies to |+|---|---|---|+| Request body | 8 MB | The whole JSON document, enforced by the server for every endpoint |+| Inline payload | 5 MB | The decoded bytes of a `data:` URL. Base64 inflates raw bytes by 4/3, so 5 MB of payload is about 6.7 MB of body |+| Storage source | 50 MB | The object fetched from an `https://` source URL |++Anything larger than the inline ceiling should be uploaded to storage first and+pinned by URL, which is what the 50 MB lane is for.++```bash+curl -X POST https://three.ws/api/pinning/pin \+ -H "Authorization: Bearer $THREE_WS_TOKEN" \+ -H "Content-Type: application/json" \+ -d '{"sourceUrl":"data:application/json;base64,eyJuYW1lIjoiS25pZ2h0In0=","kind":"manifest","filename":"knight.json"}'+```++```json+{+ "ok": true,+ "cid": "QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "gatewayUrl": "https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "gatewayUrls": [+ "https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "https://dweb.link/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "https://w3s.link/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "https://gateway.pinata.cloud/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"+ ],+ "provider": "pinata"+}+```++`gatewayUrl` is the single canonical read URL; `gatewayUrls` is every gateway+worth trying. A freshly pinned CID takes minutes to propagate across the public+network, so the provider's own gateway (last in the list) is the one guaranteed+to serve it immediately.++**Errors:** `400` (`validation_error`: missing `sourceUrl`, bad `kind`,+malformed `data:` URL, or a source host the platform does not own), `401`+(`unauthorized`), `413` (`payload_too_large`, naming the ceiling that was+crossed), `415` (body was not JSON), `429` (`rate_limited`), `502`+(`fetch_failed`: the source URL was unreachable or redirected), `503`+(`pinning_unconfigured`).++A request that is malformed always answers `4xx`, including on a deployment+with no provider configured: the `503` is reached only once the request itself+is known to be valid.++### Check whether a CID is still pinned++```+GET /api/pinning/status?cid=<cid>+```++Public, unauthenticated, rate limited by IP. `cid` must be 16 to 128+alphanumeric characters.++```bash+curl "https://three.ws/api/pinning/status?cid=QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"+```++```json+{+ "cid": "QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o",+ "pinned": true,+ "provider": "pinata",+ "unreachableProviders": [],+ "gatewayUrls": ["https://ipfs.io/ipfs/QmYazpLPRXtuBsCQk64LpXohMxSGJa3RoQTx9fckJgPY9o"]+}+```++`pinned: false` means every provider that answered said it is not holding the+CID. It never means "we could not tell": a provider that failed to answer is+named in `unreachableProviders` instead, and if none of them answered the+response is a `503` (`pinning_check_failed`) rather than a `200`. Treat+`unreachableProviders` as non-empty before acting on `pinned: false`, because a+partial answer is still a partial answer.++**Errors:** `400` (`validation_error`: missing or out-of-bounds `cid`), `429`+(`rate_limited`), `503` (`pinning_unconfigured` or `pinning_check_failed`).++---+## PaginationPaginated list endpoints use `limit`/`offset` query parameters unless noted otherwise (each endpoint's own parameter table is authoritative; some small per-user lists, like `/api/agents` and `/api/widgets`, return everything with no pagination).diff --git a/packages/billing-mcp/README.md b/packages/billing-mcp/README.mdindex ae602103d..b93e32442 100644--- a/packages/billing-mcp/README.md+++ b/packages/billing-mcp/README.md@@ -91,6 +91,79 @@ Everything reads live state — usage, invoices, and earnings all move between c**`get_fee_info`** — none.+## Examples++```jsonc+// get_billing_summary — plan ceilings and live usage against them+> {}+{+ "ok": true,+ "plan": "free",+ "quotas": {+ "max_avatars": 10,+ "max_bytes_per_avatar": 26214400,+ "max_total_bytes": 262144000,+ "mcp_calls_per_day": 1000+ },+ "usage": {+ "avatar_count": 1,+ "total_bytes": 1234540,+ "agent_count": 1,+ "mcp_calls_24h": 0,+ "llm_calls_month": 0+ },+ "remaining": { "avatars": 9, "total_bytes": 260909460, "mcp_calls_today": 1000 }+}+```++```jsonc+// query_usage — the period statement (defaults to the current UTC month)+> {}+{+ "ok": true,+ "period_label": "2026-08",+ "period": { "from": "2026-08-01T00:00:00.000Z", "to": "2026-09-01T00:00:00.000Z" },+ "line_item_count": 0,+ "line_items": [],+ "totals": {+ "charge_count": 0,+ "gross_atomics": "0", "fee_atomics": "0", "net_atomics": "0",+ "gross_usd": "0.00", "fee_usd": "0.00", "net_usd": "0.00",+ "currency": "USDC"+ },+ "reconciliation": { "total": 0, "reconciled": 0, "unreconciled": 0, "all_reconciled": true }+}+```++```jsonc+// export_billing_history — the same statement as a ready-to-save CSV+> { "preview_rows": 5 }+{+ "ok": true,+ "filename": "three-ws-invoice-2026-08.csv",+ "content_type": "text/csv; charset=utf-8",+ "row_count": 1,+ "preview": [ { "action": "TOTAL", "count": "0", "gross_usd": "0.00", "fee_usd": "0.00" } ],+ "csv": "action,label,count,units,gross_usd,fee_usd,discount_bps\nTOTAL,,0,,0.00,0.00,\n"+}+```++```jsonc+// get_fee_info — the one read that needs no session+> {}+{ "ok": true, "fee_bps": 250, "fee_percent": "2.5" }+```++A quiet account reads like the statements above: zeroed totals with+`all_reconciled: true`. That is the healthy empty state, not a failed call. Every+read without `THREE_WS_SESSION` (except `get_fee_info`) fails loudly instead of+returning empty data:++```jsonc+{ "ok": false, "error": "no_session", "status": 401,+ "message": "/api/billing/summary is account-scoped and needs your three.ws session. …" }+```+## What you owe vs. what you earnedTwo sides of the same account, two tools:diff --git a/public/changelog.xml b/public/changelog.xmlindex 3ed342bc8..a055565ab 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -46,6 +46,14 @@<category>docs</category><description>Nine documentation pages are written as article drafts, so each one starts with a small block of publishing metadata: the title, where it is meant to run, its tags. That block is meant for the tooling, not for you, but the docs reader had no idea what it was and rendered it as an enormous heading at the very top of the article, above the actual writing. It is now recognised and hidden, on the page and in the Copy page text, so those articles begin where they should. Reading the same pages closely turned up claims that had drifted: several said three.ws was already live on AWS Marketplace and billing usage to your AWS invoice. The integration is built and deployed, but the listing itself has not been published yet and the pricing decision is a free subscription with no AWS metering, so the AWS pages now say exactly that and point at the page that tracks the status. The MCP article's vanity-address tool was also listed at a metered price of up to fifty cents; it is a flat five cents per grind, which is what the code has always charged.</description></item>+ <item>+ <title>Eight build tutorials now match what the platform actually does</title>+ <link>https://three.ws/tutorials/connect-ai-brain</link>+ <guid isPermaLink="false">2026-08-15:Eight build tutorials now match what the platform actually does</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>docs</category>+ <description>An audit of eight tutorials found instructions that could not work. The AI-brain tutorial described a model line-up that had been superseded: it never mentioned the Claude 5 family (Sonnet 5, Opus 5, Fable 5), which are live and selectable, and it recommended Sonnet 4.6 as the default. It also sent you to screens that do not exist, telling you to add API keys under a gear icon in My Agents and to change models, sampling knobs, and streaming under a Brain menu. Provider keys actually live in the AI Provider Keys panel on your account page, the model is a field on the agent's embed policy, and streaming has no off-switch. The promised usage tab with token charts and threshold emails did not exist either; the tutorial now documents the real per-agent usage read and points at the monthly quota and per-minute rate limit, which are the controls actually enforced before your money is spent. It also now explains that a visitor can never escalate your agent onto a paid model. The custom-GLB tutorial was worse for anyone following along: it linked a Studio address that no longer resolves, and four of its commands invoked gltf-transform subcommands that have never existed, so converting an FBX, renaming animation clips, and the full Mixamo walkthrough all failed at the first step. Those are replaced with the converter the platform itself uses and a clip-renaming script that was run against a real avatar to confirm it works. Its Draco flag was wrong, its upload path pointed at the wrong page, and it still warned that an avatar without an idle clip would stand frozen in a T-pose, which stopped being true when animation retargeting became universal. Finally, the page-events tutorial listed the wrong fallback order for emote animations.</description>+ </item><item><title>Oracle stops answering "nothing is happening" when the database is the thing that is down</title><link>https://three.ws/oracle</link>