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
feat(earnings): explain zero-earning coins on the Earned card, list the MCP earnings resource, add tests
nirholas9eb5bffcf6d4
diff --git a/docs/mcp.md b/docs/mcp.mdindex 3d3afc8c3..339b10390 100644--- a/docs/mcp.md+++ b/docs/mcp.md@@ -956,6 +956,7 @@ Clients that show tools but not resources get the same data from the `read_resou| `three://agents/{agentId}/orders` | mcp, mcp-agent | Open programmable orders | `agents:read` || `three://agents/{agentId}/dca` | mcp, mcp-agent | DCA strategies with their latest execution | `agents:read` || `three://agents/{agentId}/intents` | mcp, mcp-agent | Standing wallet intents: trigger, action, limits, last result | `agents:read` |+| `three://agents/{agentId}/earnings` | mcp, mcp-agent | Creator fees from the agent's pump.fun coins (earned, claimed, unclaimed, per coin), recorded claim transactions, x402 skill sales and hires, earnings-leaderboard rank, and a `method` line; same data as `GET /api/agents/:id/earnings` | public for a public agent; owner only for a private one || `three://wallets` | mcp, mcp-agent | Every agent wallet you own with SOL, USD value and freeze state, plus a total | `wallet:read` or `agents:read` || `three://launches` | mcp, mcp-agent | Every token your agents launched through three.ws | `agents:read` || `three://marketplace` | mcp, mcp-agent, mcp-bazaar | Paid agent skills with prices and free trials, agent services with track records, and your trials when signed in | public |diff --git a/src/shared/agent-earnings-card.js b/src/shared/agent-earnings-card.jsindex 5cf9753a8..a0aa7f293 100644--- a/src/shared/agent-earnings-card.js+++ b/src/shared/agent-earnings-card.js@@ -159,13 +159,24 @@ function claimRow(c) {}function footer(d) {- const updated = d.refreshed_at ? `Updated ${esc(relTime(d.refreshed_at))}` : 'Not refreshed yet';+ const updated = d.refreshed_at ? `Updated ${esc(relTime(d.refreshed_at))}` : '';return `<div class="ern-foot${d.stale ? ' stale' : ''}">- <span>${d.stale ? 'Figures may be out of date. ' : ''}${updated}</span>+ ${updated ? `<span>${d.stale ? 'Figures may be out of date. ' : ''}${updated}</span>` : ''}<details class="ern-how"><summary>How it's calculated</summary><p>${esc(d.method)}</p></details></div>`;}+function subline(zero, coins, service) {+ if (!zero) return `Lifetime creator fees from its coins${service.usd ? ' plus service income' : ''}.`;+ if (coins.length && coins.every((c) => c.status === 'other_wallet')) {+ return 'None counted for this agent: its coins pay creator fees to a wallet that is not its own, listed below.';+ }+ if (coins.length && coins.every((c) => c.status === 'not_reported')) {+ return 'pump.fun has not reported creator fees for its coins yet.';+ }+ return 'Nothing earned yet. Creator fees accrue with every trade of this agent’s coin.';+}+function render(d) {const lifetime = d.lifetime_creator_fees || {};const service = d.service_income || {};@@ -208,11 +219,7 @@ function render(d) {${totalUsd != null ? `<span class="ern-usd">${esc(fmtUsd(totalUsd))}</span>` : ''}${rank}</div>- <p class="ern-sub">${- zero- ? 'Nothing earned yet. Creator fees accrue with every trade of this agent’s coin.'- : 'Lifetime creator fees from its coins' + (service.usd ? ' plus service income' : '') + '.'- }</p>+ <p class="ern-sub">${esc(subline(zero, coins, service))}</p><div class="ern-stats">${stats.map(([k, v, s]) =>diff --git a/tests/agent-earnings.test.js b/tests/agent-earnings.test.jsnew file mode 100644index 000000000..e1dd8defb--- /dev/null+++ b/tests/agent-earnings.test.js@@ -0,0 +1,101 @@+// api/_lib/agent-earnings.js: the pure parts of the earnings read model that+// both GET /api/agents/:id/earnings and GET /api/leaderboard/earnings rely on.+// The window ranges decide which fee buckets and service rows count, and+// shapeTotals is the one place SOL and USD are derived, so the two endpoints+// can only agree if these are right.++import { describe, it, expect, vi } from 'vitest';++vi.mock('../api/_lib/db.js', () => ({ sql: vi.fn(async () => []) }));+vi.mock('../api/_lib/sol-price.js', () => ({ solPriceUsd: vi.fn(async () => 100) }));+vi.mock('../api/_lib/r2.js', () => ({ publicUrl: (k) => `https://cdn.example/${k}` }));++const { windowRange, normalizeWindow, shapeTotals, earningsMethod, EARNINGS_WINDOWS } = await import(+ '../api/_lib/agent-earnings.js'+);++const NOW = Date.UTC(2026, 8, 30, 14, 30); // 2026-09-30 14:30 UTC+const iso = (d) => d.toISOString();++const totals = (over = {}) => ({+ creator_lamports: 0n,+ lifetime_lamports: 0n,+ claimed_lamports: 0n,+ unclaimed_lamports: 0n,+ refreshed_at: null,+ skill_sales_usd: 0,+ skill_sales_count: 0,+ hires_usd: 0,+ hires_count: 0,+ ...over,+});++describe('normalizeWindow', () => {+ it('keeps the four supported windows and falls back to all', () => {+ for (const w of EARNINGS_WINDOWS) expect(normalizeWindow(w)).toBe(w);+ expect(normalizeWindow('1y')).toBe('all');+ expect(normalizeWindow(undefined)).toBe('all');+ });+});++describe('windowRange', () => {+ it('has no range for all-time', () => {+ expect(windowRange('all', 0, NOW)).toBeNull();+ });++ it('uses the last 24 hours of 30-minute buckets, and the 24 before that', () => {+ const cur = windowRange('24h', 0, NOW);+ expect(cur.interval).toBe('30m');+ expect(iso(cur.end)).toBe('2026-09-30T14:30:00.000Z');+ expect(iso(cur.start)).toBe('2026-09-29T14:30:00.000Z');+ const prev = windowRange('24h', 1, NOW);+ expect(iso(prev.end)).toBe(iso(cur.start));+ });++ it('uses whole UTC days including today for 7d and 30d', () => {+ const week = windowRange('7d', 0, NOW);+ expect(week.interval).toBe('1d');+ expect(iso(week.start)).toBe('2026-09-24T00:00:00.000Z');+ expect(iso(week.end)).toBe('2026-10-01T00:00:00.000Z');+ const prevWeek = windowRange('7d', 1, NOW);+ expect(iso(prevWeek.end)).toBe(iso(week.start));+ expect(iso(prevWeek.start)).toBe('2026-09-17T00:00:00.000Z');+ const month = windowRange('30d', 0, NOW);+ expect(iso(month.start)).toBe('2026-09-01T00:00:00.000Z');+ });+});++describe('shapeTotals', () => {+ it('converts creator fees and service income at one price and sums them', () => {+ const out = shapeTotals(+ totals({ creator_lamports: 1_500_000_000n, skill_sales_usd: 20, skill_sales_count: 2, hires_usd: 30, hires_count: 1 }),+ 100,+ );+ expect(out.creator_fees).toEqual({ lamports: '1500000000', sol: 1.5, usd: 150 });+ expect(out.service_income).toMatchObject({ usd: 50, sol: 0.5, skill_sales_count: 2, hires_count: 1 });+ expect(out.total).toEqual({ sol: 2, usd: 200 });+ });++ it('never invents a USD figure when the SOL price is unknown', () => {+ const out = shapeTotals(totals({ creator_lamports: 1_000_000_000n }), 0);+ expect(out.creator_fees.usd).toBeNull();+ expect(out.service_income.sol).toBeNull();+ expect(out.total).toEqual({ sol: 1, usd: null });+ });++ it('reports a clean zero for an agent that earned nothing', () => {+ const out = shapeTotals(totals(), 100);+ expect(out.total).toEqual({ sol: 0, usd: 0 });+ expect(out.creator_fees.lamports).toBe('0');+ });+});++describe('earningsMethod', () => {+ it('names the source, the attribution rule and the window', () => {+ expect(earningsMethod('all')).toMatch(/creator-fee index/);+ expect(earningsMethod('all')).toMatch(/own custodial wallet/);+ expect(earningsMethod('7d')).toMatch(/last 7 UTC days/);+ expect(earningsMethod('24h')).toMatch(/30-minute buckets/);+ expect(earningsMethod('all')).toMatch(/Devnet coins are excluded/);+ });+});diff --git a/tests/pump-creator-fees.test.js b/tests/pump-creator-fees.test.jsnew file mode 100644index 000000000..74874a5f9--- /dev/null+++ b/tests/pump-creator-fees.test.js@@ -0,0 +1,66 @@+// api/_lib/pump-creator-fees.js: the pump.fun creator-fee reads behind the+// earnings snapshot and the coin page. Payload shapes are the ones+// swap-api.pump.fun returns for /v1/creators/<wallet>/fees/total and+// /v1/creators/<wallet>/fees?interval=..., captured 2026-09-30.++import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';++const { fetchCreatorFeeTotal, fetchCreatorFeeBuckets } = await import('../api/_lib/pump-creator-fees.js');+const { _resetBreakers } = await import('../api/_lib/resilience.js');++const WALLET = 'THREEsynthetic11111111111111111111111111111';+const originalFetch = global.fetch;+const reply = (status, body) => ({ ok: status >= 200 && status < 300, status, headers: new Headers(), json: async () => body });++beforeEach(() => _resetBreakers());+afterEach(() => {+ global.fetch = originalFetch;+});++describe('fetchCreatorFeeTotal', () => {+ it('reads lifetime lamports from totalFees', async () => {+ global.fetch = vi.fn(async (url) => {+ expect(String(url)).toContain(`/v1/creators/${WALLET}/fees/total`);+ return reply(200, { totalFees: '73148608', totalFeesSOL: '0.073148608' });+ });+ const r = await fetchCreatorFeeTotal(WALLET);+ expect(r).toEqual({ ok: true, value: 73148608n });+ });++ it('treats a wallet with no fees as a healthy zero, not a failure', async () => {+ global.fetch = vi.fn(async () => reply(200, { totalFees: '0', totalFeesSOL: '0' }));+ expect(await fetchCreatorFeeTotal(WALLET)).toEqual({ ok: true, value: 0n });+ });++ it('reports an upstream failure so the caller keeps its last good figure', async () => {+ global.fetch = vi.fn(async () => reply(404, { statusCode: 404 }));+ const r = await fetchCreatorFeeTotal(WALLET);+ expect(r.ok).toBe(false);+ expect(r.error).toMatch(/404/);+ });+});++describe('fetchCreatorFeeBuckets', () => {+ it('keeps only non-zero buckets, as lamports with ISO starts', async () => {+ global.fetch = vi.fn(async (url) => {+ expect(String(url)).toContain('interval=1d');+ return reply(200, [+ { bucket: '2026-07-25T00:00:00.000Z', creatorFee: '0', creatorFeeSOL: '0', numTrades: 0 },+ { bucket: '2026-07-26T00:00:00.000Z', creatorFee: '73094972', creatorFeeSOL: '0.073094972', numTrades: 65 },+ { bucket: '2026-07-27T00:00:00.000Z', creatorFee: '53636', creatorFeeSOL: '0.000053636', numTrades: 1 },+ ]);+ });+ const r = await fetchCreatorFeeBuckets(WALLET, '1d');+ expect(r.ok).toBe(true);+ expect(r.value).toEqual([+ { bucket_start: '2026-07-26T00:00:00.000Z', fee_lamports: 73094972n, num_trades: 65 },+ { bucket_start: '2026-07-27T00:00:00.000Z', fee_lamports: 53636n, num_trades: 1 },+ ]);+ });++ it('fails on a body that is not a bucket list', async () => {+ global.fetch = vi.fn(async () => reply(200, { statusCode: 400, message: 'interval must be one of' }));+ const r = await fetchCreatorFeeBuckets(WALLET, '30m');+ expect(r.ok).toBe(false);+ });+});