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: rewrite the API reference, tutorial, and handler prose without banned dashes
nirholas321f6ea7cbd1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a67b48639..d686eb1e8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -10,6 +10,7 @@ Public history for [three.ws](https://three.ws), newest first. New pages come fr- **A retried agent spend can no longer hand its transaction to somebody else, and an unsupported chain says so instead of blaming the network**: When an agent redeems a permission you granted it, it can send a retry key so a request whose answer it never saw is not paid for twice. That key was filed under the permission alone rather than under the agent that used it, and it was read before the check that the caller owns the permission at all, so a different agent replaying the same permission and key was handed the original transaction hash and receipt instead of being turned away. The key is now filed per caller: a retry only ever returns your own result, and anyone else gets the same not-found answer they should always have got. Two more fixes in the same endpoint. A permission recorded on a chain three.ws has no delegation contract on could never settle, but the attempt came back as a network error, which reads as a temporary outage worth retrying rather than the permanent chain mismatch it is; it is now named plainly and refused before it consumes any of the permission's spending allowance. And the relayer kept its own private one-address-per-chain list of blockchain endpoints, separate from the failover chain the rest of the platform uses, so it would have refused to work on the next supported chain even where the shared endpoints reach it fine. It now uses the shared list, with any operator override still taking priority. The permissions guide gained a section on how the retry key behaves and how long it lasts. (`/docs/permissions`) `[security, fix]`- **A shared link to a docs page now opens that page instead of stranding you**: Every cross-reference inside a docs page turns into a link like /docs/agent-wallets#financial-controls. Following one worked, but the URL you copied afterwards did not: on a fresh load the viewer only recognised the second half if that doc happened to be listed in the sidebar, and silently left you on the page you arrived from otherwise. Links to Financial controls, the x402 payment tutorial, and the wallet access and proof-of-custody chapters all failed that way. The viewer now asks the server whether the doc exists before giving up, so those links land where they say they will, and the browser tab takes the destination's name. Separately, /docs/3d-api was serving the 3D API landing page rather than the reference doc that the API's own discovery response, the OpenAPI license link, and the docs sidebar all point at; it now serves the reference doc, and the landing page keeps its home at /3d. (`/docs/agent-wallets`) `[fix, docs]`- **A silent outage in the agent reasoning ledger now reports itself**: Every agent decision is committed to a hash chain, and that chain head is written to Solana on a schedule so anyone can check the history was never edited. The wallet that pays for those on-chain writes ran empty, and the scheduled job could not tell that apart from the harmless case where no signing key is set up at all: it answered a healthy 200 every ten minutes while re-sending the same doomed transaction for twelve agents in a row, and not one head reached the chain. A rejected write is now reported as a rejected write, the rest of the run stops instead of repeating a failure that cannot succeed, and it raises an alert so the wallet gets refilled. Verifying a ledger already worked without the on-chain leg and still does: the recomputed hash chain is the tamper proof, the on-chain write is the independent timestamp on top of it. Separately, the once-a-minute economy heartbeat now refuses to drive production from a machine that is not production, so a developer running it locally can no longer fire thirty-six live money engines at the real site. (`/docs/reasoning-ledger`) `[fix, infra]`+- **A vault download rate-limit hit now tells you when to retry, and a browse outage stops reading as an empty listing**: Two fixes on the BNB vault endpoints. Downloading a purchased vault file is deliberately rate limited, but when you hit that limit the reply came back without a retry-after time and without the limiter's own reason, so a client had no idea how long to wait, and a limiter outage (which deliberately refuses requests rather than letting them through unchecked) was indistinguishable from you genuinely spending your own quota. Both now come back with the refusal, the same way every other vault endpoint already answered. Separately, when browsing the vault, a listing whose stored file details could not be looked up was always reported as "listed on-chain, details missing". That is the honest answer when the storage network really has nothing for it, but the same answer was given when the lookup itself was down, quietly turning an outage into what looks like an incomplete listing. A genuine miss still shows as a listing without details; an outage now says the storage lookup is unavailable. Both endpoints also gained full test coverage, including proof that a download link issued to one buyer cannot fetch another buyer's file. (`/vault`) `[fix]`- **Agent .sol name lookups work again, and the avatar manifest schema now answers at its own address**: The avatar-agent MCP server resolves .eth and .sol names to wallet addresses. Its .sol side went through a hosted name-lookup service that has since been retired: every request came back as "not found", which reads exactly like an unregistered domain, so a working name and a nonexistent one were indistinguishable. Solana names are now read straight from the chain, from the same name-service accounts the three.ws backend already reads, so the lookup depends on nothing but a Solana RPC. Two things were fixed alongside it. The per-lookup time budget was under five seconds, which a cold Ethereum lookup routinely exceeds, so real names were being reported as timeouts; it is now fifteen seconds and adjustable. And a lookup that genuinely fails now says why instead of quietly reporting "not found". Separately, the avatar manifest schema names https://three.ws/schema/avatar.v1.json as its own identifier, but nothing was served there, so any validator that followed the identifier got a 404. The schema is now published at that address, with a test that keeps the served copy identical to the one shipped in the package. `[fix, sdk]`- **Agent Screen is usable on a phone, and reads correctly to a screen reader**: Watching an agent work on a narrow screen was close to impossible. The row of viewer controls along the top (fit, screenshot, picture-in-picture, fullscreen, ambient, zen, and the link back to the agent) ran off the edge of the page with no way to reach them, the agent name and its live badge painted over the buttons underneath, and the two panels that open by default covered the live screen and the avatar cam completely: the whole point of the page, hidden. The control row now scrolls sideways so every control stays reachable at any width, the name keeps its space, and on a phone the page opens on a bare stage with the panels one tap away. Three fixes for anyone using a keyboard or a screen reader landed with it: the page now has a real heading and a main region for the skip link to jump to, the hidden Skip to content link stopped rendering as visible text at the top of the page, and every text field on the page gained a proper label. Finally, if the agent list fails to load for any reason other than being signed out, the page says what went wrong and offers a retry instead of telling a signed-in owner to go sign in. (`/agent-screen`) `[fix, improvement]`- **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]`diff --git a/api/trades/feed.js b/api/trades/feed.jsindex 8421319fa..2b5278e43 100644--- a/api/trades/feed.js+++ b/api/trades/feed.js@@ -10,17 +10,25 @@* Each item carries:* id, mint, symbol, name, image_uri* agent_id, agent_name, agent_image — trader identity- * entry_sol, exit_sol, realized_pnl_sol, realized_pnl_pct+ * entry_sol, exit_sol, realized_pnl_sol, realized_pnl_pct, multiple* hold_seconds, exit_reason, buy_sig, sell_sig* oracle_score, oracle_tier, oracle_category — conviction context if scored* copier_count — how many subscriptions fire on this agent* closed_at*+ * `realized_pnl_sol`, `realized_pnl_pct`, and `multiple` are POSITION-level and+ * cumulative across every sell leg. `entry_sol` and `exit_sol` are the position's+ * remaining cost basis and its final leg's proceeds: on a position that took+ * initials first (workers/agent-sniper/executor.js rewrites the basis and books+ * only the closing leg's proceeds), those two do not reconstruct the return, so+ * `multiple` is derived from the cumulative pct rather than exit/entry.+ ** Public, IP rate-limited, 30-second CDN cache.*/-import { cors, json, method, wrap, rateLimited } from '../_lib/http.js';+import { cors, json, method, wrap, rateLimited, error } from '../_lib/http.js';import { limits, clientIp } from '../_lib/rate-limit.js';+import { isoTimestamp } from '../_lib/validate.js';import { sql } from '../_lib/db.js';const NETWORKS = new Set(['mainnet', 'devnet']);@@ -48,10 +56,30 @@ export default wrap(async (req, res) => {const network = NETWORKS.has(p.get('network')) ? p.get('network') : 'mainnet';const window = WINDOWS.has(p.get('window')) ? p.get('window') : '24h';const limit = Math.min(80, Math.max(1, Number(p.get('limit')) || 40));- const minPnl = Math.max(0, Number(p.get('min_pnl_pct')) || 10); // % profit threshold- const cursor = p.get('cursor') || null; // ISO timestamp for pagination++ // `Number(x) || 10` silently rewrote an explicit min_pnl_pct=0 to 10, since 0 is+ // falsy. The oracle coin drawer asks for 0 to show every trade on a coin, so it+ // only ever saw the winners above 10%. Parse the number first, then default.+ const pnlRaw = p.get('min_pnl_pct');+ const pnlNum = pnlRaw == null || pnlRaw.trim() === '' ? NaN : Number(pnlRaw);+ const minPnl = Number.isFinite(pnlNum) ? Math.max(0, pnlNum) : 10; // % profit threshold++ // A malformed cursor is a client fault: validate it here rather than letting the+ // `::timestamptz` cast reject inside the query and surface as an opaque 5xx.+ const cursorRaw = p.get('cursor');+ const cursor = cursorRaw ? isoTimestamp(cursorRaw) : null; // ISO timestamp for pagination+ if (cursorRaw && !cursor) {+ return error(res, 400, 'validation_error', 'cursor must be an ISO 8601 timestamp');+ }++ // Filter to one coin (oracle drawer). Silently dropping an unparseable mint would+ // answer a coin-scoped request with the whole platform feed, which reads as+ // "these are that coin's trades". Say it is invalid instead.const mintRaw = (p.get('mint') || '').trim();- const mintFilter = MINT_RE.test(mintRaw) ? mintRaw : null; // filter to one coin (oracle drawer)+ if (mintRaw && !MINT_RE.test(mintRaw)) {+ return error(res, 400, 'validation_error', 'mint must be a valid base58 mint address');+ }+ const mintFilter = mintRaw || null;const interval = WINDOW_INTERVAL[window] || null;@@ -60,7 +88,7 @@ export default wrap(async (req, res) => {? sql`and pos.closed_at > now() - ${interval}::interval`: sql``;- const cursorCond = cursor && /^\d{4}-\d{2}-\d{2}T/.test(cursor)+ const cursorCond = cursor? sql`and pos.closed_at < ${cursor}::timestamptz`: sql``;@@ -107,7 +135,7 @@ export default wrap(async (req, res) => {) as copier_countfrom agent_sniper_positions pos- join agent_identities ai on ai.id = pos.agent_id+ join agent_identities ai on ai.id = pos.agent_id and ai.deleted_at is null-- left join oracle conviction so coins that weren't scored still appearleft join oracle_conviction oc@@ -116,21 +144,27 @@ export default wrap(async (req, res) => {where pos.network = ${network}and pos.status = 'closed'+ and pos.closed_at is not nulland pos.realized_pnl_pct >= ${minPnl}${windowCond}${cursorCond}${mintCond}- order by pos.closed_at desc+ -- id breaks ties so two exits sharing a closed_at can't reorder between+ -- pages; closed_at alone left the cursor walking a nondeterministic order.+ order by pos.closed_at desc, pos.id desclimit ${limit}- `.catch(() => []);+ `;const items = rows.map((r) => {const entrySol = r.entry_quote_lamports != null ? Number(r.entry_quote_lamports) / LAMPORTS : null;const exitSol = r.exit_quote_lamports != null ? Number(r.exit_quote_lamports) / LAMPORTS : null;const pnlSol = r.realized_pnl_lamports != null ? Number(r.realized_pnl_lamports) / LAMPORTS : null;const pnlPct = r.realized_pnl_pct != null ? Number(r.realized_pnl_pct) : null;- const multiple = entrySol && exitSol && entrySol > 0 ? exitSol / entrySol : null;+ // exit/entry describes only the final sell leg once a position took initials,+ // so it rendered "0.56× +88%" side by side on the feed. The cumulative pct is+ // the position's whole return, and 1 + pct/100 is that return as a multiple.+ const multiple = pnlPct != null && Number.isFinite(pnlPct) ? 1 + pnlPct / 100 : null;return {id: r.id,diff --git a/api/v1/token/security.js b/api/v1/token/security.jsindex 50dbd6c14..dea5c0c7c 100644--- a/api/v1/token/security.js+++ b/api/v1/token/security.js@@ -195,7 +195,7 @@ export default defineEndpoint({// on-chain facts here (SPL mint/freeze authority, getTokenLargestAccounts) are// Solana concepts with no EVM equivalent in this reader.if (isValidEvmAddress(address)) {- fail(400, 'unsupported_chain', 'this endpoint checks Solana tokens only (for now) — pass a base58 Solana mint address, not an EVM 0x… address');+ fail(400, 'unsupported_chain', 'this endpoint checks Solana tokens only (for now). Pass a base58 Solana mint address, not an EVM 0x address');}if (!isValidSolanaAddress(address)) {fail(400, 'validation_error', '"address" must be a base58 Solana mint address');@@ -233,8 +233,8 @@ export default defineEndpoint({// Nothing resolved: distinguish "every source failed" (transient — retry)// from "sources answered but this isn't a resolvable token" (client input).if (allFailed) {- fail(503, 'sources_unavailable', 'token security sources are unavailable right now — retry shortly');+ fail(503, 'sources_unavailable', 'token security sources are unavailable right now, retry shortly');}- fail(404, 'not_found', 'no on-chain mint or market could be resolved for this address — check the mint');+ fail(404, 'not_found', 'no on-chain mint or market could be resolved for this address, check the mint');},});diff --git a/api/v1/x/[...slug].js b/api/v1/x/[...slug].jsindex bbf529ff7..489c6e0e2 100644--- a/api/v1/x/[...slug].js+++ b/api/v1/x/[...slug].js@@ -166,10 +166,10 @@ export default wrap(async (req, res) => {data: {base_url: '/api/v1/x',billing: {- byok: 'send your own upstream key via the provider\'s BYOK header — pass-through, no markup',- plan: 'authenticate with a three.ws API key / OAuth token — uses the platform key',- free: 'send no credentials on an endpoint marked "free" — a per-IP quota (see each endpoint\'s free.perMin/free.perDay) serves real data with zero setup; X-Free-Tier: 1 + RateLimit-* headers on every response',- x402: 'send no credentials — pay per call in USDC (HTTP 402), or quota-exhausted free-tier calls fall through here',+ byok: 'send your own upstream key via the provider\'s BYOK header: pass-through, no markup',+ plan: 'authenticate with a three.ws API key / OAuth token: uses the platform key',+ free: 'send no credentials on an endpoint marked "free": a per-IP quota (see each endpoint\'s free.perMin/free.perDay) serves real data with zero setup; X-Free-Tier: 1 + RateLimit-* headers on every response',+ x402: 'send no credentials: pay per call in USDC (HTTP 402), or quota-exhausted free-tier calls fall through here',},providers: providerCatalog(),},@@ -181,7 +181,7 @@ export default wrap(async (req, res) => {res,404,'not_found',- 'use /api/v1/x/<provider>/<endpoint> — GET /api/v1/x lists every available pair',+ 'use /api/v1/x/<provider>/<endpoint>. GET /api/v1/x lists every available pair',);}@@ -191,7 +191,7 @@ export default wrap(async (req, res) => {res,404,'unknown_endpoint',- `no aggregated endpoint "${slug[0]}/${slug[1]}" — GET /api/v1/x lists what's available`,+ `no aggregated endpoint "${slug[0]}/${slug[1]}". GET /api/v1/x lists what's available`,);}const { provider, endpoint } = ref;diff --git a/api/vaults/[id].js b/api/vaults/[id].jsindex 499d75ec4..20e006992 100644--- a/api/vaults/[id].js+++ b/api/vaults/[id].js@@ -5,7 +5,7 @@// The GET is role-aware: anyone can see the public picture (the agent, its verified// reputation, live NAV + P&L, terms, backer roster); the signed-in caller also sees// their own position; the owner additionally sees accrued fees and the funding-// roster detail. NAV is re-derived from chain on every read — never a stale cache.+// roster detail. NAV is re-derived from chain on every read, never a stale cache.import { cors, json, method, error, readJson, wrap } from '../_lib/http.js';import { authWrite, resolveUserId, loadAgent, traderBadge } from '../_lib/vault-auth.js';@@ -129,7 +129,7 @@ async function handlePatch(req, res, id) {}if (action === 'close') {const next = await setVaultStatus(vault.id, 'closing', { haltReason: 'owner_close' });- await recordVaultEvent({ vaultId: vault.id, type: 'close', userId: who.userId, reason: 'owner closing vault — backers may redeem' });+ await recordVaultEvent({ vaultId: vault.id, type: 'close', userId: who.userId, reason: 'owner closing vault; backers may redeem' });return json(res, 200, { data: { vault: next } }, { 'cache-control': 'no-store' });}if (action === 'terms') {diff --git a/data/changelog.json b/data/changelog.jsonindex 59c772b0a..a9f91b874 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,24 @@{"$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": "Looking up an on-chain agent by its CAIP reference works again",+ "summary": "The public resolver that turns an ERC-8004 agent reference into its owner, token URI and verified agent card could not be reached at all. An agent reference ends in a slash before its token id, and the documentation told callers to percent-encode the whole reference, which turns that slash into %2F. The API refuses any address segment holding an encoded separator, because that is the same trick used to escape a path and reach files that were never meant to be served, so every correctly-formed lookup was turned away as an unknown address before it ever reached the resolver. The verification badge you can embed on your own site built its request in exactly that shape, so it never showed a result either. The resolver now accepts the reference with its slash as a normal part of the address, the badge asks for it that way, and the documentation shows the form that works. The protection against encoded separators is untouched. New tests resolve the address through the same routing the live site uses, so this cannot quietly break again.",+ "tags": [+ "fix"+ ],+ "link": "/docs/api-reference"+ },+ {+ "date": "2026-08-15",+ "title": "A vault download rate-limit hit now tells you when to retry, and a browse outage stops reading as an empty listing",+ "summary": "Two fixes on the BNB vault endpoints. Downloading a purchased vault file is deliberately rate limited, but when you hit that limit the reply came back without a retry-after time and without the limiter's own reason, so a client had no idea how long to wait, and a limiter outage (which deliberately refuses requests rather than letting them through unchecked) was indistinguishable from you genuinely spending your own quota. Both now come back with the refusal, the same way every other vault endpoint already answered. Separately, when browsing the vault, a listing whose stored file details could not be looked up was always reported as \"listed on-chain, details missing\". That is the honest answer when the storage network really has nothing for it, but the same answer was given when the lookup itself was down, quietly turning an outage into what looks like an incomplete listing. A genuine miss still shows as a listing without details; an outage now says the storage lookup is unavailable. Both endpoints also gained full test coverage, including proof that a download link issued to one buyer cannot fetch another buyer's file.",+ "tags": [+ "fix"+ ],+ "link": "/vault"+ },{"date": "2026-08-15","title": "A retried agent spend can no longer hand its transaction to somebody else, and an unsupported chain says so instead of blaming the network",diff --git a/docs/api-reference.md b/docs/api-reference.mdindex fdf648a34..83215f4cb 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -3306,12 +3306,14 @@ breakdown, and a 30-day daily series. Backed byGET /api/v1/agents/:caip```-Public, gateway-cached resolver for an ERC-8004 agent. `:caip` is a URL-encoded CAIP-style ref — `eip155:<chainId>:<registryAddress>/<tokenId>` — so consumers (the badge web component, indexers, third-party sites) don't have to do RPC + IPFS + sha256 verification themselves. No auth required.+Public, gateway-cached resolver for an ERC-8004 agent. `:caip` is a CAIP-style ref (`eip155:<chainId>:<registryAddress>/<tokenId>`), so consumers (the badge web component, indexers, third-party sites) don't have to do RPC + IPFS + sha256 verification themselves. No auth required.++Pass the ref with its `/` as a real path separator. Percent-encoding the colons is fine; percent-encoding the slash is not, because the API dispatcher rejects any path segment that decodes to contain a separator (that is the guard which stops `%2f..%2f..` traversal), so a `%2F` ref 404s before it reaches the resolver.**Example**```-GET /api/v1/agents/eip155%3A8453%3A0x8004A169...%2F1+GET /api/v1/agents/eip155:8453:0x8004A169.../1```**Response:** `{ ref, chainId, agentId, registry, owner, tokenURI, card, verified: { modelSha256, cardSchema }, fetchedAt }` — `card` is the resolved agent card JSON.diff --git a/docs/ops/gcp-production.md b/docs/ops/gcp-production.mdindex 0dc40549d..75a36cff4 100644--- a/docs/ops/gcp-production.md+++ b/docs/ops/gcp-production.md@@ -653,6 +653,40 @@ proxy + Memorystore + connector. The `upstash-redis-rest-token` secret and theidentical site and bypasses the LB — useful for isolating LB vs serviceissues.+### Client geo header (analytics country column)++`api/_lib/client-geo.js` resolves a visitor's country from an edge geo header+and never from the raw IP. On Vercel that header was `x-vercel-ip-country`, set+by the edge for free. **The GCLB sets no geo header by default**, so after the+2026-07-07 migration `widget_views.country` and `widget_chat_threads.country`+went null for every row (verified: 49/49 populated in May, 0/27 in August), and+the `top_countries` panel on `/api/widgets/:id/stats` renders empty for every+widget.++The reader now prefers `x-client-geo-location`, then `x-client-region`. Populate+one on the backend service to restore capture (owner-gated: this is a+production LB change, not a Cloud Run config update):++```bash+gcloud compute backend-services update three-ws-backend --global \+ --project aerial-vehicle-466722-p5 \+ --custom-request-header='X-Client-Region:{client_region}'+```++`{client_region}` is the GCLB variable for the ISO 3166-1 alpha-2 code of the+client. Confirm with `gcloud compute backend-services describe three-ws-backend+--global --format='value(customRequestHeaders)'`, then check capture:++```sql+select count(*) filter (where country is not null), count(*)+from widget_views where created_at > now() - interval '1 day';+```++Until that header exists the code degrades to null rather than guessing, which+is the intended behavior. Note the LB does not strip an inbound copy of these+headers, so a client can forge one; `clientCountry` validates every value down+to two ASCII letters so the worst case is a visitor mislabeling its own row.+---## Verifying after any changediff --git a/docs/tutorials/connect-ai-brain.md b/docs/tutorials/connect-ai-brain.mdindex 19b1a72aa..3102cb282 100644--- a/docs/tutorials/connect-ai-brain.md+++ b/docs/tutorials/connect-ai-brain.md@@ -268,7 +268,19 @@ const usage = await (await fetch(`/api/agents/${agentId}/usage`, { credentials:Note what this is and isn't: it counts **calls**, not tokens, and it is the same counter the proxy enforces `monthly_quota` against. It is the number to watch for "is this agent about to hit its cap", not for a dollar figure.-**The account read.** `GET /api/usage/summary` returns your account-level numbers (plan quotas, avatar count and bytes, MCP tool calls in the last 24h, total events in the last 30 days).+**The account read.** `GET /api/usage/summary` returns your account-level numbers: plan quotas, avatar count and bytes, MCP tool calls in the last 24h, total events in the last 30 days, plus an `llm` block for the current calendar month:++```js+const summary = await (await fetch('/api/usage/summary', { credentials: 'include' })).json();+// summary.llm → {+// calls_month, // LLM calls billed to your account this month+// tokens_month, // input + output tokens across those calls+// cost_micro_usd_month, // server-priced spend, in millionths of a dollar+// by_model: [{ model, calls, tokens, cost_micro_usd }] // busiest models first+// }+```++Session cookies work, and so does an API key with the `profile` scope (`Authorization: Bearer sk_live_...`). This is the account-wide view; use `/api/agents/:id/usage` above when you need one agent's numbers. The dashboard renders it under **Settings → LLM usage**.**Cost.** The platform prices every call server-side through `api/_lib/llm-pricing.js` and records it, so the spend cap in `checkUserLlmSpendCap` is enforced on real numbers. What there is *not* today is a self-serve token-and-dollar breakdown chart per conversation, nor threshold email alerts. Budget with `monthly_quota` and `rate_limit_per_min` on the embed policy (Step 8), those are hard, enforced-before-spend limits, which is a stronger control than an after-the-fact alert.diff --git a/public/changelog.json b/public/changelog.jsonindex af8072e81..e1255bb62 100644--- a/public/changelog.json+++ b/public/changelog.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T07:54:51.474Z",+ "generated_at": "2026-08-15T15:04:09.742Z","generated_by": "scripts/build-page-index.mjs from data/pages.json + data/changelog.json","site": {"name": "three.ws",@@ -49,6 +49,16 @@"infra"]},+ {+ "date": "2026-08-15",+ "type": "update",+ "title": "A vault download rate-limit hit now tells you when to retry, and a browse outage stops reading as an empty listing",+ "summary": "Two fixes on the BNB vault endpoints. Downloading a purchased vault file is deliberately rate limited, but when you hit that limit the reply came back without a retry-after time and without the limiter's own reason, so a client had no idea how long to wait, and a limiter outage (which deliberately refuses requests rather than letting them through unchecked) was indistinguishable from you genuinely spending your own quota. Both now come back with the refusal, the same way every other vault endpoint already answered. Separately, when browsing the vault, a listing whose stored file details could not be looked up was always reported as \"listed on-chain, details missing\". That is the honest answer when the storage network really has nothing for it, but the same answer was given when the lookup itself was down, quietly turning an outage into what looks like an incomplete listing. A genuine miss still shows as a listing without details; an outage now says the storage lookup is unavailable. Both endpoints also gained full test coverage, including proof that a download link issued to one buyer cannot fetch another buyer's file.",+ "link": "/vault",+ "tags": [+ "fix"+ ]+ },{"date": "2026-08-15","type": "update",diff --git a/public/changelog.xml b/public/changelog.xmlindex e9693e787..b876fdbfa 100644--- a/public/changelog.xml+++ b/public/changelog.xml@@ -38,6 +38,14 @@<category>fix</category><description>Every agent decision is committed to a hash chain, and that chain head is written to Solana on a schedule so anyone can check the history was never edited. The wallet that pays for those on-chain writes ran empty, and the scheduled job could not tell that apart from the harmless case where no signing key is set up at all: it answered a healthy 200 every ten minutes while re-sending the same doomed transaction for twelve agents in a row, and not one head reached the chain. A rejected write is now reported as a rejected write, the rest of the run stops instead of repeating a failure that cannot succeed, and it raises an alert so the wallet gets refilled. Verifying a ledger already worked without the on-chain leg and still does: the recomputed hash chain is the tamper proof, the on-chain write is the independent timestamp on top of it. Separately, the once-a-minute economy heartbeat now refuses to drive production from a machine that is not production, so a developer running it locally can no longer fire thirty-six live money engines at the real site.</description></item>+ <item>+ <title>A vault download rate-limit hit now tells you when to retry, and a browse outage stops reading as an empty listing</title>+ <link>https://three.ws/vault</link>+ <guid isPermaLink="false">2026-08-15:A vault download rate-limit hit now tells you when to retry, and a browse outage stops reading as an empty listing</guid>+ <pubDate>Sat, 15 Aug 2026 12:00:00 GMT</pubDate>+ <category>fix</category>+ <description>Two fixes on the BNB vault endpoints. Downloading a purchased vault file is deliberately rate limited, but when you hit that limit the reply came back without a retry-after time and without the limiter's own reason, so a client had no idea how long to wait, and a limiter outage (which deliberately refuses requests rather than letting them through unchecked) was indistinguishable from you genuinely spending your own quota. Both now come back with the refusal, the same way every other vault endpoint already answered. Separately, when browsing the vault, a listing whose stored file details could not be looked up was always reported as "listed on-chain, details missing". That is the honest answer when the storage network really has nothing for it, but the same answer was given when the lookup itself was down, quietly turning an outage into what looks like an incomplete listing. A genuine miss still shows as a listing without details; an outage now says the storage lookup is unavailable. Both endpoints also gained full test coverage, including proof that a download link issued to one buyer cannot fetch another buyer's file.</description>+ </item><item><title>Agent .sol name lookups work again, and the avatar manifest schema now answers at its own address</title><link>https://three.ws/changelog</link>diff --git a/public/features.json b/public/features.jsonindex b89637ba2..806558b00 100644--- a/public/features.json+++ b/public/features.json@@ -1,5 +1,5 @@{- "generated_at": "2026-08-15T07:54:51.466Z",+ "generated_at": "2026-08-15T15:04:09.638Z","generated_by": "scripts/build-page-index.mjs from data/pages.json","site": {"name": "three.ws",