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): 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.jsnew file mode 100644index 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.sqlnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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 });+});