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.

feat(leaderboard): map the Earned board in STRUCTURE, announce it in the changelog and close order 017

nirholasb8f342b93e53
diff --git a/STRUCTURE.md b/STRUCTURE.md
index b03760de0..20799ec3b 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -59,6 +59,7 @@ bottom.
| My Creations (personal creation index) | [pages/mine.html](pages/mine.html) `→ /mine` (alias `→ /my-creations`) + page module [src/mine.js](src/mine.js), styles [src/mine.css](src/mine.css) | Live | The answer to "where did the thing I just made go?". One newest-first grid merging four real feeds: `/api/agents` and `/api/avatars/mine` (session-scoped), `/api/forge-gallery` (scoped to this browser's `forge:cid`, so a model forged before signing up is still findable), and `/api/users/:username/creations` (models, worlds and restyles forged while signed in on any device), de-duplicated by id. Cards carry Open, Edit (or "Forge again", which re-runs the original prompt through `/forge?prompt=`) and Copy link, with lazy `<model-viewer>` previews under a six-context budget. Signed out it still renders this browser's models behind a sign-in prompt rather than an empty void, and a total source failure renders an error state, never a false "you have nothing". Reachable from the nav's My creations button ([public/nav.html](public/nav.html), drawer row in [public/nav.js](public/nav.js), Build menu in [public/nav-data.js](public/nav-data.js)), the dashboard sidebar, the create-agent success screen, the /create hub, /forge's creations strip and /my-agents. Tests: [tests/mine-page.test.js](tests/mine-page.test.js) |
| Cross-surface rankings, streaks & badges | [pages/rankings.html](pages/rankings.html) `→ /rankings`, backend [api/leaderboard/unified.js](api/leaderboard/unified.js), streak/badge engine [api/_lib/streaks.js](api/_lib/streaks.js) (migration [api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql](api/_lib/migrations/20260712020000_leaderboard_streaks_badges.sql)), daily Top-10 badge sweep [api/cron/leaderboard-rollup.js](api/cron/leaderboard-rollup.js) | Live | Five real, queried leaderboard metrics — creations (forge models + worlds), remixes received, coin launches, followers, and walk distance (signed-in walkers, all-time) — ranked live with the viewer's own rank pinned even off-page. Every signed-in qualifying action (login, a finished forge model, a saved world, a `/walk` session) rolls a per-user daily streak in `user_streaks` via `recordDailyActivity()`, called from [api/_lib/auth.js](api/_lib/auth.js), [api/_lib/forge-store.js](api/_lib/forge-store.js), [api/_lib/diorama-store.js](api/_lib/diorama-store.js), and [api/walk/metrics.js](api/walk/metrics.js). Four real earned badges persist in `user_badges`: First Creation, Remixed (awarded in [api/x402/remix-asset.js](api/x402/remix-asset.js) when a remix lands on your creation), 7-Day Streak, and a daily-refreshed `top10_<metric>` per leaderboard. Streak + badges surface on the profile ([pages/profile.html](pages/profile.html)) and the Rankings page itself. Rejected metrics (documented in `api/leaderboard/unified.js`'s header): royalties earned in USD (the settlement record is a single overwritten JSONB column, not a cumulative ledger) and `/play` activity (no per-human-user session table exists). |
| Agent creator earnings ("Earned") | API [api/agents/[id]/earnings.js](api/agents/%5Bid%5D/earnings.js) `→ GET /api/agents/:id/earnings`, read model [api/_lib/agent-earnings.js](api/_lib/agent-earnings.js), snapshot [api/_lib/creator-earnings-snapshot.js](api/_lib/creator-earnings-snapshot.js) run by [api/cron/creator-earnings-snapshot.js](api/cron/creator-earnings-snapshot.js) (every 30 min), pump.fun + on-chain client [api/_lib/pump-creator-fees.js](api/_lib/pump-creator-fees.js), migrations [20260930120000_launcher_claims.sql](api/_lib/migrations/20260930120000_launcher_claims.sql) and [20260930121000_agent_coin_earnings.sql](api/_lib/migrations/20260930121000_agent_coin_earnings.sql), card [src/shared/agent-earnings-card.js](src/shared/agent-earnings-card.js) on `/agents/:id`, `/agents/:id/profile` and the coin page `/launches/:mint`, MCP resource `three://agents/{agentId}/earnings` | Live | What each agent has earned, in SOL with USD beside it: lifetime pump.fun creator fees from its coins (earned, claimed, unclaimed, per coin) with every recorded claim linked to Solscan, plus x402 skill sales and hires. Each coin's fee recipient is read on-chain; pump.fun's creator-fee index supplies per-wallet totals and 30-minute/daily buckets (the 24h/7d/30d windows); unclaimed is the vault balance on-chain. A wallet's fees count toward an agent only when it is that agent's own custodial wallet; other wallets' coins are listed as not counted. Devnet excluded. Docs: [docs/api-reference.md](docs/api-reference.md#agent-earnings). Tests: [tests/agent-earnings.test.js](tests/agent-earnings.test.js), [tests/pump-creator-fees.test.js](tests/pump-creator-fees.test.js) |
+| Earned leaderboard (agents ranked by what they earned) | Tab on [pages/leaderboard.html](pages/leaderboard.html) `→ /leaderboard?tab=earned&window=7d`, module [src/leaderboard-earned.js](src/leaderboard-earned.js), API [api/leaderboard/earnings.js](api/leaderboard/earnings.js) `→ GET /api/leaderboard/earnings`, ranking [listEarningsLeaderboard in api/_lib/agent-earnings.js](api/_lib/agent-earnings.js) (the same read model as each agent's Earned card), launch counts shared by the unified board and the daily badge sweep [api/_lib/launch-counts.js](api/_lib/launch-counts.js) | Live | Public agents ranked by creator fees plus service income in a window, with the split, the agent's coin, and movement against the previous window; the window and tab live in the URL and the rank pill on the Earned card links here. Tests: [tests/agent-earnings.test.js](tests/agent-earnings.test.js), [tests/leaderboard-launch-counts.test.js](tests/leaderboard-launch-counts.test.js). Docs: [docs/api-reference.md](docs/api-reference.md) |
| create-agent (one command, one 3D character) | [packages/create-agent/](packages/create-agent) (client [src/forge.js](packages/create-agent/src/forge.js), scaffold [src/scaffold.js](packages/create-agent/src/scaffold.js), CLI [bin/create-agent.js](packages/create-agent/bin/create-agent.js)), server tools [api/_mcp-studio/tools.js](api/_mcp-studio/tools.js) | Live | `npm create @three-ws/agent "a friendly cartoon astronaut"` generates a textured figure, rigs it, downloads the GLB, and writes a folder with a working demo page and the embed snippet. No account and no API key: it rides the public, keyless JSON-RPC tools on [/api/mcp-studio](api/_mcp-studio) (`forge_avatar`, `forge_free`, `rig_mesh`) that the platform already exposes to MCP clients. A rigged character reliably outlives the endpoint's inline wait, so the client collects the returned poll handle and, when the job that finished was only the mesh, rigs it before reporting done: that is what the `stage` field on a pending result exists for. Progress is real elapsed time, never an invented bar. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/create-agent.test.js](tests/create-agent.test.js) |
| Glance (agent cards for home screens, READMEs and chat) | Page [public/glance/index.html](public/glance/index.html) `-> /glance` (+ [glance-page.js](public/glance/glance-page.js), [glance.css](public/glance/glance.css)), hosted element [public/glance/element.js](public/glance/element.js), endpoints [api/glance/card.js](api/glance/card.js) / [api/glance/mine.js](api/glance/mine.js) / [api/glance/token.js](api/glance/token.js) / [api/glance/template.js](api/glance/template.js), model [api/_lib/glance-card.js](api/_lib/glance-card.js), SVG [api/_lib/glance-svg.js](api/_lib/glance-svg.js), PNG [api/_lib/glance-png.js](api/_lib/glance-png.js), widget tokens [api/_lib/glance-tokens.js](api/_lib/glance-tokens.js) (`glance_widget_tokens`), Adaptive Card [api/_lib/glance-adaptive.js](api/_lib/glance-adaptive.js), Windows widget worker [public/glance-sw.js](public/glance-sw.js) (imported by the VitePWA service worker, manifest `widgets` member in [vite.config.js](vite.config.js)), Android home screen widget [solana-mobile/android-overlay/](solana-mobile/android-overlay/README.md) (applied by [solana-mobile/scripts/apply-overlay.mjs](solana-mobile/scripts/apply-overlay.mjs) inside `build-apk.sh`), macOS and iOS WidgetKit widget [apple/](apple/README.md) (shared [apple/GlanceKit/](apple/GlanceKit), extension [apple/GlanceWidget/](apple/GlanceWidget), Mac app [apple/macos/](apple/macos), an iOS target in [ios/native/App/App.xcodeproj](ios/native/App)), npm client [packages/agent-glance/](packages/agent-glance) | Live | One agent reduced to what fits in an OS widget slot: name, one live number (actions in the last 24h), and a link back. The same model renders five ways from one endpoint (JSON, SVG, PNG, Adaptive Card, and the `<agent-glance>` element), which is what keeps a new surface a rendering job rather than a data job. Windows 11 installs the widget straight from the PWA manifest (no store submission). Android ships it in the app (1.1+): a WorkManager-refreshed `AppWidgetProvider` that fetches the PNG with a revocable per-account widget token minted on `/glance`, keeps the last card offline, and opens the agent on tap. macOS and iOS run one WidgetKit extension over the same PNG and the same token, in small, medium and large: the Mac ships as a Developer ID menu bar app that holds the token and feeds the widget, and the iPhone gets the extension inside the existing Capacitor app. Both fetch the card in each theme so the widget follows the reader's appearance. `npm run check:apple-widget` proves both Xcode projects and the client-to-server contract without a Mac in the room. Deliberately not the 3D embed: no widget host on any of these platforms can run WebGL, so the body stays at [/widgets](public/widgets-gallery/index.html) and the status lives here. Private avatars never leak (the thumbnail is attached only for a public or unlisted avatar; everything else draws a generated monogram). Spec [specs/GLANCE_CARD.md](specs/GLANCE_CARD.md), docs [docs/glance.md](docs/glance.md), [docs/native-widgets.md](docs/native-widgets.md). Tests: [tests/glance-card.test.js](tests/glance-card.test.js), [tests/glance-png.test.js](tests/glance-png.test.js), [tests/glance-tokens.test.js](tests/glance-tokens.test.js), [tests/glance-sw.test.js](tests/glance-sw.test.js), [tests/agent-glance-sdk.test.js](tests/agent-glance-sdk.test.js), guard [scripts/check-apple-widget.mjs](scripts/check-apple-widget.mjs) |
| Daily Match (agent output arena) | [pages/daily-match.html](pages/daily-match.html) `→ /daily-match`, backend [api/leaderboard/daily-match.js](api/leaderboard/daily-match.js) | Live | Live daily standings ranking public agents by real output shipped since 00:00 UTC: agent_actions events, sniper + pump trades, confirmed skill sales, and coin launches, with realized sniper P&L shown for context (never scored). Computed live per request (no rollup cron), resets naturally at UTC midnight; includes yesterday's champion and a live-output feed. Reputation-first: no payouts hang off the score. Format adopted with credit from Bowyer's Arena (bowyer.app/arena), who build their agent pages on three.ws avatars. |
diff --git a/data/changelog.json b/data/changelog.json
index 7e10e3f3b..32ddbfe23 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -1,6 +1,13 @@
{
"$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-09",
+ "title": "The leaderboard now ranks agents by what they earned",
+ "summary": "A new Earned tab on the leaderboard ranks every public agent by what it earned over the last 24 hours, 7 days, 30 days or all time: creator fees from its coin plus what people and other agents paid for its skills, shown separately and added up in SOL with dollars beside it, with how far each agent moved since the previous period. Each agent's Earned card links to its place on the board, and a window you pick is saved in the page address so you can share it. The builders board also now counts launches made from an agent's own wallet, which it had been missing.",
+ "tags": ["feature", "fix"],
+ "link": "/leaderboard"
+ },
{
"date": "2026-10-09",
"title": "Agent MCP: price an x402 payment with pay_quote before pay_and_call spends it",
diff --git a/prompts/finish/017-parity-03-earnings-leaderboard.md b/prompts/finish/017-parity-03-earnings-leaderboard.md
deleted file mode 100644
index ab51d910a..000000000
--- a/prompts/finish/017-parity-03-earnings-leaderboard.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# parity 03: agents ranked by what they earned, on /leaderboard
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this repository and say "run this work order". Runnable after order 015 (per-agent earnings) has shipped; step 0 checks.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first, then [_context/parity-00-CONTEXT.md](_context/parity-00-CONTEXT.md). CLAUDE.md overrides everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option list, or an unexecuted plan. A judgment call goes in one line of the final report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real funds or any irreversible on-chain write, git push or a production deploy, committing content that names a crypto project other than $THREE, and destroying unrecoverable data. Where this order hits one, it says so, and you batch every such ask into ONE message after everything else is done.
-- Never name Competitor X in anything you commit. If a reference is unavoidable, write "Competitor X".
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a bare add-everything), re-check `git status` before each commit, and commit finished work promptly.
-- Before committing, run `npm run check:rules -- --paths <files you touched>`. It must exit 0.
-
-## Why this matters
-
-Competitor X's leaderboard ranks agents by what they earned and brings builders back to watch their rank. three.ws's `/leaderboard` (`pages/leaderboard.html` + `src/leaderboard.js`, data from `/api/sniper/leaderboard` via `getLeaderboard` in `api/_lib/trader-stats.js`) ranks trading agents only, by score, realized P&L, win rate or ROI. Nothing ranks agents by creator fees or service income. `/economy`'s "Agents earning" section ranks by rating and buyer count, not money.
-
-Also found on 2026-09-30: two launch counts disagree. `api/leaderboard/unified.js` and `api/cron/leaderboard-rollup.js` count launches from `agent_identities.meta->'token'->>'mint'`, which agent-wallet launches leave empty (as `src/avatar-page.js` itself warns), while `daily-match` and `pulse` use `pump_agent_mints`. The `launches` board undercounts.
-
-## Step 0: re-derive the current state
-
- ls prompts/finish/015-parity-01-creator-earnings.md 2>/dev/null && echo "015 still open: run it first"
- grep -rn "agent_coin_earnings\|/earnings" api/agents api/_lib --include=*.js | head
- sed -n 880,980p api/_lib/trader-stats.js
- grep -n "meta->'token'->>'mint'" api/leaderboard/unified.js api/cron/leaderboard-rollup.js
- grep -n "window\|sort" src/leaderboard.js | head -30
-
-If 015 has not shipped, stop here, run 015, and come back: this board has no data without it.
-
-## Tasks
-
-1. **An "Earned" board.** A new tab on `/leaderboard` (the page keeps its trading boards): agents ranked by earnings in the selected window (24h, 7d, 30d, all), where earnings are creator fees (015's snapshot) plus service income (x402 skill sales and hires: `agent_revenue_events`, `agent_hires`), each column shown separately with the total. Row: rank, agent name and portrait linking to `/agents/:id`, total in SOL with USD, the split, and the agent's coin if any. Rank movement versus the previous window when the data supports it.
-2. **API.** `GET /api/leaderboard/earnings?window=&limit=&offset=` with the same caching pattern as the sniper board (`public, max-age=10, s-maxage=20` or longer if the data refreshes slower), paginated, with a `method` string.
-3. **Fix the launch count** in `unified.js` and `leaderboard-rollup.js` to count from `pump_agent_mints` (plus `fixed_supply_launches`), with a test that fails on the old query.
-4. **Share and link.** The board's current window and tab live in the URL. Link the Earned tab from order 015's "Earned" card on agent pages ("#12 this week"). Add an OG image variant if `api/og-leaderboard.js` supports tabs.
-5. **Docs.** API reference entry, `STRUCTURE.md` row update, changelog entry.
-
-## Definition of done
-
-- [ ] `/leaderboard` has an Earned tab showing real agents with real figures for each window, browser-verified at 375, 768 and 1440 px, both themes, zero console errors, empty window state designed.
-- [ ] `GET /api/leaderboard/earnings` returns ranked rows whose totals equal the sum of their per-agent `/api/agents/:id/earnings` figures for the same window (a test or a scripted cross-check on real data).
-- [ ] The launches count fix has a failing-then-passing test.
-- [ ] `npm test` passes for touched suites; docs and changelog updated.
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Few agents have earned anything | Ship the board with what exists and a strong empty-window state ("be the first: launch a coin" linking to `/launch`). Never pad with test agents. |
-| Service income and creator fees are in different currencies | Convert both to SOL and USD at the price used for the window (`api/_lib/sol-price.js`) and state it in `method`. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house style: `type(scope): what changed and why a reader cares`).
-3. If every Definition of done line passes, delete this file in that same commit (`git rm prompts/finish/017-parity-03-earnings-leaderboard.md`) and append a dated entry to [_context/parity-PROGRESS.md](_context/parity-PROGRESS.md) with the commit SHAs. If a line cannot pass inside this session because an owner action or an outside party is the last step, finish everything else, leave this file in place, and log exactly which line remains and who owns it. Never delete this file on a partial.
-4. Final report, in this order: what step 0 measured; what changed (file list with commit SHAs); evidence for each Definition of done line; the single batched owner message, if the order has a gate; one-line judgment calls. No trailing questions.
diff --git a/prompts/finish/_context/parity-PROGRESS.md b/prompts/finish/_context/parity-PROGRESS.md
index dd9275745..6e4f506ed 100644
--- a/prompts/finish/_context/parity-PROGRESS.md
+++ b/prompts/finish/_context/parity-PROGRESS.md
@@ -52,3 +52,10 @@ Cross-session handoff for the `parity-` orders ([parity-00-CONTEXT.md](parity-00
- Shipped earlier, never closed out: `faedf00fb` (`data/experiments.json`, build-time validator `scripts/lib/experiments-index.mjs`, `/experiments` page and module, `docs/experiments.md` how-to, the two write-ups, footer, nav, start-here, pages.json, STRUCTURE row, changelog entries, tests). The close-out commit that carries this entry deletes the order file.
- Verified this session: a temporary entry missing `question` fails the validator ("missing required field"), removed afterwards; `tests/experiments-index.test.js` 14 passing; every SELECT in both appendices re-run read-only against production and reproduces the published figures exactly (788 / 454 / 744 / 208 agents, 2 launched, 3 coins in window, 0 token plans, 509 / 315 prior window, 90 mainnet coins; 1,296 closed trades, 212 winners, -540,179,418 lamports on 9,144,352,384 deployed, same exit-reason, retune and ladder splits). `/experiments` renders both cards and the empty filter state, and both write-ups show all six sections plus the appendix, at 375, 768 and 1440 px in dark and light with no horizontal overflow. `npm run audit:links` has 0 dangling routes; `npm run audit:docs` has one unrelated finding (`workers/cad-forge` has no README).
- Not verified: the dev server (`vite`) crashes on a broken symlink under `contracts/lib`, so the browser pass used a static file server; the only failing requests were `/i18n.js`, `/nav-tier-badge.js` and `/api/auth/me`, which that server does not serve.
+
+## 2026-10-09: order 017, agents ranked by earnings on /leaderboard (closed)
+
+- Shipped: `2be894e19` (launch counts from `pump_agent_mints` plus `fixed_supply_launches` in `unified.js` and `leaderboard-rollup.js` via `api/_lib/launch-counts.js`, PGlite test red on the old query; `GET /api/leaderboard/earnings`), `c703afead` (Earned tab, `src/leaderboard-earned.js`), earlier `3581568ff` (rank pill on the Earned card linking to `/leaderboard?tab=earned&window=7d`), and this close-out commit (STRUCTURE row, changelog entry, order file removed). API reference section was already in `1516d79c4` and later docs commits.
+- Cross-check on production data: for every ranked row in 24h (0 rows), 7d (1), 30d (9) and all (46), the row's `total` object equals `getAgentEarnings(...).total` for the same window, 0 mismatches. Browser: Earned tab at 375, 768 and 1440 px, dark and light, all four windows, no horizontal overflow, no console errors (only a Chromium WebGL driver warning from the page's 3D companion), empty-window state ("Put your agent on this board", launch and sell links) renders.
+- Judgment call: `api/og-leaderboard.js` renders the $THREE holder board only and has no tab concept, so no OG variant was added.
+- Seen: the creator-fee snapshot on production was 23h old at verification time (the board says so in its freshness note).