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): snapshot per-coin creator-fee earnings for agent launches on a cron

nirholasdfb5c2d86975
diff --git a/api/_lib/creator-earnings-snapshot.js b/api/_lib/creator-earnings-snapshot.js
new file mode 100644
index 000000000..f0a173444
--- /dev/null
+++ b/api/_lib/creator-earnings-snapshot.js
@@ -0,0 +1,217 @@
+// @ts-check
+// The creator-fee earnings snapshot: walks every mainnet coin in
+// pump_agent_mints, resolves each coin's on-chain fee recipient, reads that
+// wallet's creator fees from pump.fun's index (plus its unclaimed vault balance
+// from the cluster), and stores the result in agent_coin_earnings and
+// creator_fee_buckets (migration 20260930121000_agent_coin_earnings.sql).
+//
+// Run by api/cron/creator-earnings-snapshot.js on Cloud Scheduler. Devnet coins
+// are excluded: devnet trades carry no real value and pump.fun does not index
+// them. When pump.fun or the RPC cannot answer, a coin keeps its last good
+// figures (refreshed_at stays at the last success) and the failure is recorded
+// in `error`; a coin that never had a good read is stored as 'unavailable'.
+
+import { sql } from './db.js';
+import { getConnection } from './pump.js';
+import {
+ resolveCoinCreators,
+ readCreatorFeeReport,
+ fetchCreatorFeeBuckets,
+} from './pump-creator-fees.js';
+
+const WSOL = 'So11111111111111111111111111111111111111112';
+const WALLET_CONCURRENCY = 4;
+
+/** @param {bigint | null | undefined} v */
+const big = (v) => (v == null ? null : v.toString());
+
+/**
+ * Map over `items` with at most `limit` in flight.
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T) => Promise<R>} fn
+ * @returns {Promise<R[]>}
+ */
+async function mapLimit(items, limit, fn) {
+ const out = new Array(items.length);
+ let next = 0;
+ const worker = async () => {
+ while (next < items.length) {
+ const i = next++;
+ out[i] = await fn(items[i]);
+ }
+ };
+ await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+ return out;
+}
+
+/**
+ * Record a coin that has no figure this run. An existing row keeps its last good
+ * figures and source; only the error and attempt time move.
+ */
+async function recordUnavailable(coin, { creator = null, walletCoins = 1, walletAgents = 1, reason }) {
+ await sql`
+ insert into agent_coin_earnings
+ (mint, network, agent_id, creator, wallet_coin_count, wallet_agent_count, source, error, attempted_at)
+ values
+ (${coin.mint}, 'mainnet', ${coin.agent_id}, ${creator}, ${walletCoins}, ${walletAgents}, 'unavailable', ${reason}, now())
+ on conflict (mint, network) do update set
+ agent_id = excluded.agent_id,
+ creator = coalesce(excluded.creator, agent_coin_earnings.creator),
+ wallet_coin_count = excluded.wallet_coin_count,
+ wallet_agent_count = excluded.wallet_agent_count,
+ error = excluded.error,
+ attempted_at = now()
+ `;
+}
+
+async function recordReport(coin, { creator, walletCoins, walletAgents, report }) {
+ await sql`
+ insert into agent_coin_earnings
+ (mint, network, agent_id, creator, earned_lamports, claimed_lamports, unclaimed_lamports,
+ wallet_coin_count, wallet_agent_count, source, error, refreshed_at, attempted_at)
+ values
+ (${coin.mint}, 'mainnet', ${coin.agent_id}, ${creator},
+ ${big(report.earned_lamports)}, ${big(report.claimed_lamports)}, ${big(report.unclaimed_lamports)},
+ ${walletCoins}, ${walletAgents}, 'pumpfun_creator_fees', null, now(), now())
+ on conflict (mint, network) do update set
+ agent_id = excluded.agent_id,
+ creator = excluded.creator,
+ earned_lamports = excluded.earned_lamports,
+ claimed_lamports = coalesce(excluded.claimed_lamports, agent_coin_earnings.claimed_lamports),
+ unclaimed_lamports = coalesce(excluded.unclaimed_lamports, agent_coin_earnings.unclaimed_lamports),
+ wallet_coin_count = excluded.wallet_coin_count,
+ wallet_agent_count = excluded.wallet_agent_count,
+ source = excluded.source,
+ error = null,
+ refreshed_at = now(),
+ attempted_at = now()
+ `;
+}
+
+async function storeBuckets(creator, interval, buckets) {
+ for (const b of buckets) {
+ await sql`
+ insert into creator_fee_buckets (creator, bucket_interval, bucket_start, fee_lamports, num_trades, refreshed_at)
+ values (${creator}, ${interval}, ${b.bucket_start}, ${big(b.fee_lamports)}, ${b.num_trades}, now())
+ on conflict (creator, bucket_interval, bucket_start) do update set
+ fee_lamports = excluded.fee_lamports,
+ num_trades = excluded.num_trades,
+ refreshed_at = now()
+ `;
+ }
+}
+
+/**
+ * Refresh one creator wallet: its fee report, its buckets, and every coin row
+ * that shares it.
+ */
+async function refreshWallet(connection, creator, coins) {
+ const walletCoins = coins.length;
+ const walletAgents = new Set(coins.map((c) => c.agent_id).filter(Boolean)).size || 1;
+ const [report, days, halfHours] = await Promise.all([
+ readCreatorFeeReport(connection, creator),
+ fetchCreatorFeeBuckets(creator, '1d'),
+ fetchCreatorFeeBuckets(creator, '30m'),
+ ]);
+ if (!report.ok) {
+ for (const coin of coins) {
+ await recordUnavailable(coin, { creator, walletCoins, walletAgents, reason: report.error });
+ }
+ return { creator, ok: false, error: report.error, coins: walletCoins };
+ }
+ for (const coin of coins) {
+ await recordReport(coin, { creator, walletCoins, walletAgents, report });
+ }
+ if (days.ok) await storeBuckets(creator, '1d', days.value);
+ if (halfHours.ok) await storeBuckets(creator, '30m', halfHours.value);
+ return {
+ creator,
+ ok: true,
+ coins: walletCoins,
+ earned_lamports: report.earned_lamports.toString(),
+ buckets_ok: days.ok && halfHours.ok,
+ };
+}
+
+/**
+ * One full snapshot pass over every mainnet coin.
+ * @returns {Promise<{ coins: number, wallets: number, refreshed: number, upstream_failed: number, skipped: Array<{ mint: string, reason: string }>, wallet_errors: Array<{ creator: string, error: string }> }>}
+ */
+export async function runCreatorEarningsSnapshot() {
+ const coins = await sql`
+ select mint, agent_id, quote_mint
+ from pump_agent_mints
+ where network = 'mainnet'
+ order by created_at asc
+ `;
+
+ // Rows for coins that are no longer on file are regenerable snapshot data.
+ await sql`
+ delete from agent_coin_earnings e
+ where e.network = 'mainnet'
+ and not exists (select 1 from pump_agent_mints p where p.mint = e.mint and p.network = 'mainnet')
+ `;
+
+ /** @type {Array<{ mint: string, reason: string }>} */
+ const skipped = [];
+ const priced = [];
+ for (const coin of coins) {
+ if (coin.quote_mint && coin.quote_mint !== WSOL) {
+ skipped.push({ mint: coin.mint, reason: 'quote is not SOL: pump.fun indexes creator fees in SOL only' });
+ await recordUnavailable(coin, { reason: 'quote_not_sol' });
+ } else {
+ priced.push(coin);
+ }
+ }
+
+ const connection = getConnection({ network: 'mainnet' });
+ /** @type {Map<string, { creator: string, graduated: boolean } | null>} */
+ let creators;
+ try {
+ creators = await resolveCoinCreators(connection, priced.map((c) => c.mint));
+ } catch (err) {
+ const reason = `rpc: ${String(/** @type {any} */ (err)?.message || err).slice(0, 160)}`;
+ for (const coin of priced) {
+ skipped.push({ mint: coin.mint, reason });
+ await recordUnavailable(coin, { reason });
+ }
+ return { coins: coins.length, wallets: 0, refreshed: 0, upstream_failed: 0, skipped, wallet_errors: [] };
+ }
+
+ /** @type {Map<string, any[]>} */
+ const byCreator = new Map();
+ for (const coin of priced) {
+ const resolved = creators.get(coin.mint);
+ if (!resolved) {
+ skipped.push({ mint: coin.mint, reason: 'no bonding curve on chain for this mint' });
+ await recordUnavailable(coin, { reason: 'curve_unreadable' });
+ continue;
+ }
+ const list = byCreator.get(resolved.creator) || [];
+ list.push(coin);
+ byCreator.set(resolved.creator, list);
+ }
+
+ const results = await mapLimit([...byCreator.entries()], WALLET_CONCURRENCY, ([creator, list]) =>
+ refreshWallet(connection, creator, list).catch((err) => ({
+ creator,
+ ok: false,
+ coins: list.length,
+ error: String(err?.message || err).slice(0, 200),
+ })),
+ );
+
+ const walletErrors = results.filter((r) => !r.ok).map((r) => ({ creator: r.creator, error: r.error }));
+ const refreshed = results.filter((r) => r.ok).reduce((n, r) => n + r.coins, 0);
+ const failedCoins = results.filter((r) => !r.ok).reduce((n, r) => n + r.coins, 0);
+ return {
+ coins: coins.length,
+ wallets: byCreator.size,
+ refreshed,
+ upstream_failed: failedCoins,
+ skipped,
+ wallet_errors: walletErrors,
+ };
+}
diff --git a/api/_lib/migrations/20260930121000_agent_coin_earnings.sql b/api/_lib/migrations/20260930121000_agent_coin_earnings.sql
new file mode 100644
index 000000000..a6699d342
--- /dev/null
+++ b/api/_lib/migrations/20260930121000_agent_coin_earnings.sql
@@ -0,0 +1,62 @@
+-- Migration: per-coin creator-fee earnings snapshot, and the bucketed history
+-- behind windowed earnings.
+-- Apply: node scripts/apply-migrations.mjs --apply --file 20260930121000_agent_coin_earnings.sql
+-- Idempotent.
+--
+-- Filled by api/cron/creator-earnings-snapshot.js, which walks every mainnet
+-- coin in pump_agent_mints, reads the coin's on-chain fee recipient (creator),
+-- then asks pump.fun's creator-fee index what that wallet has earned and reads
+-- its vaults on-chain for what is still unclaimed. Read by
+-- GET /api/agents/:id/earnings, GET /api/leaderboard/earnings and the coin page
+-- (/api/pump/launch-detail) so no page view has to hit pump.fun.
+--
+-- agent_coin_earnings: one row per coin. pump.fun reports creator fees per
+-- creator WALLET, so every coin of a wallet carries that wallet's figures;
+-- wallet_coin_count says how many coins on file share them and
+-- wallet_agent_count how many agents those coins belong to. A wallet counts
+-- toward an agent's total only when wallet_agent_count = 1, so a figure is
+-- never attributed to two agents. refreshed_at is the last SUCCESSFUL read:
+-- when pump.fun is down the row keeps its last good figures, records the error
+-- and bumps attempted_at only. source = 'unavailable' marks a coin with no
+-- figure yet (curve unreadable, non-SOL quote, upstream down on first read).
+--
+-- creator_fee_buckets: non-zero fee buckets per creator wallet from the same
+-- index, '30m' (about the last 50 hours, used for the 24h window) and '1d'
+-- (about the last 100 days, used for the 7d and 30d windows).
+
+begin;
+
+create table if not exists agent_coin_earnings (
+ mint text not null,
+ network text not null default 'mainnet',
+ agent_id uuid,
+ creator text,
+ earned_lamports bigint,
+ claimed_lamports bigint,
+ unclaimed_lamports bigint,
+ wallet_coin_count integer not null default 1,
+ wallet_agent_count integer not null default 1,
+ source text not null default 'unavailable'
+ check (source in ('pumpfun_creator_fees', 'unavailable')),
+ error text,
+ refreshed_at timestamptz,
+ attempted_at timestamptz not null default now(),
+ primary key (mint, network)
+);
+
+create index if not exists agent_coin_earnings_agent_idx on agent_coin_earnings (agent_id);
+create index if not exists agent_coin_earnings_creator_idx on agent_coin_earnings (creator);
+
+create table if not exists creator_fee_buckets (
+ creator text not null,
+ bucket_interval text not null check (bucket_interval in ('30m', '1d')),
+ bucket_start timestamptz not null,
+ fee_lamports bigint not null default 0,
+ num_trades integer not null default 0,
+ refreshed_at timestamptz not null default now(),
+ primary key (creator, bucket_interval, bucket_start)
+);
+
+create index if not exists creator_fee_buckets_window_idx on creator_fee_buckets (bucket_interval, bucket_start desc);
+
+commit;
diff --git a/api/_lib/pump-creator-fees.js b/api/_lib/pump-creator-fees.js
new file mode 100644
index 000000000..d3a143ed1
--- /dev/null
+++ b/api/_lib/pump-creator-fees.js
@@ -0,0 +1,202 @@
+// @ts-check
+// Creator-fee reads for pump.fun coins: the one client behind the coin page's
+// "Creator earned" figure (api/pump/launch-detail.js), the per-agent earnings
+// snapshot cron (api/cron/creator-earnings-snapshot.js) and anything else that
+// needs to know what a coin's creator has earned.
+//
+// Where the numbers come from:
+//
+// creator the coin's on-chain fee recipient, read from the bonding curve
+// (or the AMM pool once the coin graduated). pump.fun's coin
+// metadata `creator` field is NOT used: for a gasless launch it
+// names the sponsor that paid the transaction, not the wallet
+// that collects the fees.
+// earned pump.fun's creator-fee index, GET swap-api.pump.fun
+// /v1/creators/<wallet>/fees/total (lifetime, lamports) and
+// /v1/creators/<wallet>/fees?interval=1d|30m (bucketed). It is
+// keyed by creator WALLET, so one wallet that created several
+// coins reports one combined figure. The fee-sharing totals
+// endpoint the coin page used before answers 0 for every coin
+// that never set up a sharing config, which is every coin
+// three.ws has launched, so the page never showed a real figure.
+// unclaimed the creator vault balances read straight from the cluster
+// (pump bonding-curve vault plus the PumpSwap coin-creator vault),
+// the exact lamports a claim would sweep right now.
+// claimed earned minus unclaimed: every lamport the index says was
+// earned and the vault no longer holds was swept by a claim.
+//
+// Every pump.fun call runs behind the shared 'pumpfun:creator-fees' circuit
+// breaker, so a sick upstream costs one timeout per instance, not one per read.
+// An unhealthy answer (network error, timeout, non-2xx, unparseable body) throws
+// inside the breaker and resolves to a `{ ok: false }` result; a healthy answer
+// with no earnings is `{ ok: true }` with zero lamports. Callers keep their last
+// good value on `ok: false` and never invent a figure.
+
+import { PublicKey } from '@solana/web3.js';
+import { withBreaker } from './resilience.js';
+import { pumpFetchJson, PUMP_SWAP_BASE } from './pump-feed-fetch.js';
+
+export const CREATOR_FEES_BREAKER = 'pumpfun:creator-fees';
+const BREAKER_OPTS = { threshold: 3, halfOpenAfterMs: 30_000 };
+const TIMEOUT_MS = 6000;
+
+/** @param {unknown} v */
+function toLamports(v) {
+ if (v == null || v === '') return null;
+ try {
+ const n = BigInt(String(v).split('.')[0]);
+ return n < 0n ? 0n : n;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Run one pump.fun read behind the shared breaker. `fn` throws on an unhealthy
+ * upstream; the breaker turns that (or an open circuit) into `{ ok: false }`.
+ * @template T
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<{ ok: true, value: T } | { ok: false, error: string }>}
+ */
+async function guarded(fn) {
+ return withBreaker(
+ CREATOR_FEES_BREAKER,
+ async () => ({ ok: /** @type {const} */ (true), value: await fn() }),
+ {
+ ...BREAKER_OPTS,
+ fallback: (err) => ({
+ ok: /** @type {const} */ (false),
+ error: String(/** @type {any} */ (err)?.message || err || 'pump.fun unavailable').slice(0, 200),
+ }),
+ },
+ );
+}
+
+/**
+ * Lifetime creator fees earned by one wallet, in lamports, across every coin
+ * that wallet created.
+ * @param {string} wallet
+ */
+export async function fetchCreatorFeeTotal(wallet) {
+ return guarded(async () => {
+ const r = await pumpFetchJson(
+ `${PUMP_SWAP_BASE}/v1/creators/${encodeURIComponent(wallet)}/fees/total`,
+ { timeoutMs: TIMEOUT_MS },
+ );
+ if (!r.ok) throw new Error(`pump.fun creator fees ${r.status}`);
+ const lamports = toLamports(r.body?.totalFees);
+ if (lamports == null) throw new Error('pump.fun creator fees: no totalFees in response');
+ return lamports;
+ });
+}
+
+/**
+ * Bucketed creator fees for one wallet. pump.fun answers the most recent ~100
+ * buckets: `1d` spans about 100 days, `30m` about the last 50 hours. Zero
+ * buckets are dropped; they add nothing to a windowed sum.
+ * @param {string} wallet
+ * @param {'1d'|'30m'} interval
+ */
+export async function fetchCreatorFeeBuckets(wallet, interval) {
+ return guarded(async () => {
+ const r = await pumpFetchJson(
+ `${PUMP_SWAP_BASE}/v1/creators/${encodeURIComponent(wallet)}/fees?interval=${interval}`,
+ { timeoutMs: TIMEOUT_MS },
+ );
+ if (!r.ok) throw new Error(`pump.fun creator fee buckets ${r.status}`);
+ if (!Array.isArray(r.body)) throw new Error('pump.fun creator fee buckets: not an array');
+ const out = [];
+ for (const b of r.body) {
+ const fee = toLamports(b?.creatorFee);
+ const at = Date.parse(b?.bucket);
+ if (fee == null || !Number.isFinite(at) || fee === 0n) continue;
+ out.push({
+ bucket_start: new Date(at).toISOString(),
+ fee_lamports: fee,
+ num_trades: Number.isFinite(Number(b?.numTrades)) ? Number(b.numTrades) : 0,
+ });
+ }
+ return out;
+ });
+}
+
+/**
+ * The on-chain fee recipient of each mint. Bonding curves are read in one
+ * batched RPC call per 100 mints; a graduated coin's recipient comes from its
+ * canonical PumpSwap pool. A mint whose curve cannot be read maps to null.
+ *
+ * @param {import('@solana/web3.js').Connection} connection
+ * @param {string[]} mints
+ * @returns {Promise<Map<string, { creator: string, graduated: boolean } | null>>}
+ */
+export async function resolveCoinCreators(connection, mints) {
+ const [{ PumpSdk, bondingCurvePda, canonicalPumpPoolPda }, { OnlinePumpAmmSdk }] = await Promise.all([
+ import('@pump-fun/pump-sdk'),
+ import('@pump-fun/pump-swap-sdk'),
+ ]);
+ const offline = new PumpSdk();
+ /** @type {Map<string, { creator: string, graduated: boolean } | null>} */
+ const out = new Map();
+ for (let i = 0; i < mints.length; i += 100) {
+ const chunk = mints.slice(i, i + 100);
+ const infos = await connection.getMultipleAccountsInfo(chunk.map((m) => bondingCurvePda(new PublicKey(m))));
+ chunk.forEach((mint, j) => {
+ const info = infos[j];
+ const curve = info ? offline.decodeBondingCurveNullable(info) : null;
+ out.set(mint, curve ? { creator: curve.creator.toBase58(), graduated: curve.complete === true } : null);
+ });
+ }
+ const amm = new OnlinePumpAmmSdk(connection);
+ for (const [mint, row] of out) {
+ if (!row?.graduated) continue;
+ const pool = await amm.fetchPool(canonicalPumpPoolPda(new PublicKey(mint))).catch(() => null);
+ if (pool?.coinCreator) row.creator = pool.coinCreator.toBase58();
+ }
+ return out;
+}
+
+/**
+ * Lamports sitting unclaimed in a creator's vaults right now (pump bonding-curve
+ * vault plus the PumpSwap coin-creator vault), above rent. Null when the cluster
+ * could not be read.
+ * @param {import('@solana/web3.js').Connection} connection
+ * @param {string} wallet
+ * @returns {Promise<bigint | null>}
+ */
+export async function readUnclaimedLamports(connection, wallet) {
+ try {
+ const { OnlinePumpSdk } = await import('@pump-fun/pump-sdk');
+ const bn = await new OnlinePumpSdk(connection).getCreatorVaultBalanceBothPrograms(new PublicKey(wallet));
+ return BigInt(bn.toString());
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * One wallet's full creator-fee report: lifetime total, unclaimed, derived
+ * claimed. `ok: false` when pump.fun could not answer (the caller keeps its last
+ * good figure). `unclaimed_lamports` is null when the cluster read failed; the
+ * report is still good, claimed is then unknown.
+ *
+ * @param {import('@solana/web3.js').Connection} connection
+ * @param {string} wallet
+ */
+export async function readCreatorFeeReport(connection, wallet) {
+ const [total, unclaimed] = await Promise.all([
+ fetchCreatorFeeTotal(wallet),
+ readUnclaimedLamports(connection, wallet),
+ ]);
+ if (!total.ok) return { ok: false, error: total.error };
+ const earned = total.value;
+ // The index can lag a fresh trade by a few seconds while the vault is live, so
+ // the vault can briefly exceed the indexed total. Earned is never reported
+ // below what is provably sitting in the vault.
+ const earnedLamports = unclaimed != null && unclaimed > earned ? unclaimed : earned;
+ return {
+ ok: true,
+ earned_lamports: earnedLamports,
+ unclaimed_lamports: unclaimed,
+ claimed_lamports: unclaimed == null ? null : earnedLamports - unclaimed,
+ };
+}
diff --git a/api/cron/creator-earnings-snapshot.js b/api/cron/creator-earnings-snapshot.js
new file mode 100644
index 000000000..1a90117b5
--- /dev/null
+++ b/api/cron/creator-earnings-snapshot.js
@@ -0,0 +1,22 @@
+// @ts-check
+// GET/POST /api/cron/creator-earnings-snapshot: refresh what every agent coin's
+// creator has earned in pump.fun creator fees (every 30 minutes, Cloud
+// Scheduler). The work lives in api/_lib/creator-earnings-snapshot.js; this is
+// only the authenticated trigger.
+//
+// Response: { ok, coins, wallets, refreshed, upstream_failed, skipped[], wallet_errors[] }.
+// `skipped` names every coin that got no figure this run and why, so a coin is
+// never silently missing from the earnings surfaces.
+//
+// Auth: CRON_SECRET Bearer (same gate as every cron endpoint).
+
+import { json, method, wrapCron } from '../_lib/http.js';
+import { requireCron } from '../_lib/cron-auth.js';
+import { runCreatorEarningsSnapshot } from '../_lib/creator-earnings-snapshot.js';
+
+export default wrapCron(async (req, res) => {
+ if (!method(req, res, ['GET', 'POST'])) return;
+ if (!requireCron(req, res)) return;
+ const out = await runCreatorEarningsSnapshot();
+ return json(res, 200, { ok: true, ...out });
+});