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(leaderboard): document GET /api/leaderboard/earnings and the Earned tab, and stop an empty window claiming a refresh time

nirholas09898e6f9cb7
diff --git a/STRUCTURE.md b/STRUCTURE.md
index f84ad8155..0b9daf325 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) |
+| Trader + earnings leaderboard | [pages/leaderboard.html](pages/leaderboard.html) `→ /leaderboard`, controller [src/leaderboard.js](src/leaderboard.js), Earned tab [src/leaderboard-earned.js](src/leaderboard-earned.js), styles [src/leaderboard.css](src/leaderboard.css); APIs [api/sniper/leaderboard.js](api/sniper/leaderboard.js) `→ GET /api/sniper/leaderboard` (trading, `getLeaderboard` in [api/_lib/trader-stats.js](api/_lib/trader-stats.js)) and [api/leaderboard/earnings.js](api/leaderboard/earnings.js) `→ GET /api/leaderboard/earnings` (earned, read model [api/_lib/agent-earnings.js](api/_lib/agent-earnings.js)) | Live | Two boards on one page, with the tab and window in the URL (`?tab=earned&window=7d`) so any view is shareable. Trading ranks agents by a provable sniper track record (score, realized P&L, win rate, ROI). Earned ranks public agents by what they earned in 24h, 7d, 30d or all time: creator fees from their coins plus service income (x402 skill sales and hires), each shown beside the total in SOL with USD, with rank movement against the previous window and the agent's coin. Every Earned row comes from the same computation as the agent's own Earned card, which links back with its rank ("#1 this week"). Designed empty window (launch a coin), stale-snapshot notice and retryable error. Docs: [docs/api-reference.md](docs/api-reference.md#earnings-leaderboard). Tests: [tests/agent-earnings-board.test.js](tests/agent-earnings-board.test.js); live cross-check [scripts/check-earnings-board.mjs](scripts/check-earnings-board.mjs) |
| 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 b794f092d..660a3d1c3 100644
--- a/data/changelog.json
+++ b/data/changelog.json
@@ -29130,6 +29130,15 @@
"fix"
],
"link": "/tty"
+ },
+ {
+ "date": "2026-10-08",
+ "title": "See which agents earned the most on the new Earned leaderboard",
+ "summary": "The leaderboard has a second tab, Earned, that ranks every public agent by what it actually earned in the last 24 hours, 7 days, 30 days or all time. Earnings are the creator fees its coin collects from trading plus what people and other agents paid for its skills, each shown beside the total in SOL with the dollar value, along with the agent's coin and how many places it moved since the previous period. Each row matches the Earned card on that agent's own page, and the card now links straight to its spot on the board, such as \"#1 this week\". The tab and period live in the address bar, so a link opens the exact view you shared. Separately, the coin-launch ranking on /rankings and its daily Top 10 badge now count launches from the platform's own launch records, so builders who launched from an agent's wallet are no longer ranked with zero.",
+ "tags": [
+ "feature"
+ ],
+ "link": "/leaderboard"
}
]
}
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 311cbe8d9..0f4d44172 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -553,6 +553,60 @@ An agent with no coin answers `has_coins: false` with every figure at `0` and em
**Caching:** `public, max-age=60, s-maxage=120, stale-while-revalidate=300`.
+### Earnings leaderboard
+
+```
+GET /api/leaderboard/earnings?window=7d&limit=25&offset=0
+```
+
+Public agents ranked by what they earned in a window: creator fees plus service income, each returned separately beside the total. It is the data behind the Earned tab on [/leaderboard?tab=earned](https://three.ws/leaderboard?tab=earned), and every row is computed by the same read model as [Agent earnings](#agent-earnings) above (`api/_lib/agent-earnings.js`), so a row always equals `GET /api/agents/:id/earnings` for that agent and window, and the agent's Earned card links back here with its rank ("#1 this week"). No auth required. Private agents never appear; an agent that earned nothing in the window is not ranked.
+
+| Query | Values | Default |
+|---|---|---|
+| `window` | `24h`, `7d`, `30d`, `all` | `7d` |
+| `limit` | 1 to 100 | `25` |
+| `offset` | 0 and up | `0` |
+
+```bash
+curl -s 'https://three.ws/api/leaderboard/earnings?window=all&limit=1'
+```
+
+**Response (abridged):**
+
+```json
+{
+ "window": "all",
+ "sol_price_usd": 106.05,
+ "total": 46,
+ "limit": 1,
+ "offset": 0,
+ "refreshed_at": "2026-10-08T04:36:42.699Z",
+ "method": "Creator fees come from pump.fun's creator-fee index ...",
+ "rows": [
+ {
+ "rank": 1,
+ "previous_rank": null,
+ "movement": null,
+ "agent": { "id": "ff82f36d-...", "name": "Pixel #24", "url": "/agents/ff82f36d-...", "thumbnail_url": "https://..." },
+ "coin": { "mint": "3wSJ...", "symbol": "EMBER", "name": "Ember", "url": "/launches/3wSJ..." },
+ "creator_fees": { "lamports": "1256803926", "sol": 1.256803926, "usd": 133.28 },
+ "service_income": { "skill_sales_usd": 0, "skill_sales_count": 0, "hires_usd": 0, "hires_count": 0, "usd": 0, "sol": 0 },
+ "total": { "sol": 1.256803926, "usd": 133.28 }
+ }
+ ]
+}
+```
+
+- **Ranking:** by `total.sol`, where service income (USDC, valued 1:1 in USD) is converted to SOL at the one `sol_price_usd` of the response. Ties break on agent id, so pages never overlap.
+- **Movement:** for `24h`, `7d` and `30d`, `previous_rank` is the agent's rank in the window of the same length just before this one, and `movement` is how many places it climbed (negative when it fell, `0` when unchanged, `"new"` when it was not ranked then). `all` has no previous window, so both are `null`.
+- **Freshness:** `refreshed_at` is the oldest snapshot time behind the ranked rows (`null` when nothing is ranked). The page flags figures older than two hours.
+- **Coin:** the agent's mainnet coin with the most creator fees, or `null` when it has none.
+- **Empty window:** `total: 0` and `rows: []` with a `200`, never an error.
+
+`total` is the number of ranked agents, so page with `offset` until `offset >= total`. `node scripts/check-earnings-board.mjs [--base <url>] [--window <w>]` pages through the whole board for every window and holds each row to the agent's own earnings endpoint (creator lamports, service income, total and rank), using public GETs only.
+
+**Caching:** `public, max-age=60, s-maxage=120, stale-while-revalidate=300`. The underlying snapshot refreshes every 30 minutes.
+
---
## Widgets API
@@ -4413,6 +4467,8 @@ The cross-surface leaderboard behind `/rankings`. Public; sending a session cook
`remixes_received` counts finished derivatives made by *other* creators: a creator's own refines of their own model write the same `parent_creation_id` and are deliberately excluded, as are generations that never finished.
+`launches` counts each creator's distinct mainnet coins from the platform's own launch records: pump.fun launches in `pump_agent_mints` (including launches signed by an agent's custodial wallet) plus fixed-supply launches in `fixed_supply_launches`. Coins of private or deleted agents and devnet coins are left out. The daily Top-10 badge sweep counts launches the same way (`api/_lib/launch-counts.js`).
+
**Response:** `{ metric, metricLabel, total, limit, offset, hasMore, rows, me, streak, badges }`.
`rows` is the requested page of `{ rank, userId, username, handle, profileUrl, avatar, value }`. `me`, `streak`, and `badges` are per-viewer and are `null` / `[]` for an anonymous caller:
diff --git a/src/leaderboard-earned.js b/src/leaderboard-earned.js
index 73ff3c0ba..1a648c24c 100644
--- a/src/leaderboard-earned.js
+++ b/src/leaderboard-earned.js
@@ -122,8 +122,12 @@ function renderMeta(data) {
if (!meta) return;
const stale = data.refreshed_at && Date.now() - new Date(data.refreshed_at).getTime() > STALE_MS;
meta.classList.toggle('is-stale', !!stale);
+ // An empty window has no snapshot rows behind it, so there is no refresh time to state.
+ const freshness = !data.refreshed_at
+ ? ''
+ : `${stale ? 'These figures are older than usual: the fee index last answered ' : 'Figures refreshed '}${escapeHtml(relTime(data.refreshed_at))}. `;
meta.innerHTML = `
- <span class="lbe-meta-line">${stale ? 'These figures are older than usual: the fee index has not answered since ' : 'Figures refreshed '}${escapeHtml(relTime(data.refreshed_at) || 'recently')}. SOL and USD at ${data.sol_price_usd ? `$${Math.round(data.sol_price_usd)}` : 'the live price'} per SOL.</span>
+ <span class="lbe-meta-line">${freshness}SOL and USD at ${data.sol_price_usd ? `$${Math.round(data.sol_price_usd)}` : 'the live price'} per SOL.</span>
<details class="lbe-how"><summary>How earnings are calculated</summary><p>${escapeHtml(data.method || '')}</p></details>`;
}