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(payouts): add the /creator/payouts page to register a signed payout wallet, see held reasons and export distributions

nirholas3146189b5a5d
diff --git a/STRUCTURE.md b/STRUCTURE.md
index dd19a976c..43b367a5e 100644
--- a/STRUCTURE.md
+++ b/STRUCTURE.md
@@ -90,6 +90,7 @@ packages, a generated standalone GitHub mirror). See
| 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) |
| Creator-fee payouts | Core [api/_lib/creator-payouts-core.js](api/_lib/creator-payouts-core.js), store and sender [api/_lib/creator-payouts.js](api/_lib/creator-payouts.js), endpoint [api/creator-payouts.js](api/creator-payouts.js), crons [creator-payout-distribute.js](api/cron/creator-payout-distribute.js) + [creator-payout-reconcile.js](api/cron/creator-payout-reconcile.js), page [pages/creator-payouts.html](pages/creator-payouts.html) `→ /creator/payouts` + [src/creator-payouts-page.js](src/creator-payouts-page.js), migration `20261023190000_creator_payouts.sql` | Live; sending off until `CREATOR_PAYOUTS_LIVE=true` | The creator's share of every claimed pump.fun fee, sent to a wallet the owner registers by signature plus step-up (48 hour cooldown on change, session-only). One distribution row per claim, held with a named reason (no wallet, cooldown, below minimum, paused), reconciled against the chain. Docs: [docs/creator-payouts.md](docs/creator-payouts.md). Tests: [tests/creator-payouts.test.js](tests/creator-payouts.test.js) |
+| Creator-fee payouts | Core [api/_lib/creator-payouts-core.js](api/_lib/creator-payouts-core.js), store and sender [api/_lib/creator-payouts.js](api/_lib/creator-payouts.js), endpoint [api/creator-payouts.js](api/creator-payouts.js), crons [creator-payout-distribute.js](api/cron/creator-payout-distribute.js) + [creator-payout-reconcile.js](api/cron/creator-payout-reconcile.js), page [pages/creator-payouts.html](pages/creator-payouts.html) `→ /creator/payouts` + [src/creator-payouts-page.js](src/creator-payouts-page.js), migration `20261023190000_creator_payouts.sql` | Live; sending off until `CREATOR_PAYOUTS_LIVE=true` | The creator's share of every claimed pump.fun fee, sent to a wallet the owner registers by signature plus step-up (48 hour cooldown on change, session-only). One distribution row per claim, held with a named reason (no wallet, cooldown, below minimum, paused), reconciled against the chain. Docs: [docs/creator-payouts.md](docs/creator-payouts.md). Tests: [tests/creator-payouts.test.js](tests/creator-payouts.test.js) |
| Funded launch intents | Pairs [api/pump/pairs.js](api/pump/pairs.js) + [api/_lib/pump-launch-pairs.js](api/_lib/pump-launch-pairs.js), intents [api/pump/launch-intents.js](api/pump/launch-intents.js) + [api/_lib/pump-funded-launch.js](api/_lib/pump-funded-launch.js), page [pages/launch-intent.html](pages/launch-intent.html) `→ /launch/intents` + [src/launch/launch-intent-page.js](src/launch/launch-intent-page.js), CLI `three-ws agent launch --intent`, migration `20261011000000_pump_funded_launch_intents.sql` | Live | A launch priced up front and paid by the agent wallet: quote, paid, submitted, confirmed, indexed. Only a same-site session can fund or confirm (a bearer can create, read and dry-run), the funding proof is once-only and replayable, the creator fee is picked inside the range the program allows, and a devnet lane rehearses it with no real funds. Docs: [docs/launch-intents.md](docs/launch-intents.md). Tests: [tests/pump-funded-launch.test.js](tests/pump-funded-launch.test.js) |
| 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) |
| Agent persona template gallery (create wizard) | Catalog [data/agent-templates.json](data/agent-templates.json), module [src/create-agent-templates.js](src/create-agent-templates.js), dialog + strip in [pages/create-agent.html](pages/create-agent.html) `→ /create-agent`, wiring `wireTemplates` in [src/create-agent.js](src/create-agent.js) | Live | "Start from a template" in step 1 of the wizard: 26 Solana-first finance personas (whale watching, wallet safety, yield, launch vetting, tax planning) in a searchable, tag-filterable grid with a preview pane. One click prefills persona, greeting, category and skills (name, description and tags only fill what is empty), with Undo and a jump to the Personality step. Rewritten from the owner's defi-agents repo; every persona branded for another project dropped, tools are real MCP tool names, no addresses, no third-party coins. The new `finance` category is also offered by the marketplace filter, the agent editor and the spec generator. Docs [docs/create-agent.md](docs/create-agent.md). Tests: [tests/agent-templates.test.js](tests/agent-templates.test.js), [tests/create-agent-templates.test.js](tests/create-agent-templates.test.js), [tests/e2e/create-agent-templates.spec.js](tests/e2e/create-agent-templates.spec.js) |
diff --git a/data/changelog.json b/data/changelog.json
index dd9732f6a..fb347af85 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-23",
+ "title": "Creator-fee payouts: register a wallet and see every distribution",
+ "summary": "Your share of each claimed creator fee now has a record and a destination. Register a payout wallet by signing with it and confirming with a step-up (a change waits 48 hours), then follow what is sent, pending or held and why on the new payouts page, and export every distribution as CSV. Sending stays off until payouts are switched on, and shares are recorded and held until then.",
+ "tags": ["feature"],
+ "link": "/creator/payouts"
+ },
{
"date": "2026-10-23",
"title": "Holder concentration, funder seeding and v1 launch signals on every coin",
diff --git a/data/pages.json b/data/pages.json
index 8f77b445d..46b8ede8b 100644
--- a/data/pages.json
+++ b/data/pages.json
@@ -1845,6 +1845,15 @@
"added": "2026-10-23",
"indexable": false
},
+ {
+ "path": "/creator/payouts",
+ "title": "Creator Payouts",
+ "description": "Register the wallet your agent's creator-fee share is paid to, see what is sent, pending or held and why, and export every distribution. Fee collection, distribution and reconciliation cadences are read live.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-10-23",
+ "indexable": false
+ },
{
"path": "/launch/robinhood",
"title": "Launch on Robinhood Chain",
@@ -7164,6 +7173,14 @@
"changefreq": "monthly",
"added": "2026-10-23"
},
+ {
+ "path": "/docs/creator-payouts",
+ "title": "Docs · Creator payouts",
+ "description": "How a claimed creator fee becomes a payout: the four cron stages, the signed and step-up payout wallet with a 48 hour change cooldown, the four hold reasons, and the API.",
+ "priority": 0.6,
+ "changefreq": "monthly",
+ "added": "2026-10-23"
+ },
{
"path": "/docs/pill-mascot",
"title": "Docs · Rigging the pump.fun pill mascot",
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 18f7e0e1e..4dc1015c2 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -4244,6 +4244,19 @@ Where an agent's creator-fee share is sent, and the record of every distribution
Rules, hold reasons and configuration: [creator-payouts.md](creator-payouts.md).
+### Creator payouts
+
+Where an agent's creator-fee share is sent, and the record of every distribution.
+
+| Method and path | Auth | Purpose |
+| --- | --- | --- |
+| `GET /api/creator-payouts?info=1` | none | Stage cadences and the per-$100 flow. |
+| `GET /api/creator-payouts?agent=<id>` | owner session | Payout wallet, pending change, totals, held reasons, recent distributions. |
+| `GET /api/creator-payouts?agent=<id>&format=csv` | owner session | Every distribution as CSV. |
+| `POST /api/creator-payouts` | owner session | `challenge`, `register` (needs a step-up grant) or `cancel`. |
+
+Rules, hold reasons and configuration: [creator-payouts.md](creator-payouts.md).
+
### Whales
Whale / large-buy detection across pump.fun — **facts only**: which wallets