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
// @ts-check
// Agent earnings read model: the single computation behind
// GET /api/agents/:id/earnings and GET /api/leaderboard/earnings, so an agent's
// own page and its leaderboard row can never disagree.
//
// An agent earns two ways, and both are counted here:
//
// creator fees pump.fun creator fees on the coins it launched, from the
// agent_coin_earnings snapshot (api/_lib/creator-earnings-snapshot.js).
// pump.fun reports these per creator WALLET, so a wallet's
// figure counts toward an agent only when that wallet is the
// agent's own custodial wallet (agent_identities.meta.solana_address)
// and no other agent's coin on file shares it. A coin whose
// fees go to any other wallet (an owner's connected wallet, a
// launch sponsor) is listed but not counted: that wallet's
// total can include coins launched anywhere. Each coin also
// carries a second, independent figure summed from that
// coin's own pump.fun distribution timeline
// (pump-creator-fees.js's fetchCoinEarnings), surfaced per
// coin as `distributed` with a `reconciliation` delta
// against the wallet-level figure.
// service income x402 skill sales (agent_revenue_events, USDC net of the
// platform fee) and hires by other agents (agent_hires,
// completed). USDC is valued 1:1 in USD.
// invoice income agent commerce invoices paid on Solana mainnet
// (agent_commerce_invoices, api/_lib/agent-commerce/), in
// USDC, SOL or $THREE, valued in USD at the moment the
// watcher verified the payment. Offer sales are invoices too.
//
// Windows: 'all' uses the lifetime creator-fee totals; '24h' sums the 30-minute
// fee buckets of the last 24 hours; '7d' and '30d' sum UTC-day buckets (today
// plus the previous 6 or 29 days). Service income uses the same time range.
// Everything is converted at one SOL/USD price per call (solPriceUsd()).
import { sql } from './db.js';
import { solPriceUsd } from './sol-price.js';
import { SOLANA_USDC_MINT } from '../payments/_config.js';
import { cdnUrl } from './r2.js';
import { getAgentPayouts } from './creator-payouts.js';
// A portrait is decoration: a misconfigured URL resolver degrades it to null
// instead of failing the board. Routed through /cdn/ (not a raw publicUrl())
// so a thumbnail here gets the same signed-read-then-public-fallback
// protection every other API-facing thumbnail now gets.
function safeR2Url(key) {
if (!key) return null;
try {
return cdnUrl(key);
} catch {
return null;
}
}
export const EARNINGS_WINDOWS = /** @type {const} */ (['24h', '7d', '30d', 'all']);
const DAY_MS = 86_400_000;
/** @param {unknown} w */
export function normalizeWindow(w) {
return EARNINGS_WINDOWS.includes(/** @type {any} */ (w)) ? /** @type {'24h'|'7d'|'30d'|'all'} */ (w) : 'all';
}
/**
* The time range a window covers, `back` windows ago (0 = current, 1 = the one
* before it, used for rank movement). 'all' has no range.
* @param {'24h'|'7d'|'30d'|'all'} window
* @param {number} [back]
* @param {number} [now]
* @returns {{ interval: '30m'|'1d', start: Date, end: Date } | null}
*/
export function windowRange(window, back = 0, now = Date.now()) {
if (window === 'all') return null;
if (window === '24h') {
const end = new Date(now - back * DAY_MS);
return { interval: '30m', start: new Date(end.getTime() - DAY_MS), end };
}
const days = window === '7d' ? 7 : 30;
const todayStart = Math.floor(now / DAY_MS) * DAY_MS;
const end = new Date(todayStart + DAY_MS - back * days * DAY_MS);
return { interval: '1d', start: new Date(end.getTime() - days * DAY_MS), end };
}
export function earningsMethod(window) {
const range =
window === 'all'
? 'lifetime totals'
: window === '24h'
? 'the last 24 hours, summed from 30-minute buckets'
: `the last ${window === '7d' ? 7 : 30} UTC days including today, summed from daily buckets`;
return (
`Creator fees come from pump.fun's creator-fee index for each coin's on-chain fee recipient ` +
`(read from the bonding curve or AMM pool), refreshed every 30 minutes into a snapshot; ` +
`unclaimed is the creator vault balance read on-chain, claimed is earned minus unclaimed. ` +
`pump.fun reports fees per creator wallet, so a wallet counts toward an agent only when it is ` +
`that agent's own custodial wallet; coins paying any other wallet are listed but not counted. ` +
`Each coin also carries a second, independent figure (distributed_sol) summed from that coin's own ` +
`pump.fun distribution timeline, which is the only source that can say which coin actually paid a ` +
`wallet; the gap between the two sources is shown as a reconciliation delta, never hidden. ` +
`Service income is x402 skill sales (net, USDC) plus completed hires by other agents, valued 1:1 in USD, ` +
`plus invoices paid on Solana mainnet, valued in USD when the payment was verified. ` +
`Figures cover ${range}. SOL and USD are converted at one live SOL/USD price. Devnet coins are excluded.`
);
}
const lamportsToSol = (v) => (v == null ? null : Number(BigInt(v)) / 1e9);
const round = (n, dp) => (n == null || !Number.isFinite(n) ? null : Math.round(n * 10 ** dp) / 10 ** dp);
/**
* Per-agent creator-fee lamports for a window, plus lifetime claimed/unclaimed.
* Only counted wallets (see header). `agentId` narrows to one agent; `publicOnly`
* keeps the leaderboard to public agents.
*/
async function creatorFeeRows(window, { agentId = null, publicOnly = false, back = 0 } = {}) {
const range = windowRange(window, back);
const agentFilter = agentId ? sql`and e.agent_id = ${agentId}` : sql``;
const publicFilter = publicOnly ? sql`and ai.is_public = true` : sql``;
const windowed = range
? sql`
left join (
select creator, sum(fee_lamports) as fee
from creator_fee_buckets
where bucket_interval = ${range.interval}
and bucket_start >= ${range.start.toISOString()}
and bucket_start < ${range.end.toISOString()}
group by creator
) b on b.creator = w.creator`
: sql``;
const value = range ? sql`coalesce(b.fee, 0)` : sql`coalesce(w.earned_lamports, 0)`;
return sql`
with w as (
select distinct on (e.creator)
e.creator, e.agent_id, e.earned_lamports, e.claimed_lamports, e.unclaimed_lamports, e.refreshed_at
from agent_coin_earnings e
join agent_identities ai on ai.id = e.agent_id and ai.deleted_at is null
where e.network = 'mainnet'
and e.source = 'pumpfun_creator_fees'
and e.wallet_agent_count = 1
and e.creator = ai.meta->>'solana_address'
${agentFilter}
${publicFilter}
order by e.creator, e.refreshed_at desc nulls last
)
select w.agent_id,
sum(${value})::text as lamports,
sum(coalesce(w.earned_lamports, 0))::text as lifetime_lamports,
sum(coalesce(w.claimed_lamports, 0))::text as claimed_lamports,
sum(coalesce(w.unclaimed_lamports, 0))::text as unclaimed_lamports,
min(w.refreshed_at) as refreshed_at
from w
${windowed}
group by w.agent_id
`;
}
/**
* Lifetime creator-fee lamports for a set of public agents, keyed by agent id,
* counted by the same attribution rule as getAgentEarnings (an agent's own
* custodial wallet, never shared). Agents with no counted fees are absent.
* @param {string[]} agentIds
* @returns {Promise<Map<string, { lamports: bigint, refreshed_at: any }>>}
*/
export async function creatorFeesByAgent(agentIds) {
const wanted = new Set(agentIds);
const out = new Map();
if (!wanted.size) return out;
for (const r of await creatorFeeRows('all', { publicOnly: true })) {
if (wanted.has(r.agent_id)) out.set(r.agent_id, { lamports: BigInt(r.lifetime_lamports || 0), refreshed_at: r.refreshed_at });
}
return out;
}
/** Skill sales (USDC net), completed hires and paid invoices, per agent, for a window. */
async function serviceRows(window, { agentId = null, publicOnly = false, back = 0 } = {}) {
const range = windowRange(window, back);
const salesRange = range
? sql`and r.created_at >= ${range.start.toISOString()} and r.created_at < ${range.end.toISOString()}`
: sql``;
const hireRange = range
? sql`and coalesce(h.completed_at, h.created_at) >= ${range.start.toISOString()}
and coalesce(h.completed_at, h.created_at) < ${range.end.toISOString()}`
: sql``;
const invoiceRange = range
? sql`and i.paid_at >= ${range.start.toISOString()} and i.paid_at < ${range.end.toISOString()}`
: sql``;
const salesAgent = agentId ? sql`and r.agent_id = ${agentId}` : sql``;
const hireAgent = agentId ? sql`and h.provider_agent_id = ${agentId}` : sql``;
const invoiceAgent = agentId ? sql`and i.agent_id = ${agentId}` : sql``;
const publicFilter = publicOnly ? sql`and ai.is_public = true` : sql``;
const [sales, hires, invoices] = await Promise.all([
sql`
select r.agent_id, sum(r.net_amount)::text as atomics, count(*)::int as n
from agent_revenue_events r
join agent_identities ai on ai.id = r.agent_id and ai.deleted_at is null
where r.currency_mint = ${SOLANA_USDC_MINT} ${salesRange} ${salesAgent} ${publicFilter}
group by r.agent_id
`,
sql`
select h.provider_agent_id as agent_id, coalesce(sum(h.usd), 0)::float8 as usd, count(*)::int as n
from agent_hires h
join agent_identities ai on ai.id = h.provider_agent_id and ai.deleted_at is null
where h.status = 'completed' ${hireRange} ${hireAgent} ${publicFilter}
group by h.provider_agent_id
`,
sql`
select i.agent_id, coalesce(sum(i.paid_usd), 0)::float8 as usd, count(*)::int as n
from agent_commerce_invoices i
join agent_identities ai on ai.id = i.agent_id and ai.deleted_at is null
where i.status = 'paid' and i.network = 'mainnet' and i.paid_usd is not null
${invoiceRange} ${invoiceAgent} ${publicFilter}
group by i.agent_id
`,
]);
return { sales, hires, invoices };
}
/**
* Totals per agent for one window, as plain numbers, keyed by agent id.
* @returns {Promise<Map<string, { creator_lamports: bigint, lifetime_lamports: bigint, claimed_lamports: bigint, unclaimed_lamports: bigint, refreshed_at: any, skill_sales_usd: number, skill_sales_count: number, hires_usd: number, hires_count: number, invoices_usd: number, invoices_count: number }>>}
*/
async function totalsByAgent(window, opts) {
const [fees, service] = await Promise.all([creatorFeeRows(window, opts), serviceRows(window, opts)]);
const out = new Map();
const get = (id) => {
let row = out.get(id);
if (!row) {
row = {
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,
invoices_usd: 0,
invoices_count: 0,
};
out.set(id, row);
}
return row;
};
for (const f of fees) {
const row = get(f.agent_id);
row.creator_lamports = BigInt(f.lamports || 0);
row.lifetime_lamports = BigInt(f.lifetime_lamports || 0);
row.claimed_lamports = BigInt(f.claimed_lamports || 0);
row.unclaimed_lamports = BigInt(f.unclaimed_lamports || 0);
row.refreshed_at = f.refreshed_at;
}
for (const s of service.sales) {
const row = get(s.agent_id);
row.skill_sales_usd = Number(BigInt(s.atomics || 0)) / 1e6;
row.skill_sales_count = s.n;
}
for (const h of service.hires) {
const row = get(h.agent_id);
row.hires_usd = Number(h.usd) || 0;
row.hires_count = h.n;
}
for (const i of service.invoices) {
const row = get(i.agent_id);
row.invoices_usd = Number(i.usd) || 0;
row.invoices_count = i.n;
}
return out;
}
/**
* Shape one agent's totals into the public figures. Exported so both endpoints
* shape identically.
*/
export function shapeTotals(t, price) {
const creatorSol = Number(t.creator_lamports) / 1e9;
const serviceUsd = serviceIncomeUsd(t);
const serviceSol = price > 0 ? serviceUsd / price : null;
const totalSol = creatorSol + (serviceSol ?? 0);
return {
creator_fees: {
lamports: t.creator_lamports.toString(),
sol: round(creatorSol, 9),
usd: price > 0 ? round(creatorSol * price, 2) : null,
},
service_income: {
skill_sales_usd: round(t.skill_sales_usd, 2),
skill_sales_count: t.skill_sales_count,
hires_usd: round(t.hires_usd, 2),
hires_count: t.hires_count,
invoices_usd: round(t.invoices_usd || 0, 2),
invoices_count: t.invoices_count || 0,
usd: round(serviceUsd, 2),
sol: serviceSol == null ? null : round(serviceSol, 9),
},
total: {
sol: round(totalSol, 9),
usd: price > 0 ? round(totalSol * price, 2) : serviceUsd > 0 ? round(serviceUsd, 2) : null,
},
};
}
/** Skill sales, hires and paid invoices, in USD. */
export const serviceIncomeUsd = (t) => t.skill_sales_usd + t.hires_usd + (t.invoices_usd || 0);
const rankKey = (t, price) => Number(t.creator_lamports) / 1e9 + (price > 0 ? serviceIncomeUsd(t) / price : 0);
/** Ranked public agents for a window (only agents that earned something). */
async function rankedAgents(window, price, back = 0) {
const totals = await totalsByAgent(window, { publicOnly: true, back });
return [...totals.entries()]
.map(([agentId, t]) => ({ agentId, t, key: rankKey(t, price) }))
.filter((r) => r.key > 0)
.sort((a, b) => b.key - a.key || String(a.agentId).localeCompare(String(b.agentId)));
}
/**
* One agent's earnings: windowed totals, lifetime creator-fee figures, the
* per-coin breakdown, and its recorded claims.
* @param {{ id: string, name: string, is_public: boolean, solana_address: string | null }} agent
* @param {{ window?: string }} [opts]
*/
export async function getAgentEarnings(agent, { window: rawWindow = 'all' } = {}) {
const window = normalizeWindow(rawWindow);
const [price, totals, lifetimeTotals, coins, devnet, claims, payouts] = await Promise.all([
solPriceUsd(),
totalsByAgent(window, { agentId: agent.id }),
window === 'all' ? null : totalsByAgent('all', { agentId: agent.id }),
sql`
select pam.mint, pam.name, pam.symbol, pam.created_at,
e.creator, e.earned_lamports::text, e.claimed_lamports::text, e.unclaimed_lamports::text,
e.wallet_coin_count, e.wallet_agent_count, e.source, e.error, e.refreshed_at, e.attempted_at,
e.coin_earned_lamports::text, e.coin_distributions, e.coin_earnings_source,
e.reconciliation_delta_lamports::text, e.reconciliation_pct
from pump_agent_mints pam
left join agent_coin_earnings e on e.mint = pam.mint and e.network = pam.network
where pam.agent_id = ${agent.id} and pam.network = 'mainnet'
order by pam.created_at desc
`,
sql`select count(*)::int as n from pump_agent_mints where agent_id = ${agent.id} and network = 'devnet'`,
recentClaims(agent.id),
// The payout ledger is an additive block: a failure here must not hide earnings.
getAgentPayouts(agent.id).catch(() => null),
]);
const t = totals.get(agent.id) || emptyTotals();
const life = (lifetimeTotals ? lifetimeTotals.get(agent.id) : totals.get(agent.id)) || emptyTotals();
const shaped = shapeTotals(t, price);
const lifeSol = (v) => round(Number(v) / 1e9, 9);
const usd = (sol) => (price > 0 && sol != null ? round(sol * price, 2) : null);
const coinRows = coins.map((c) => ({
...shapeCoin(c, agent.solana_address, price),
payout: payouts?.per_coin?.[c.mint] || { sent_sol: 0, pending_sol: 0, held_sol: 0 },
}));
const refreshedTimes = coinRows.map((c) => c.refreshed_at).filter(Boolean).map((d) => new Date(d).getTime());
const refreshedAt = refreshedTimes.length ? new Date(Math.min(...refreshedTimes)).toISOString() : null;
let rank = null;
if (agent.is_public) rank = await agentRank(agent.id, window === 'all' ? '7d' : window, price);
return {
agent: { id: agent.id, name: agent.name, url: `/agents/${agent.id}` },
network: 'mainnet',
window,
sol_price_usd: price > 0 ? price : null,
has_coins: coins.length > 0,
devnet_coins_excluded: devnet[0]?.n || 0,
...shaped,
lifetime_creator_fees: {
earned_sol: lifeSol(life.lifetime_lamports),
earned_usd: usd(lifeSol(life.lifetime_lamports)),
claimed_sol: lifeSol(life.claimed_lamports),
claimed_usd: usd(lifeSol(life.claimed_lamports)),
unclaimed_sol: lifeSol(life.unclaimed_lamports),
unclaimed_usd: usd(lifeSol(life.unclaimed_lamports)),
},
coins: coinRows,
claims,
// Public read model: the registered wallet and totals only. A staged wallet
// change and the cooldown stay on the owner's /creator/payouts page.
payouts: payouts && {
...payouts,
wallet: { ...payouts.wallet, pending: null },
recent_distributions: payouts.recent_distributions.map(({ payout_wallet, ...rest }) => rest),
total_earned_sol: lifeSol(life.lifetime_lamports),
total_claimed_sol: lifeSol(life.claimed_lamports),
// Earned and claimed are the lifetime creator-fee figures; sent, pending and
// held are the creator's share of recorded claims (claim minus the buyback earmark).
basis: 'Earned and claimed are lifetime creator fees. Sent, pending and held are your share of each recorded claim after the buyback earmark.',
},
rank,
refreshed_at: refreshedAt,
stale: refreshedAt ? Date.now() - new Date(refreshedAt).getTime() > 2 * 3_600_000 : false,
method: earningsMethod(window),
};
}
function emptyTotals() {
return {
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,
invoices_usd: 0,
invoices_count: 0,
};
}
function shapeCoin(c, agentWallet, price) {
const reported = c.source === 'pumpfun_creator_fees' && c.earned_lamports != null;
const counted = reported && c.creator === agentWallet && Number(c.wallet_agent_count) === 1;
const earnedSol = reported ? lamportsToSol(c.earned_lamports) : null;
const distributedSol = c.coin_earnings_source === 'timeline' && c.coin_earned_lamports != null
? lamportsToSol(c.coin_earned_lamports)
: null;
const deltaSol = c.reconciliation_delta_lamports != null ? lamportsToSol(c.reconciliation_delta_lamports) : null;
return {
mint: c.mint,
name: c.name,
symbol: c.symbol,
url: `/launches/${c.mint}`,
launched_at: c.created_at,
creator: c.creator || null,
status: !reported ? 'not_reported' : counted ? 'counted' : 'other_wallet',
earned_sol: earnedSol,
earned_usd: price > 0 && earnedSol != null ? round(earnedSol * price, 2) : null,
claimed_sol: reported ? lamportsToSol(c.claimed_lamports) : null,
unclaimed_sol: reported ? lamportsToSol(c.unclaimed_lamports) : null,
wallet_coin_count: c.wallet_coin_count ?? null,
refreshed_at: c.refreshed_at || null,
error: c.error || null,
distributed: {
sol: distributedSol,
usd: price > 0 && distributedSol != null ? round(distributedSol * price, 2) : null,
distributions: c.coin_distributions ?? null,
},
reconciliation: deltaSol == null ? null : {
delta_sol: round(deltaSol, 9),
delta_pct: c.reconciliation_pct == null ? null : round(Number(c.reconciliation_pct), 2),
},
};
}
/**
* Recorded creator-fee claims for an agent: autonomous claims (launcher_claims)
* and owner-triggered claims (agent_actions 'pumpfun.collect_creator_fee').
* A claim sweeps every coin of the wallet at once, so `mint` names the coin the
* claim was started from.
*/
async function recentClaims(agentId) {
const [launcher, studio] = await Promise.all([
sql`
select claim_sig as signature, claimed_lamports::text as lamports, mint, created_at
from launcher_claims
where agent_id = ${agentId} and network = 'mainnet' and claim_sig is not null
order by created_at desc limit 20
`,
sql`
select payload->>'signature' as signature, payload->>'lamports' as lamports,
payload->>'mint' as mint, created_at
from agent_actions
where agent_id = ${agentId} and type = 'pumpfun.collect_creator_fee'
and coalesce(payload->>'network', 'mainnet') = 'mainnet'
and payload->>'signature' is not null
order by created_at desc limit 20
`,
]);
const rows = [
...launcher.map((r) => ({ ...r, source: 'autonomous' })),
...studio.map((r) => ({ ...r, source: 'owner' })),
];
rows.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
return rows.slice(0, 20).map((r) => ({
signature: r.signature,
sol: r.lamports != null && /^\d+$/.test(String(r.lamports)) ? lamportsToSol(r.lamports) : null,
mint: r.mint,
at: r.created_at,
source: r.source,
explorer: `https://solscan.io/tx/${r.signature}`,
}));
}
/** Rank of one public agent on the earnings board for a window, or null. */
async function agentRank(agentId, window, price) {
const ranked = await rankedAgents(window, price);
const i = ranked.findIndex((r) => r.agentId === agentId);
return i < 0 ? null : { window, position: i + 1, of: ranked.length, url: `/leaderboard?tab=earned&window=${window}` };
}
/**
* The earnings leaderboard for a window, paginated. Each row's figures come
* from shapeTotals over the same totals getAgentEarnings uses.
*/
export async function listEarningsLeaderboard({ window: rawWindow = '7d', limit = 25, offset = 0 } = {}) {
const window = normalizeWindow(rawWindow);
const price = await solPriceUsd();
const [ranked, previous] = await Promise.all([
rankedAgents(window, price),
window === 'all' ? null : rankedAgents(window, price, 1),
]);
const prevPos = new Map((previous || []).map((r, i) => [r.agentId, i + 1]));
const page = ranked.slice(offset, offset + limit);
const ids = page.map((r) => r.agentId);
const [profiles, coins] = ids.length
? await Promise.all([
sql`
select ai.id, ai.name, ai.meta->>'solana_address' as solana_address,
a.thumbnail_key, a.visibility
from agent_identities ai
left join avatars a on a.id = ai.avatar_id and a.deleted_at is null
where ai.id = any(${ids})
`,
sql`
select distinct on (pam.agent_id) pam.agent_id, pam.mint, pam.symbol, pam.name
from pump_agent_mints pam
left join agent_coin_earnings e on e.mint = pam.mint and e.network = pam.network
where pam.agent_id = any(${ids}) and pam.network = 'mainnet'
order by pam.agent_id, e.earned_lamports desc nulls last, pam.created_at desc
`,
])
: [[], []];
const byId = new Map(profiles.map((p) => [p.id, p]));
const coinById = new Map(coins.map((c) => [c.agent_id, c]));
const refreshed = ranked.map((r) => r.t.refreshed_at).filter(Boolean).map((d) => new Date(d).getTime());
return {
window,
sol_price_usd: price > 0 ? price : null,
total: ranked.length,
limit,
offset,
refreshed_at: refreshed.length ? new Date(Math.min(...refreshed)).toISOString() : null,
method: earningsMethod(window),
rows: page.map((r, i) => {
const p = byId.get(r.agentId) || {};
const coin = coinById.get(r.agentId) || null;
const rank = offset + i + 1;
const prev = prevPos.get(r.agentId) ?? null;
return {
rank,
previous_rank: prev,
movement: window === 'all' ? null : prev == null ? 'new' : prev - rank,
agent: {
id: r.agentId,
name: p.name || 'Agent',
url: `/agents/${r.agentId}`,
thumbnail_url: p.visibility === 'public' || p.visibility === 'unlisted' ? safeR2Url(p.thumbnail_key) : null,
},
coin: coin ? { mint: coin.mint, symbol: coin.symbol, name: coin.name, url: `/launches/${coin.mint}` } : null,
...shapeTotals(r.t, price),
};
}),
};
}