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: correct the trader card, coin launch, and tutor references
nirholas4c26d30555e2
diff --git a/agents/tutor/README.md b/agents/tutor/README.mdindex 879f1a78f..56d586db6 100644--- a/agents/tutor/README.md+++ b/agents/tutor/README.md@@ -5,14 +5,15 @@ The teaching engine behind the three.ws Tutor: ask a question (optionally with c## How it works- **Teaching** ([src/teach.js](src/teach.js)): `teach({ question, context, level, anthropicKey })` builds a level-specific system prompt (`beginner`, `intermediate`, `expert`) and asks the shared LLM chain for a JSON object with `explanation`, `keyPoints` (2 to 5), `example`, and `followUp`. Malformed LLM output is coerced into that shape rather than failing. The output-token count is returned so the endpoint can bill accurately.-- **Session ledger** ([src/session.js](src/session.js)): sessions live in Upstash-compatible KV over REST with a 7-day TTL and a 500-entry cap, so a learner can close the tab and resume. `appendCharge()` adds one line item per answer, `loadSession()` reloads the tab, and `closeSession()` marks the session closed and returns an idempotent, attested invoice. Storage is best-effort: with no KV configured the tutor still works as a stateless per-question service.+- **Session ledger** ([src/session.js](src/session.js)): sessions persist for 7 days with a 500-entry cap, so a learner can close the tab and resume. `appendCharge()` adds one line item per answer, `loadSession()` reloads the tab, and `closeSession()` marks the session closed and returns an idempotent, attested invoice (closing the same session twice returns the stored invoice verbatim). Closing an id that has no tab returns a zero invoice without writing anything, so a stray close can never make someone else's session id unusable.+- **Storage tiers** (`sessionBackend()` reports the active one): a Postgres `tutor_sessions` row when `DATABASE_URL` is set (the tier production runs on, table created lazily on first use), an Upstash-compatible KV key when a deployment has KV but no database, and process-local memory when neither is configured (local dev; resume then works inside one server process only). Reads propagate a storage fault to the caller rather than reporting an empty tab, because telling a learner who owes money that they owe nothing is worse than an error; writes on the paid path are best-effort, because a ledger outage must never cost the learner the answer they paid for.## Key files| File | Role ||---|---|| [src/teach.js](src/teach.js) | `teach()`: level-aware structured explanation generation; exports `LEVEL_NAMES` |-| [src/session.js](src/session.js) | Session ledger: `loadSession()`, `appendCharge()`, `closeSession()`, `atomicsToUsd()`, `kvAvailable()` |+| [src/session.js](src/session.js) | Session ledger: `loadSession()`, `appendCharge()`, `closeSession()`, `atomicsToUsd()`, `sessionBackend()` || [../../api/x402/tutor.js](../../api/x402/tutor.js) | `POST /api/x402/tutor`: the paid endpoint, $0.01 per answer || [../../api/tutor/session.js](../../api/tutor/session.js) | Free session endpoint: `GET /api/tutor/session?sessionId=<id>` for the tab, `POST` with `{"action":"end"}` to close || [../../public/tutor.html](../../public/tutor.html) | The `/tutor` page |@@ -41,7 +42,9 @@ Or use the browser UI at [https://three.ws/tutor](https://three.ws/tutor).## Environment variables-- `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` (or `three_KV_REST_API_URL` / `three_KV_REST_API_TOKEN`, or `KV_REST_API_URL` / `KV_REST_API_TOKEN`): session persistence. Optional; without them sessions do not persist across requests.+- `DATABASE_URL`: session persistence (preferred, and what production uses). The `tutor_sessions` table is created on first write.+- `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` (or `three_KV_REST_API_URL` / `three_KV_REST_API_TOKEN`, or `KV_REST_API_URL` / `KV_REST_API_TOKEN`): the KV tier, used only when no database is configured.+- With neither configured, sessions live in process memory and do not survive a restart or reach a second replica.- LLM providers come from the shared chain in [../../api/_lib/llm.js](../../api/_lib/llm.js) (`GROQ_API_KEY`, `OPENROUTER_API_KEY`, and the rest); a caller-supplied Anthropic key can be passed through as BYOK.## Platform connectionsdiff --git a/data/changelog.json b/data/changelog.jsonindex a9f91b874..1882e8279 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -22516,6 +22516,15 @@"improvement"],"link": "/agent-screen"+ },+ {+ "date": "2026-08-15",+ "title": "Claim Your Wallet stopped telling real traders they had no track record",+ "summary": "Pasting a wallet into Claim Your Wallet could answer \"not indexed yet\" to a wallet with thousands of indexed pump.fun trades. The page only accepted a wallet the reputation scorer had already graded, and that scorer runs on a rollup that lags the trade indexer by design, so a wallet the platform had watched trade for days was still turned away. Any wallet with a real on-chain record now renders its full ledger and window aggregates immediately, with the reputation panel honestly reading unproven until the grade lands. Three more fixes shipped with it. Win and loss counts now cover closed positions only, so a trader still holding sixty fresh bags no longer reads as sixty losses, and a new realized profit-and-loss figure sits beside the existing net figure that charges an open bag's entry as if it were written off. Asking for devnet returned the wallet's mainnet trades; both halves of the read are now scoped to the network you asked for. And if the database is unreachable, the page now says the record is temporarily unavailable and offers a retry, instead of publishing an empty scorecard that the CDN would then serve to everyone for the next few minutes.",+ "tags": [+ "fix"+ ],+ "link": "/claim-wallet"}]}diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 83215f4cb..9c20cbe59 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -697,7 +697,7 @@ Gemini, NVIDIA), a session adds the metered ones (OpenAI, ElevenLabs), and an| Param | Meaning || --- | --- |-| `provider` | `edge`, `gemini`, `nvidia`, `openai`, `elevenlabs`. Omit for all. |+| `provider` | `edge`, `gemini`, `nvidia`, `openai`, `elevenlabs`. Omit for all. Anything else is a `400 validation_error` listing the lanes that exist. || `q` | Substring match over name, id, locale, and labels. || `language` | Primary subtag or full locale, e.g. `ja`, `en-GB`. || `limit` | Max voices returned (default 400, max 2000). |@@ -770,6 +770,14 @@ lanes require a session or bearer token.`models` and `direction` fields say which). `speed` is clamped to 0.5 to 2.0.Max 1,000 characters. ElevenLabs additionally accepts `voice_settings`.+`voiceId` must be one the chosen lane publishes. A `voiceId` the lane does not+have returns `400 validation_error` naming the id and the catalog URL to pick+from, before anything is metered; it is never quietly swapped for the lane's+default voice. Omit `voiceId` entirely to get the lane default on purpose.+ElevenLabs is the exception: its catalog grows at runtime (cloning, library+adds), so an id it does not recognize comes back as a `400` carrying the+upstream verdict rather than being pre-checked here.+**Response**Audio binary in the lane's container (`audio/mpeg` for Edge and ElevenLabs,@@ -2172,7 +2180,10 @@ curl -s 'https://three.ws/api/v1/market/projects?limit=5&chain=solana'| Status | Code | Meaning || ------ | --------------- | ------------------------------------------------------------------------ || `429` | `rate_limited` | Either the shared aixbt ceiling or the per-IP gateway budget is spent |+| `429` | `aixbt_rate_limited` | aixbt throttled this deployment's key upstream. Retry shortly. |+| `502` / `504` | `aixbt_upstream_error` | aixbt is erroring or unreachable. The upstream status is relayed. || `503` | `not_configured` | `AIXBT_API_KEY` isn't set on this deployment — never a raw 500 |+| `503` | `aixbt_unauthorized` | aixbt rejected this deployment's key (expired, revoked, or below the plan the read needs). A deployment fault, never the caller's: these routes take no client credential, so they never answer `401`. || `502` | `aixbt_upstream_error` | aixbt returned an unexpected error — retry shortly |---diff --git a/docs/trader-card.md b/docs/trader-card.mdindex 1c73a4db5..c89fbfae0 100644--- a/docs/trader-card.md+++ b/docs/trader-card.md@@ -15,7 +15,9 @@ The Wallet Intelligence view renders, for any base-58 address:Nothing here is typed in by the trader. The Oracle smart-money brain continuously indexes pump.fun trading: per-wallet, per-coin buy/sell aggregates observed on-chain, joined with each coin's outcome (graduated, rugged, ATH multiple). Rollup workers grade every indexed wallet into a reputation row — the same pedigree ledger that powers Oracle's WHO pillar ([the conviction engine](oracle.md)). Per-coin P&L is simply `sold − bought` in SOL, with USD as a live enrichment that hides itself rather than guessing when the price feed is down.-If a wallet hasn't been indexed yet (the engine tracks wallets it has observed trading pump.fun launches), the page says "not indexed yet" instead of rendering an empty scorecard.+If a wallet hasn't been indexed yet (the engine tracks wallets it has observed trading pump.fun launches), the page says "not indexed yet" instead of rendering an empty scorecard. "Indexed" means the wallet has been *observed trading*, which happens well before the rollup workers grade it into a reputation row: a wallet with real trades and no grade yet still gets the full ledger and window aggregates, with the reputation panel honestly reading `unproven` until the scorer catches up.++**Realized vs. open.** Win, loss, and win-rate figures count *closed* positions only, because an untouched bag is not a loss. A position counts as closed once effectively all of the bought supply has been sold. `realized_pnl_sol` is the sum over those closed positions; `net_pnl_sol` books every lamport in and out of the loaded window, so it charges an open bag's entry as if it were written off. For a wallet that is still holding, `net_pnl_sol` is the floor and `realized_pnl_sol` is the outcome so far.**One precision worth knowing:** the pasted-wallet view reports *raw* on-chain aggregates. The platform's own [trader leaderboard](https://three.ws/leaderboard) — which ranks three.ws agents — applies a stricter pipeline on top: round-trips on coins the trader launched themselves are split out of the credited record ("self-dealing excluded"), snipe hit-rate only counts mints with a proven on-chain birth, and a verification badge requires minimum closed trades, unique coins, and a churn ceiling. Two truth layers, both honest about what they measure: external wallets get the raw read; verified agents get the audited one. Details in [trading-arenas](trading-arenas.md).@@ -42,7 +44,13 @@ The preview endpoint is public and cacheable:curl 'https://three.ws/api/traders/preview?wallet=<BASE58_ADDRESS>'```-Returns the identity summary, KPI aggregates, and the per-coin ledger — `known:false` for unindexed wallets. Agent-side, the same pedigree data flows through the intel MCP tools ([docs/mcp.md](mcp.md)).+Returns the identity summary, KPI aggregates, and the per-coin ledger (up to 60 coins, most recently active first).++- `known` is true once the rollup has graded the wallet into a reputation row.+- `claimable` is true once there is a real on-chain record to claim, which includes an indexed-but-not-yet-graded wallet. A wallet with neither is the unindexed case.+- `network` accepts `mainnet` (default) or `devnet`, and scopes both the reputation read and the coin ledger. Anything else falls back to `mainnet`.++The read is CDN-cacheable for two minutes. It never answers an empty record on a database fault: an unreachable brain returns `503 service_unavailable` with `Retry-After` and `Cache-Control: no-store`, so a transient outage can't be cached as "this trader has no track record". Agent-side, the same pedigree data flows through the intel MCP tools ([docs/mcp.md](mcp.md)).## Relateddiff --git a/docs/ux-flows/08-coin-launch-wallets.md b/docs/ux-flows/08-coin-launch-wallets.mdindex 4ebc58c73..32c82c44b 100644--- a/docs/ux-flows/08-coin-launch-wallets.md+++ b/docs/ux-flows/08-coin-launch-wallets.md@@ -83,13 +83,13 @@ real Solana/EVM RPC, pump.fun, and x402 — no mocks.- **Steps (N):**1. Boot warms `GET /api/auth/me`. `?wallet=` param pre-fills + auto-previews.2. User pastes a base-58 Solana wallet; client validates with `WALLET_RE`.- 3. Click **Preview** → `GET /api/traders/preview?wallet=` → renders the Trader Card: label, win rate / early-win / smart-money score / net PnL / dumps stats, and up to 15 recent pump.fun coins.+ 3. Click **Preview** → `GET /api/traders/preview?wallet=` → renders the Trader Card: label, win rate / early-win / smart-money score / net PnL / dumps stats, and up to 60 recent pump.fun coins.4. CTA branches by state: claimed (View card + Share) / signed-in-unclaimed (Claim button) / signed-out (Sign-in-to-claim link). Claimed status verified via `GET /api/auth/wallets` (filtered to chain_type=solana).5. (claim) User clicks **Claim this wallet** → detect provider → `provider.connect()`. If connected pubkey ≠ previewed wallet, abort with a switch-wallet message.6. `POST /api/auth/wallets/nonce-solana` → `provider.signMessage` (gasless, no tx) → base64.7. `POST /api/auth/wallets/link-solana` with message+signature. A 409 `address_in_use` prompts a `window.confirm` takeover; on confirm, re-POST with `takeover:true`.8. On success, re-read linked wallets (force) and re-render in the claimed state; message "Claimed — your Trader Card is live."-- **Decision points / branches:** claimable+known vs. not-indexed (`notFoundHtml`); signed-in vs out; wallet-mismatch; takeover confirm; share via Web Share API vs Twitter intent.+- **Decision points / branches:** claimable-or-known vs. not-indexed (`notFoundHtml`); a wallet the indexer has seen trade is claimable even before the rollup grades it, so only a wallet with neither a reputation row nor a single indexed trade takes the not-indexed branch; signed-in vs out; wallet-mismatch; takeover confirm; share via Web Share API vs Twitter intent.- **External calls / dependencies:** `/api/auth/me`, `/api/traders/preview`, `/api/auth/wallets`, `/api/auth/wallets/nonce-solana`, `/api/auth/wallets/link-solana`. Wallet providers: Phantom/Solana/Backpack/Solflare.- **Success state:** "Your Trader Card is live" card with View (`/trader/:wallet`) + Share buttons; linked row reflected server-side.- **Empty / error states:** invalid-address inline error; "Wallet not yet indexed" not-found state; signature-cancelled message; per-step error toasts on the claim button.