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(chart-companion): document the 3D chart companion, its OBS overlay and reaction rules, and announce it
nirholas70ec5c48a91b
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex f61972de1..3ae74b7ac 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -275,6 +275,7 @@ bottom.| Global Intel Globe (`/globe`) | Page [pages/globe.html](pages/globe.html) `-> /globe`, renderer [src/globe-intel.js](src/globe-intel.js), pure logic [src/globe-intel-core.js](src/globe-intel-core.js), styles [src/globe-intel.css](src/globe-intel.css); API [api/globe/intel.js](api/globe/intel.js) over [api/_lib/globe-sources.js](api/_lib/globe-sources.js) and [api/_lib/globe-centroids.js](api/_lib/globe-centroids.js); ingest [api/cron/globe-ingest.js](api/cron/globe-ingest.js) -> `globe_events`; reference set [data/globe-reference.json](data/globe-reference.json), geometry baked by [scripts/build-globe-geometry.mjs](scripts/build-globe-geometry.mjs) into [public/data/globe-land.json](public/data/globe-land.json) + [data/country-centroids.json](data/country-centroids.json) | Live | **A 3D globe of what is happening on Earth right now.** Eleven layers on one sphere: armed conflict, force posture and sanctions classified out of the GDELT 2.0 event stream by CAMEO code, attention hotspots computed from them, natural events (USGS, NASA EONET, GDACS), severe weather (GDACS), national internet outages (Georgia Tech IODA), economic stress (World Bank), and the reference geography that gives the live layers meaning: overseas military bases, nuclear sites, and maritime chokepoints that score themselves against the live feed rather than sitting still. Every upstream is keyless, so the page works on a fresh clone. GDELT publishes one file every 15 minutes and no queryable history (its GEO 2.0 API 404s for every query), so the 24h/7d/30d control is only honest because the cron keeps the window in Postgres; each layer reports the span it actually covered and the panel prints "Covers 15h so far" rather than implying a week. A dead upstream renders as a named layer with its reason, never as an empty globe. Camera, zoom, projection, range and layer selection all live in the URL, so any view is a shareable link. Globe and flat map are the same geometry lerped between two projections, written into `position` rather than a vertex shader so every marker stays pickable in both. Docs: [docs/globe.md](docs/globe.md). Tests: [tests/globe-intel-core.test.js](tests/globe-intel-core.test.js), [tests/globe-sources.test.js](tests/globe-sources.test.js) || Token in 3D (`/coin3d`, embeddable) | [pages/coin3d.html](pages/coin3d.html) + [src/coin3d/main.js](src/coin3d/main.js) `→ /coin3d`; pair bridge [api/coin/pair.js](api/coin/pair.js) `→ /api/coin/pair` over `tokenForPool()` in [api/_lib/market/ohlcv.js](api/_lib/market/ohlcv.js) | In-repo | Any Solana token as a live 3D scene: logo medallion, holder galaxy sized by balance, graduation ring, and a tape of real swaps, all from on-chain and live market data, degrading to a data view where WebGL is unavailable. Addressable two ways: `?mint=` (what three.ws keys tokens by) or `?pair=` (what every DEX terminal keys a market by), resolved through `/api/coin/pair`, the inverse of [api/coin/pool.js](api/coin/pool.js). `?embed=1` plus `frame-ancestors *` on the route make it framable on any site, with one attribution link as its only added chrome. Tests: [tests/api/coin-pair.test.js](tests/api/coin-pair.test.js) (route contract), [tests/api/coin-pair-resolver.test.js](tests/api/coin-pair-resolver.test.js) (the resolver and its fallback). Docs: [docs/coin3d-embed.md](docs/coin3d-embed.md) || DEXTools hub + Boost card embed (`/dextools`, `/embed/dextools-boost`) | [pages/dextools.html](pages/dextools.html) + [src/dextools-hub.js](src/dextools-hub.js) `→ /dextools`; [pages/dextools-boost-embed.html](pages/dextools-boost-embed.html) + [src/dextools-boost-embed.js](src/dextools-boost-embed.js) `→ /embed/dextools-boost`; input parser [src/dextools-input.js](src/dextools-input.js); visit totals [api/coin/dextools-stats.js](api/coin/dextools-stats.js) `→ /api/coin/dextools-stats` over `dextools_referrals` (written by the counted redirect [api/coin/dextools.js](api/coin/dextools.js)) | In-repo | Every three.ws x DEXTools integration on one page: the $THREE DEXTools chart beside its `/coin3d?pair=` scene, public visit totals by day, surface and coin, an embed builder that turns any pasted DEXTools / DexScreener / GeckoTerminal / pump.fun / Birdeye link into a 3D-scene or Boost-card snippet with live preview, and the Social Boost wins. The Boost card embed mounts the shared `socialBoostCard()` ([src/shared/dextools-boost.js](src/shared/dextools-boost.js)) with every link counted as `embed-boost`, framable anywhere (`frame-ancestors *`). Tests: [tests/dextools-input.test.js](tests/dextools-input.test.js). Docs: [docs/dextools.md](docs/dextools.md) |+| Chart Companion (`/chart-companion`, embeddable, OBS overlay) | [pages/chart-companion.html](pages/chart-companion.html) + [src/chart-companion/main.js](src/chart-companion/main.js) `→ /chart-companion`; reaction engine [src/chart-companion/reactor.js](src/chart-companion/reactor.js); input parser [src/chart-companion/target.js](src/chart-companion/target.js) | In-repo | A live DEXTools chart with a 3D `<agent-3d>` companion that reacts to every real swap (`/api/pump/dex-trades`, polled): whale buys, dumps, streaks and new 24h highs each get a clip from the shared animation library, a facial emotion and one line built from the swap, with a feed linking every reaction to its transaction. Sizes are judged against the coin's own rolling median, so it works on any coin. Addressed by DEXTools link, `?pair=` or `?mint=`; `?agent=` brings your own agent; `?embed=1` frames anywhere (`frame-ancestors *`); `?overlay=1` is a transparent OBS browser source. Tests: [tests/chart-companion-reactor.test.js](tests/chart-companion-reactor.test.js), [tests/chart-companion-target.test.js](tests/chart-companion-target.test.js). Docs: [docs/chart-companion.md](docs/chart-companion.md) || Market tools (heatmap, sentiment, gas, compare) | [pages/heatmap.html](pages/heatmap.html) + [src/heatmap.js](src/heatmap.js) `→ /heatmap`, [pages/fear-greed.html](pages/fear-greed.html) + [src/fear-greed.js](src/fear-greed.js) `→ /fear-greed`, [pages/gas.html](pages/gas.html) + [src/gas.js](src/gas.js) `→ /gas`, [pages/compare.html](pages/compare.html) + [src/compare.js](src/compare.js) `→ /compare`; backend [api/coin/fear-greed.js](api/coin/fear-greed.js), [api/coin/gas.js](api/coin/gas.js) | In-repo | Four tools extending Markets, same design system: treemap heatmap (market-cap-sized tiles), Fear & Greed gauge + history, live Ethereum gas tracker (keyless `eth_feeHistory`), and up-to-4-coin compare (overlay perf + stats). All real key-free data; cross-linked from the markets table. Docs: [docs/coin-pages.md](docs/coin-pages.md) || Market tools II (screener, categories, exchanges, derivatives, converter, DeFi, chains, stablecoins) | Pages+JS `→ /screener /categories /exchanges /derivatives /converter /defi /chains /stablecoins`; backend [api/coin/](api/coin) (categories, exchanges, derivatives, rates) over CoinGecko + [api/defi/](api/defi) (protocols, chains, stablecoins) over DeFiLlama | In-repo | Eight more Markets tools, same design system: token screener + category rankings + exchange/derivatives tables + crypto⇄fiat converter (CoinGecko), plus a DeFiLlama trio — DeFi TVL by protocol, chains by TVL, stablecoins with peg health. All real key-free data; cross-linked from the markets table. Docs: [docs/coin-pages.md](docs/coin-pages.md) || Market surfaces III (protocol/chain/stablecoin detail + fees, DEX volumes, hacks, trending) | Detail pages `→ /protocol/:slug /chain/:name /stablecoin/:id` over [api/defi/protocol.js](api/defi/protocol.js), [api/defi/chain.js](api/defi/chain.js), [api/defi/stablecoin.js](api/defi/stablecoin.js); surfaces `→ /fees /dex-volumes /hacks` over [api/defi/](api/defi) (fees, dex-volumes, hacks over DeFiLlama) + `→ /markets/trending` over [api/coin/trending.js](api/coin/trending.js) (CoinGecko /search/trending); list rows in [src/defi.js](src/defi.js), [src/chains.js](src/chains.js), [src/stablecoins.js](src/stablecoins.js) now deep-link into the detail pages | In-repo | Turns the DeFiLlama list pages into full detail experiences: a protocol page (TVL history + hallmark markers, per-chain breakdown, fees/revenue, funding rounds, methodology), a chain page (TVL + stablecoin + DEX-volume charts, top protocols), a stablecoin page (supply history, per-chain distribution, peg-deviation badge). Plus three new market surfaces — protocol fees & revenue, the DEX-volume leaderboard, and a searchable DeFi hacks database ($16.7B all-time) — and a CoinGecko trending page (most-searched coins/categories/NFTs). All real key-free data, cross-linked. Docs: [docs/coin-pages.md](docs/coin-pages.md) |diff --git a/data/changelog.json b/data/changelog.jsonindex c5169b2d0..ac6aba803 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, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-08",+ "title": "Chart Companion: a 3D agent that watches the chart with you",+ "summary": "Paste any DEXTools pair at /chart-companion and a 3D agent sits beside the live chart, reacting to every real swap as it lands: a superhero jump for a whale buy, a facepalm for a dump, a dance for a buy streak, applause for a new daily high. Each reaction comes with a line you can trace to its transaction, and it can read them aloud. Bring your own three.ws agent, embed it on your coin's site with one iframe, or add it to OBS as a transparent overlay for your stream.",+ "tags": [+ "feature"+ ],+ "link": "/chart-companion"+ },{"date": "2026-10-08","title": "Agent earnings are updating again",diff --git a/data/pages.json b/data/pages.jsonindex 767c2549e..b7f581ac0 100644--- a/data/pages.json+++ b/data/pages.json@@ -3242,6 +3242,14 @@"changefreq": "monthly","added": "2026-10-08"},+ {+ "path": "/docs/chart-companion",+ "title": "Docs · Chart Companion",+ "description": "How to watch a DEXTools chart with a 3D agent that reacts to every real swap: the URL parameters, streaming it as a transparent OBS overlay, embedding it with one iframe, bringing your own agent, and exactly how whale, streak and new-high reactions are decided.",+ "priority": 0.6,+ "changefreq": "monthly",+ "added": "2026-10-08"+ },{"path": "/docs/coin3d-embed","title": "Docs · Token in 3D, as an embed",diff --git a/docs/chart-companion.md b/docs/chart-companion.mdnew file mode 100644index 000000000..452fe78e4--- /dev/null+++ b/docs/chart-companion.md@@ -0,0 +1,101 @@+# Chart Companion++> **Audience:** Traders who want company on a chart, streamers who show charts live, and coin teams who want a livelier coin page. Also developers embedding it, and the three.ws side for how reactions are decided.++[`/chart-companion`](https://three.ws/chart-companion) puts a live DEXTools chart next to a 3D agent that watches it with you. Every time a real swap lands, the agent reacts: a whale buy gets a superhero jump, a dump gets a facepalm, five buys in a row start a dance, and a buy above the day's high gets a round of applause. Each reaction comes with one spoken-style line built from the swap that caused it ("Whale alert. $4.2K buy on $THREE."), and every line in the feed links to its transaction on Solscan, so nothing on screen is invented.++It is free, keyless, and needs no account.++---++## Use it++Open [/chart-companion](https://three.ws/chart-companion) and paste any of these into the box:++- a DEXTools pair link, such as `https://www.dextools.io/app/en/solana/pair-explorer/CnK82s8exdsK9nwqQ55kd9wcxoA22NwTchZJCBdu8LDa`+- a DEXTools chart widget link (`/widget-chart/...`)+- a bare pair address, or a token mint++With nothing pasted it watches $THREE.++| Control | What it does |+|---|---|+| **Open on DEXTools** | Goes to the coin's DEXTools pair page through [`/api/coin/dextools`](../api/coin/README.md), so the visit counts toward DEXTools Social Boost. |+| **Voice** | Reads each reaction aloud with the browser's own speech engine. Off by default; nothing is sent anywhere. |+| **Avatar picker** | Swaps the companion's body. Every option is a humanoid rig that the shared animation library retargets onto. |+| **Copy link / OBS overlay URL / embed code** | The three ways to take it elsewhere, described below. |++The stats strip (price, 24h change, buys and sells, net flow, biggest swap) covers the recent swaps the page loaded plus every swap since. The feed opens on the notable swaps that already happened, stamped with their real trade times, and only reactions to swaps that arrive while you watch are performed by the avatar.++## Address it by URL++| Parameter | Meaning |+|---|---|+| `pair=<address>` | A DEXTools pair (pool) address. Resolved to its token through [`/api/coin/pair`](./coin3d-embed.md). |+| `mint=<address>` | A token mint. Its most liquid pool becomes the chart's pair, through `/api/coin/pool`. |+| `url=<link>` | A pasted DEXTools link. Solana pairs only; another chain gets a clear message instead of a dead page. |+| `avatar=<name>` | `default`, `michelle`, `realistic-female`, `realistic-male`, or `mannequin`. |+| `agent=<id>` | Use your own three.ws agent as the companion, with its own body. Takes precedence over `avatar`. |+| `voice=1` | Start with the voice on (a browser may still wait for a click before it speaks). |+| `embed=1` | Chart and companion only, for an iframe. |+| `overlay=1` | Companion, speech bubble and a price ticker on a transparent background, for a stream. |++## Stream it++1. Copy the **OBS overlay URL** from the page (it is the current coin with `&overlay=1`).+2. In OBS, add a **Browser Source**, paste the URL, and size it around 500 x 700.+3. Place it over your own chart capture. The background is transparent, so only the companion, its speech bubble and the ticker show.++The overlay keeps polling while OBS has it in the background, so it never misses a swap mid-stream.++## Embed it++```html+<iframe src="https://three.ws/chart-companion?pair=CnK82s8exdsK9nwqQ55kd9wcxoA22NwTchZJCBdu8LDa&embed=1"+ width="960" height="540" style="border:0;border-radius:12px" loading="lazy"+ allow="clipboard-write; fullscreen"+ title="Live chart companion by three.ws"></iframe>+```++The route is served with `frame-ancestors *`, so it frames on any site. Below 900px wide the embed stacks the companion above the chart.++---++## How reactions are decided++Everything lives in one pure module, [src/chart-companion/reactor.js](../src/chart-companion/reactor.js), covered by [tests/chart-companion-reactor.test.js](../tests/chart-companion-reactor.test.js).++- **Size is relative to the coin.** A swap is *big* at 3x the median of the last 60 swaps and a *whale* at 8x, with dollar floors of $150 and $1,000. A $300 buy is noise on a coin doing millions a day and a whale on one doing thousands; the same rule handles both, and a dead tape of tiny swaps never cries whale.+- **New highs are real highs.** The 24-hour high comes from `/api/pump/price-history` candles. A buy that prints above it is called out once, then not again for a minute.+- **Streaks fire once.** Five swaps on the same side make a streak, announced once until the side flips.+- **A burst cannot thrash the avatar.** A frame's reactions are ranked by priority (whales first, then highs, size, streaks, and quiet-tape lines). A new reaction interrupts the current one only if it outranks it; the rest still land in the feed.+- **It narrates, never advises.** Every line describes a swap that already happened. Nothing predicts a price or suggests a trade.++| Event | Clip | Emotion |+|---|---|---|+| Whale buy | `av-superhero-jump` | celebration |+| Whale sell | `defeated` | concern |+| New 24h high | `av-brag-claps` | celebration |+| Big buy / sell | `celebrate` / `facepalm` | celebration / concern |+| Buy / sell streak | `dance` / `shrug` | celebration / concern |+| Quiet for 2 minutes | `think` | patience |++Clips come from the shared library at [`/animations/manifest.json`](https://three.ws/animations/manifest.json) through `<agent-3d>`'s `playClip()`, so they play on any humanoid body, including your own agent's (see [the web component reference](./web-component.md)).++## Data path++| Step | Source |+|---|---|+| Pair to token, symbol, pair name | `GET /api/coin/pair` |+| Token to its chart pair | `GET /api/coin/pool` |+| 24h baseline | `GET /api/pump/price-history?interval=15m` |+| Live swaps, polled every 5s | `GET /api/pump/dex-trades` (edge-cached, so a crowd of viewers shares one upstream poll) |+| The chart | DEXTools' `/widget-chart/` embed, URL built by [src/shared/chart-embeds.js](../src/shared/chart-embeds.js) |++When a source is down, the page says so instead of going blank: the chart falls back to an "open on DEXTools" panel, a coin with no pool yet still gets reactions, and a stalled swap feed dims the LIVE badge and explains itself in the feed.++## Related++- [DEXTools on three.ws](./dextools.md): every DEXTools integration in one place.+- [Token in 3D, as an embed](./coin3d-embed.md): the same pair-or-mint addressing for a 3D scene of the market.+- [STRUCTURE.md](../STRUCTURE.md): where this surface lives.diff --git a/docs/start-here.md b/docs/start-here.mdindex b41e0ee4a..fb978399b 100644--- a/docs/start-here.md+++ b/docs/start-here.md@@ -158,6 +158,7 @@ Want the model in your hands rather than on a screen? [Materialize](./materializ- **Have an audience of your own?** → [The trader card](./trader-card-embed.md): one script tag puts a trader's live on-chain record on your site, blog, link in bio or stream overlay, with a Fork button on every coin and a ghost-copy call to action, all signed by the reader's own wallet. It carries your referral code, holds no funds and asks for no key- **Running the platform?** → [Trading growth programs](./growth-programs.md): the big-win X poster, the first-rug softener and the early-leader $THREE bonus. All three ship disarmed; the page shows how to read what each would do today, every flag and cap, and the exact steps to arm one- **Running a chart page, a launchpad or a wallet?** → [Token in 3D, as an embed](./coin3d-embed.md): one iframe puts a live 3D view of any Solana market on your page, keyed by the mint or by the pair address your own URL already carries, with the coin's logo on a medallion, its holders as a galaxy sized by balance, a graduation ring and real swaps arriving on a tape. Free, keyless, no account, and it degrades to a data view where WebGL is unavailable+- **Streaming charts, or want company on one?** → [Chart Companion](./chart-companion.md): paste any DEXTools pair and a 3D agent watches the live chart with you, reacting to every real swap with a move and a line you can trace to its transaction. Embed it with one iframe, or add it to OBS as a transparent overlay- **Want your community on your DEXTools page?** → [DEXTools integration](./dextools.md): paste any DEXTools pair link at [/dextools](https://three.ws/dextools) and get a 3D scene or a Social Boost card to embed on your own site, and see the visits three.ws sends to DEXTools pair pages, counted in the open- **Want to know what just changed on the board?** → [Rivalries](./rivalries.md): every trader on the arena leaderboard is paired with the one directly above them and labelled an overtake, a debut or a standing chase, with the profit both sides settled in the last 24 hours as the reason. Worked out by rebuilding what the board said at the cutoff from the trade timestamps, so it reaches back over history already recorded and never disagrees with the leaderboard- **Watching identities land on-chain?** → [On-chain deployments](./deployments.md): the live feed of agent identities registering on-chain as it happens, Solana Metaplex Core mints alongside ERC-8004 registrations across 15 EVM chains, with chain footprint and capability stats