Skip to content

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.

docs(wrapped): document the trader wrapped recap and map it in STRUCTURE

nirholas4aa51768622d
diff --git a/STRUCTURE.md b/STRUCTURE.md
index 7ff45efd9..875a31e71 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -265,6 +265,7 @@ bottom.
| Meta-Allocator (the ETF of degens) | [pages/meta-allocator.html](pages/meta-allocator.html) + [src/meta-allocator.js](src/meta-allocator.js) `→ /meta-allocator`, brain [api/_lib/meta-allocator.js](api/_lib/meta-allocator.js), endpoint [api/meta-allocator.js](api/meta-allocator.js) | Live (non-custodial planning) | Spreads a budget across the top verified pump.fun leader agents, ranked by risk-adjusted on-chain track record (win rate, realized ROI, peak-to-trough max drawdown from `agent_sniper_positions`) and diversified across derived correlation groups, then returns a rebalance rule. Free-first `llmComplete` shaping with a deterministic same-shape fallback so it never fails. Returns a plan (weights + suggested sizes), never a transaction; users act one leader at a time via [/vaults](pages/vaults.html). Doc: [docs/meta-allocator.md](docs/meta-allocator.md). |
| Alpha-drip (a leader prices their signal latency) | Ladder rules [api/\_lib/alpha-drip.js](api/_lib/alpha-drip.js), fanout half [api/\_lib/copy-drip-runtime.js](api/_lib/copy-drip-runtime.js), measured edge half-life [api/\_lib/alpha-drip-stats.js](api/_lib/alpha-drip-stats.js), endpoint [api/copy/alpha-drip.js](api/copy/alpha-drip.js) `-> /api/copy/alpha-drip`, leader editor [src/alpha-drip-panel.js](src/alpha-drip-panel.js) mounted on [/dashboard/copy](src/dashboard-next/pages/copy.js), copier seat on the trader page [src/copy-panel.js](src/copy-panel.js), schema [api/\_lib/migrations/20260903235500\_copy\_alpha\_drip.sql](api/_lib/migrations/20260903235500_copy_alpha_drip.sql) | Live (off unless a leader turns it on) | The $THREE sink on the copy rail: a leader sets how long each holder tier waits before a copy intent is revealed to them, so the thing being sold is latency rather than only a share of the profit. Two rules are structural and enforced server-side: a higher tier can never wait longer than a lower one, and **a drip delays the reveal, never the record** (the intent row is written in full at fanout time and the public track record is untouched, so there are no hidden trades). The copier is shown the seat their balance buys BEFORE they subscribe, not after; a locked intent renders as a countdown that unlocks in place, and `POST /api/copy/executions` refuses an unreleased one in the same statement that changes its status, so the guard cannot be raced. Tier size caps are applied after the copy engine has sized and gated the order, never before, so the copier's own caps still bind first. The edge half-life the fairness warning judges a ladder against is measured from the leader's own profitable closes, and is null rather than guessed below five of them. Release runs inside [api/cron/copy-fanout.js](api/cron/copy-fanout.js) rather than a second cron, so the release cadence is the fanout cadence. Doc: [docs/alpha-drip.md](docs/alpha-drip.md). Tests: [tests/alpha-drip.test.js](tests/alpha-drip.test.js) |
| Ghost-copy (paper-copy a leader) | [pages/ghost-copy.html](pages/ghost-copy.html) + [src/ghost-copy.js](src/ghost-copy.js) `→ /ghost-copy`, simulator [api/_lib/ghost-copy.js](api/_lib/ghost-copy.js), endpoint [api/pump/ghost-copy.js](api/pump/ghost-copy.js), tests [tests/ghost-copy.test.js](tests/ghost-copy.test.js) | Live (paper only, zero custody) | The bridge between the leaderboard and actually copying someone. Pick a verified trader agent, a budget and a window, and it replays that agent's real closed on-chain round-trips (`agent_sniper_positions`) against a wallet that does not exist, sizing every order through `planCopyOrder`, the SAME function the live [copy-fanout cron](api/cron/copy-fanout.js) uses, so the result is what the copy engine would actually have generated rather than a marketing figure. Deliberately unflattering: P&L per trade is derived from exact chain lamports (never the stored pct column), losing round-trips all count, the ghost wallet has a real cash constraint so capital locked in an open copy blocks the next one, every skip carries a machine reason plus a human sentence, and the leader's still-open positions are marked at THEIR last on-chain quote and reported as unrealized outside the realized headline. Needs no account, no wallet, no signature and no funded signer, so it ships ahead of any custody decision; state lives in the query string so a result is deep-linkable and shareable. Converts into [/vaults](pages/vaults.html) for real money. Doc: [docs/ghost-copy.md](docs/ghost-copy.md). |
+| Trader Wrapped (season recap) | [pages/wrapped.html](pages/wrapped.html) + [src/wrapped.js](src/wrapped.js) `→ /wrapped`, deck builder [api/_lib/wrapped.js](api/_lib/wrapped.js), endpoint [api/pump/wrapped.js](api/pump/wrapped.js), social card [api/wrapped-og.js](api/wrapped-og.js), share page [api/wrapped-share.js](api/wrapped-share.js) `→ /wrapped/<agent_id>/share`, tests [tests/wrapped.test.js](tests/wrapped.test.js) | Live (read-only, zero custody) | The artifact the trading stack was missing: one image and one link that say what a season was. Eight slides cut server-side from a trader agent's closed on-chain round-trips (scoreboard, best trade, worst trade, the coin that carried it, rhythm, rank against the field with the nearest rival, receipt), swipeable on touch and keyboard-driven on desktop, with the current slide in the URL hash so a share link lands on the slide the sharer was reading. Arithmetic is delegated wholesale to `computeTraderMetrics` in [api/_lib/trader-stats.js](api/_lib/trader-stats.js), the same truth layer the leaderboard and trader profile use, so a recap can never disagree with the profile it links to. Deliberately unflattering: the worst-trade slide is not optional, the scoreboard carries an explicit verdict and colors a red season red, per-coin ranking includes coins that lost money, self-launched coins stay excluded from every superlative, the rank always prints the size of the real field beside it, and under 3 settled round-trips the page says there is no season rather than drawing a chart out of noise. Needs no account, wallet, signature or funded signer. Converts through [Fork](src/fork-trade.js) on the best-trade slide and links onward to the verified profile, [Ghost-copy](pages/ghost-copy.html) and the rival's own wrapped. Doc: [docs/trader-wrapped.md](docs/trader-wrapped.md). |
| Clip Director (content engine) | [pages/clip-director.html](pages/clip-director.html) + [src/clip-director-page.js](src/clip-director-page.js) `→ /clip-director`, brain [api/_lib/clip-director.js](api/_lib/clip-director.js), endpoint [api/clip-director.js](api/clip-director.js) | Live | Turns one real closed trade (`agent_sniper_positions`) into the optimal shareable card per surface (X / Telegram / Feed): honest hook, the real number, an avatar gesture mapped to a real animation clip, CTA, and alt text, plus an on-chain proof link. Losses get an honest card too. Free-first `llmComplete` with a deterministic same-shape fallback. Doc: [docs/clip-director.md](docs/clip-director.md). |
| Atlas (site-wide Cmd+K search + route map) | Palette [public/atlas.js](public/atlas.js) `-> /atlas.js`, ranking [public/atlas/score.js](public/atlas/score.js), map page [pages/atlas.html](pages/atlas.html) + [src/atlas-page.js](src/atlas-page.js) `-> /atlas`, index [scripts/build-atlas-index.mjs](scripts/build-atlas-index.mjs) `-> public/atlas-index.json`, task catalog [data/atlas-intents.json](data/atlas-intents.json), coverage [scripts/inject-atlas.mjs](scripts/inject-atlas.mjs) | Live | **Discovery layer for 650+ routes.** Cmd+K (or `/`) opens a search over every page in `data/pages.json` plus a curated set of TASKS that answer with ordered steps rather than one link, because "which page starts the get-paid flow" is a harder question than "where is /x402/studio". Zero-dependency single file so it runs identically on 250+ standalone HTML entry points; the index is fetched on first open, not page load. Every task step target is resolved against the real route table at build time, so an onboarding path cannot dead-end on a 404. Injected by a Vite `three-ws-atlas` plugin plus a post-build `dist/` walk (same belt-and-suspenders as [scripts/inject-tour-boot.mjs](scripts/inject-tour-boot.mjs), for the same plugin-ordering reason). Embeds and the nav/footer fragments are excluded. Doc: [docs/atlas.md](docs/atlas.md). Tests: [tests/atlas.test.js](tests/atlas.test.js). |
| Internationalization (i18n) | Runtime [src/i18n.js](src/i18n.js) `→ /i18n.js`; catalogs [public/locales/](public/locales) (`en` + 84 locales, `manifest.json`, `localized-pages.json`); pipeline [scripts/i18n-annotate.mjs](scripts/i18n-annotate.mjs) · [i18n-extract.mjs](scripts/i18n-extract.mjs) · [i18n-translate.mjs](scripts/i18n-translate.mjs) (Vertex Gemini, glossary-locked) · [i18n-backfill.mjs](scripts/i18n-backfill.mjs) (re-translates copy that was baked to English during a backend outage); hreflang in [api/sitemap/[type].js](api/sitemap/%5Btype%5D.js) | Live (85 languages) | LobeHub-model client-side copy swap. `npm run i18n:annotate` auto-injects `data-i18n*` into static HTML (byte-surgical), `i18n:extract` builds `en.json`, `i18n:translate` fans it out to every locale via Vertex with brand/protocol terms masked. `i18n:backfill` finds keys whose value is still byte-identical to English (the silent failure mode: a baked fallback is present, so every later run skips it) and re-translates them. Runtime auto-detects locale, mounts a floating `<lang-switcher>`, and injects hreflang. Doc: [docs/i18n.md](docs/i18n.md). Tests: [tests/i18n.test.js](tests/i18n.test.js), [tests/i18n-annotate.test.js](tests/i18n-annotate.test.js), [tests/i18n-backfill.test.js](tests/i18n-backfill.test.js). |
diff --git a/docs/trader-wrapped.md b/docs/trader-wrapped.md
new file mode 100644
index 000000000..199eb93a1
--- /dev/null
+++ b/docs/trader-wrapped.md
@@ -0,0 +1,178 @@
+# Trader Wrapped: the season recap
+
+Trader Wrapped is the shareable recap of a pump.fun trading agent's season on
+three.ws. It answers, in eight slides, what a leaderboard row never does: what
+the season actually made, which trade carried it, which trade hurt, the rhythm
+behind both, and where the trader finished against the field.
+
+Page: [/wrapped](https://three.ws/wrapped) · API: `/api/pump/wrapped` ·
+Share: `/wrapped/<agent_id>/share` · Card: `/api/wrapped-og`
+
+Everything on the page is read-only. It signs nothing, spends nothing, connects
+no wallet, and needs no account: a recap is arithmetic over round-trips that
+already settled on-chain. The one live action is [Fork](fork-trade.md) on the
+best-trade slide, which opens the real pump.fun trade panel for that coin and
+lets your own wallet sign it. Forking is opt-in and never happens as part of
+viewing a recap.
+
+## Why it exists
+
+A trader's edge is already provable here: the
+[leaderboard](https://three.ws/leaderboard) ranks agents on a verified record,
+[trader profiles](https://three.ws/trader) show every closed round-trip with its
+buy and sell signature, and [Ghost-copy](ghost-copy.md) replays a leader against
+a budget you choose. What none of those produce is an *artifact*: one image and
+one link that says what a season was, that a person actually wants to post.
+
+Wrapped is that artifact. It is deliberately the least dangerous surface in the
+trading stack (no custody, no funded signer, no account) and the most portable,
+which is why it can ship and travel ahead of any custody decision.
+
+## The eight slides
+
+Slides are assembled server-side and arrive in reading order. A slide with no
+evidence behind it is dropped, never rendered empty.
+
+| Slide | What it says | Where the number comes from |
+| --- | --- | --- |
+| `intro` | The span, round-trips closed, coins traded, active days | closed positions in the window |
+| `scoreboard` | Realized P&L in SOL and USD, ROI, win rate, profit factor, the equity curve | `realized_pnl_lamports` summed exactly, `entry_quote_lamports` as the cost basis |
+| `best_trade` | The season's biggest percentage winner, with hold time and both signatures | the closed position with the highest `realized_pnl_pct` |
+| `worst_trade` | The biggest loser, stated plainly | the closed position with the lowest `realized_pnl_pct` |
+| `top_coins` | The coin that carried the season, plus the next two | per-mint realized P&L, ranked, losers included |
+| `rhythm` | Streaks, active days, median hold, peak trading hour, best and busiest day, fastest win, longest hold | derived from open and close timestamps |
+| `rank` | Position against every comparable trader in the same window, and the nearest rival | realized P&L across public agents with at least 3 closed round-trips |
+| `receipt` | Composite score, verification state, drawdown, consistency, snipe hit rate, self-dealing exclusions | `computeTraderMetrics` in `api/_lib/trader-stats.js` |
+
+## What makes it honest
+
+A recap that only flatters is worth nothing to the reader and nothing to the
+trader who posts it. Every rule below costs the headline something:
+
+- **One truth layer.** Wrapped calls the same
+ [`computeTraderMetrics`](../api/_lib/trader-stats.js) that the leaderboard and
+ the trader profile call. A recap can never disagree with the profile it links
+ to, because there is only one place the arithmetic happens.
+- **A losing season reads as a losing season.** The scoreboard slide carries an
+ explicit verdict, the number is colored by its real sign, and the equity curve
+ draws its break-even line so a red season previews red in the social card.
+- **The worst trade is not optional.** It is a slide, not a footnote. Hiding
+ losers is the easiest way to fake a record, and this surface exists to be the
+ opposite of a screenshot.
+- **Superlatives inherit the anti-gaming rules.** Round-trips on coins the
+ trader's own account launched are excluded from every number, best trade
+ included, so nobody's signature win is a coin they minted. The excluded count
+ is shown on the receipt slide rather than quietly dropped.
+- **The rank is a real field, not a percentile of everyone.** It ranks only
+ public agents with at least 3 settled round-trips in the same window and
+ network, and always prints the size of that field beside the rank.
+- **Too little history means no recap.** Under 3 closed round-trips the page
+ says so and offers a wider window. It does not draw a chart out of noise.
+- **USD is an enrichment.** SOL amounts come from chain. If the price feed is
+ down, dollar figures are omitted rather than invented.
+
+## Using it
+
+### The picker
+
+```bash
+curl 'https://three.ws/api/pump/wrapped?window=30d&limit=24'
+```
+
+Returns public agents with enough settled history for a recap, ranked by
+activity rather than P&L so a busy losing season is still discoverable:
+
+```json
+{
+ "network": "mainnet",
+ "window": "30d",
+ "windows": ["7d", "30d", "all"],
+ "min_closed": 3,
+ "traders": [
+ {
+ "agent_id": "6287faf3-d41b-43cb-97bb-d305c1ac6e45",
+ "name": "Crosshair",
+ "closed": 270,
+ "coins": 270,
+ "win_rate_pct": 15.93,
+ "pnl_sol": 0.0008,
+ "wrapped_url": "/wrapped?agent=6287faf3-d41b-43cb-97bb-d305c1ac6e45",
+ "profile_url": "/trader/6287faf3-d41b-43cb-97bb-d305c1ac6e45"
+ }
+ ],
+ "custody": "none"
+}
+```
+
+### The deck
+
+```bash
+curl 'https://three.ws/api/pump/wrapped?agent=<agent_id>&window=all'
+```
+
+```json
+{
+ "agent": { "id": "<agent_id>", "name": "Crosshair", "profile_url": "/trader/<agent_id>" },
+ "window": "all",
+ "enough_history": true,
+ "closed_count": 270,
+ "headline": "Crosshair closed 270 round-trips across 270 coins for +0.000780 SOL. Best trade: +237% on $SHTCOIN.",
+ "slides": [{ "kind": "intro" }, { "kind": "scoreboard" }],
+ "share_url": "/wrapped/<agent_id>/share",
+ "custody": "none"
+}
+```
+
+Parameters: `agent` (an agent UUID; omit for the picker), `window`
+(`24h`, `7d`, `30d`, `all`; default `30d`), `network` (`mainnet` or `devnet`),
+`limit` (picker only, 1 to 100). A bad value is answered as a caller mistake
+(`400 invalid_agent`, `invalid_window`, `invalid_network`), never as an outage.
+An unknown or private agent is `404 agent_not_found`. Both shapes are public,
+IP rate-limited, and edge-cached.
+
+### The share link
+
+`/wrapped/<agent_id>/share` is a server-rendered page whose only job is the
+preview: Open Graph, Twitter Card, and a Farcaster Frame built from the same
+deck, with the social image at `/api/wrapped-og?agent=<agent_id>&window=<window>`.
+A real browser is redirected straight to the deck. When the sharer is signed in,
+the Share and Post-to-X buttons append their referral code, so the link that
+travels pays whoever spread it.
+
+## Keyboard and navigation
+
+| Key | Action |
+| --- | --- |
+| `→` / `j` / space | Next slide |
+| `←` / `k` | Previous slide |
+
+Touch devices swipe horizontally. The current slide lives in the URL hash
+(`#s=3`), so a link lands the reader on the slide the sharer was reading, and
+browser back and forward walk the deck.
+
+## Where it connects
+
+- Every deck links to the trader's [verified profile](https://three.ws/trader)
+ to check the record on-chain, and to [Ghost-copy](ghost-copy.md) to replay the
+ same trader against a budget of your own.
+- The rank slide links to the nearest rival's profile and to *their* wrapped,
+ which is what makes a recap worth arguing about.
+- The best-trade slide carries a [Fork](fork-trade.md) button for the coin, so a
+ recap converts on the spot instead of being a dead end.
+- The picker links onward to the [leaderboard](https://three.ws/leaderboard) and
+ the [live trade feed](trading-surfaces.md).
+
+## Where the code lives
+
+| Piece | File |
+| --- | --- |
+| Deck builder and peer rank (pure arithmetic plus the two queries) | [api/_lib/wrapped.js](../api/_lib/wrapped.js) |
+| Endpoint (picker and deck) | [api/pump/wrapped.js](../api/pump/wrapped.js) |
+| Page shell | [pages/wrapped.html](../pages/wrapped.html) |
+| Deck renderer | [src/wrapped.js](../src/wrapped.js) |
+| Social card | [api/wrapped-og.js](../api/wrapped-og.js) |
+| Share page | [api/wrapped-share.js](../api/wrapped-share.js) |
+| Shared truth layer | [api/\_lib/trader-stats.js](../api/_lib/trader-stats.js) |
+
+Coins named in a recap are runtime data: whatever the agent actually traded.
+$THREE remains the only coin this platform promotes.