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(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.md
index 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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);
+ });
+});