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
/**
* /api/pump/launch-detail — the single server-side aggregator behind the rich
* /launches/<mint> coin page.
*
* GET /api/pump/launch-detail?mint=<mint>&network=mainnet|devnet
*
* One round-trip fuses every DB-side truth we hold about a coin so the page
* paints a complete picture before any client-side enrichment:
*
* · registry — is this a three.ws agent launch? (pump_agent_mints) +
* the agent identity and avatar behind it
* · economics — confirmed agent payments, unique payers, buyback burns
* (pump_agent_payments / pump_buyback_runs)
* · intel — the Coin Intelligence Engine's first-seconds verdict
* (pump_coin_intel) — quality / bundle / organic / risk flags
* · outcome — graduated / rugged / ATH multiple (pump_coin_outcomes)
* · trader — the launching agent's verifiable track record
* (trader-stats truth layer, same numbers as the leaderboard)
*
* Live market price, the price chart, the trade tape, holder cohorts and the
* community feed are streamed in by the client from their own dedicated
* endpoints — this aggregator stays a fast, cacheable database read.
*
* Public + IP rate-limited. Every number traces to an on-chain transaction or a
* row we persisted from one; nothing here is synthesized. A coin that isn't a
* three.ws launch still resolves (found:false) with whatever intel we observed,
* so the page works for any pump.fun mint, not only ours.
*/
import { cors, json, method, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { sql } from '../_lib/db.js';
import { publicUrl as r2PublicUrl } from '../_lib/r2.js';
import { normalizeGatewayURL } from '../../src/ipfs.js';
import { getTraderStats } from '../_lib/trader-stats.js';
import { getConnection } from '../_lib/pump.js';
import { solPriceUsd } from '../_lib/sol-price.js';
import { resolveCoinCreators, readCreatorFeeReport, fetchCoinEarnings } from '../_lib/pump-creator-fees.js';
const MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const lamportsToSol = (v) => (v == null ? null : Number(BigInt(v)) / 1e9);
const num = (v) => (v == null ? null : Number(v));
// The agent avatar is non-critical enrichment. If the R2 public-URL resolver
// throws (e.g. a misconfigured S3_PUBLIC_DOMAIN), degrade the avatar to null
// rather than 500 the entire coin page over a decorative thumbnail.
function safeR2Url(key) {
if (!key) return null;
try {
return r2PublicUrl(key);
} catch {
return null;
}
}
// Creator fees: what the coin's creator wallet has earned from pump.fun's
// creator-fee program. Read from the agent_coin_earnings snapshot the
// creator-earnings cron refreshes every 30 minutes, so a page view never waits
// on pump.fun. A coin the snapshot has not reached yet (launched minutes ago)
// falls back to one live read through the shared client in
// api/_lib/pump-creator-fees.js, which runs behind the 'pumpfun:creator-fees'
// circuit breaker and resolves the fee recipient on-chain.
//
// pump.fun indexes these fees per creator wallet: `wallet_coin_count` > 1 means
// the figure is shared by that many coins from the same wallet. `distributed`
// is this coin's OWN share, summed from its own distribution timeline (the
// only source that can say which coin actually paid the wallet); `reconciled`
// is the gap between that per-coin sum and the wallet-level claimed figure,
// surfaced rather than hidden.
async function creatorFeesFor(mint, network, price) {
if (network !== 'mainnet') return null;
const toUsd = (sol) => (price > 0 && sol != null ? Math.round(sol * price * 100) / 100 : null);
const [snap] = await sql`
select creator, earned_lamports::text, claimed_lamports::text, unclaimed_lamports::text,
wallet_coin_count, source, refreshed_at,
coin_earned_lamports::text, coin_distributions, coin_earnings_source,
reconciliation_delta_lamports::text, reconciliation_pct
from agent_coin_earnings
where mint = ${mint} and network = 'mainnet'
`;
if (snap?.source === 'pumpfun_creator_fees' && snap.earned_lamports != null) {
const earned = lamportsToSol(snap.earned_lamports);
const distributedSol = snap.coin_earnings_source === 'timeline' && snap.coin_earned_lamports != null
? lamportsToSol(snap.coin_earned_lamports)
: null;
const deltaSol = snap.reconciliation_delta_lamports != null ? lamportsToSol(snap.reconciliation_delta_lamports) : null;
return {
creator: snap.creator,
earned_sol: earned,
earned_usd: toUsd(earned),
claimed_sol: lamportsToSol(snap.claimed_lamports),
unclaimed_sol: lamportsToSol(snap.unclaimed_lamports),
wallet_coin_count: snap.wallet_coin_count,
refreshed_at: snap.refreshed_at,
source: 'snapshot',
distributed: {
sol: distributedSol,
usd: toUsd(distributedSol),
distributions: snap.coin_distributions ?? null,
},
reconciliation: deltaSol == null ? null : {
delta_sol: deltaSol,
delta_pct: snap.reconciliation_pct == null ? null : Number(snap.reconciliation_pct),
},
};
}
const connection = getConnection({ network: 'mainnet' });
const creators = await resolveCoinCreators(connection, [mint]).catch(() => null);
const creator = creators?.get(mint)?.creator;
if (!creator) return null;
const [report, timeline] = await Promise.all([
readCreatorFeeReport(connection, creator, { mints: [mint] }),
fetchCoinEarnings(mint, creator),
]);
if (!report.ok) return null;
const earned = Number(report.earned_lamports) / 1e9;
const distributedSol = timeline.ok ? Number(timeline.value.lamports) / 1e9 : null;
return {
creator,
earned_sol: earned,
earned_usd: toUsd(earned),
claimed_sol: report.claimed_lamports == null ? null : Number(report.claimed_lamports) / 1e9,
unclaimed_sol: report.unclaimed_lamports == null ? null : Number(report.unclaimed_lamports) / 1e9,
wallet_coin_count: null,
refreshed_at: new Date().toISOString(),
source: 'live',
distributed: {
sol: distributedSol,
usd: toUsd(distributedSol),
distributions: timeline.ok ? timeline.value.distributions : null,
},
reconciliation: null,
};
}
// Short-lived per-instance cache — the page is read far more than coins are
// observed, and every underlying query is cheap-but-not-free.
const CACHE = new Map();
const TTL_MS = 15_000;
function shapeIntel(r) {
if (!r) return null;
return {
symbol: r.symbol,
name: r.name,
creator: r.creator,
image_uri: r.image_uri,
description: r.description,
socials: { twitter: r.twitter, telegram: r.telegram, website: r.website },
created_at: r.created_at,
first_seen_at: r.first_seen_at,
observation_seconds: r.observation_seconds,
quality_score: r.quality_score,
bundle_score: num(r.bundle_score),
organic_score: num(r.organic_score),
snipe_ratio: num(r.snipe_ratio),
concentration_top10: num(r.concentration_top10),
fresh_wallet_ratio: num(r.fresh_wallet_ratio),
bubblemap_connectivity: num(r.bubblemap_connectivity),
risk_flags: r.risk_flags || [],
category: r.category,
tags: r.tags || [],
narrative: r.narrative,
classify_confidence: num(r.classify_confidence),
classify_source: r.classify_source,
dev_buy_sol: lamportsToSol(r.dev_buy_lamports),
dev_sold: r.dev_sold,
buy_count: r.buy_count,
sell_count: r.sell_count,
buy_volume_sol: lamportsToSol(r.buy_volume_lamports),
sell_volume_sol: lamportsToSol(r.sell_volume_lamports),
unique_buyers: r.unique_buyers,
unique_sellers: r.unique_sellers,
largest_buy_sol: lamportsToSol(r.largest_buy_lamports),
};
}
function shapeOutcome(o) {
if (!o) return null;
return {
outcome: o.outcome,
graduated: o.graduated,
rugged: o.rugged,
ath_multiple: num(o.ath_multiple),
ath_market_cap_usd: num(o.ath_market_cap_usd),
last_market_cap_usd: num(o.last_market_cap_usd),
labeled_at: o.labeled_at,
};
}
async function buildDetail(mint, network) {
// Registry row (+ agent identity + avatar) — the authoritative "is this a
// three.ws launch, and whose agent is it" answer.
const [reg] = await sql`
select pam.id, pam.mint, pam.network, pam.name, pam.symbol, pam.buyback_bps,
pam.agent_authority, pam.metadata_uri, pam.quote_mint,
pam.sharing_config, pam.created_at,
ai.id as agent_id, ai.name as agent_name, ai.description as agent_description,
ai.is_public as agent_public,
ai.meta->>'solana_address' as agent_solana_address,
ai.meta->>'solana_vanity_prefix' as agent_solana_vanity_prefix,
ai.meta->>'solana_vanity_suffix' as agent_solana_vanity_suffix,
a.thumbnail_key as avatar_thumbnail_key, a.storage_key as avatar_storage_key,
a.visibility as avatar_visibility
from pump_agent_mints pam
left join agent_identities ai on ai.id = pam.agent_id and ai.deleted_at is null
left join avatars a on a.id = ai.avatar_id and a.deleted_at is null
where pam.mint=${mint} and pam.network=${network}
limit 1
`;
// Intel + outcome (observed by the Coin Intelligence Engine). Independent of
// the registry — works for any mint the engine watched.
const [intelRow] = await sql`
select * from pump_coin_intel where mint=${mint} limit 1
`;
const [outcomeRow] = await sql`
select graduated, rugged, outcome, ath_multiple, ath_market_cap_usd,
last_market_cap_usd, labeled_at
from pump_coin_outcomes where mint=${mint} limit 1
`;
// Economics + the agent's track record only exist for registry coins.
let economics = null;
let trader = null;
if (reg) {
const [stats] = await sql`
select
count(*) filter (where status='confirmed')::int as confirmed_payments,
count(distinct payer_wallet) filter (where status='confirmed')::int as unique_payers,
coalesce(sum(amount_atomics) filter (where status='confirmed'),0)::text as total_atomics,
max(confirmed_at) filter (where status='confirmed') as last_payment_at
from pump_agent_payments where mint_id=${reg.id}
`;
const [burnRow] = await sql`
select
count(*) filter (where status='confirmed')::int as runs,
coalesce(sum(burn_amount) filter (where status='confirmed'),0)::text as total_burned,
max(created_at) as last_burn_at
from pump_buyback_runs where mint_id=${reg.id}
`;
const [burnsFeed, creatorFees] = await Promise.all([
sql`
select id, currency_mint, tx_signature, burn_amount, created_at
from pump_buyback_runs
where mint_id=${reg.id} and status='confirmed'
order by created_at desc limit 8
`,
// Snapshot first; a live read (behind the shared creator-fee breaker)
// only for a coin the snapshot has not reached. Enrichment, so a
// failure degrades to null rather than failing the page.
solPriceUsd().then((price) => creatorFeesFor(mint, network, price)).catch(() => null),
]);
economics = {
confirmed_payments: stats?.confirmed_payments ?? 0,
unique_payers: stats?.unique_payers ?? 0,
total_atomics: stats?.total_atomics ?? '0',
last_payment_at: stats?.last_payment_at ?? null,
burns: {
runs: burnRow?.runs ?? 0,
total_burned: burnRow?.total_burned ?? '0',
last_burn_at: burnRow?.last_burn_at ?? null,
},
burns_feed: burnsFeed,
creator_fees: creatorFees,
};
// The launching agent's verifiable PnL — same truth layer as the
// leaderboard, so the page and /leaderboard can never disagree. Public
// agents only; private track records stay private.
if (reg.agent_id && reg.agent_public) {
try {
const s = await getTraderStats({ agentId: reg.agent_id, network, window: 'all' });
if (s?.metrics && s.metrics.closed_count > 0) {
const m = s.metrics;
trader = {
agent_id: reg.agent_id,
score: m.score,
verified: m.verified,
closed_count: m.closed_count,
open_count: m.open_count,
win_rate: m.win_rate,
realized_pnl_sol: m.realized_pnl_sol,
realized_pnl_usd: m.realized_pnl_usd,
roi_pct: m.roi_pct,
unique_coins: m.unique_coins,
best_pnl_pct: m.best_pnl_pct,
last_active_at: m.last_active_at,
};
}
} catch {
/* track record is best-effort enrichment; never block the page on it */
}
}
}
const avatarPublic =
reg?.avatar_visibility === 'public' || reg?.avatar_visibility === 'unlisted';
return {
mint,
network,
found: !!reg,
registry: reg
? {
name: reg.name,
symbol: reg.symbol,
buyback_bps: reg.buyback_bps,
agent_authority: reg.agent_authority,
metadata_uri: normalizeGatewayURL(reg.metadata_uri) || reg.metadata_uri,
quote_mint: reg.quote_mint,
sharing_config: reg.sharing_config,
created_at: reg.created_at,
}
: null,
agent: reg?.agent_id
? {
id: reg.agent_id,
name: reg.agent_name,
description: reg.agent_description,
url: `/agents/${reg.agent_id}`,
is_public: reg.agent_public,
avatar_thumbnail_url: avatarPublic ? safeR2Url(reg.avatar_thumbnail_key) : null,
// The launching agent's interactive 3D model — drives the inline
// <agent-3d> stage on the coin page. Public/unlisted only; private
// avatars fall back to the shared mannequin client-side.
avatar_model_url: avatarPublic ? safeR2Url(reg.avatar_storage_key) : null,
// Public custodial wallet (+ vanity) of the launching agent, so the
// shared wallet chip renders identically here as on the feed/profile.
solana_address: reg.agent_solana_address || null,
solana_vanity_prefix: reg.agent_solana_vanity_prefix || null,
solana_vanity_suffix: reg.agent_solana_vanity_suffix || null,
}
: null,
economics,
intel: shapeIntel(intelRow),
outcome: shapeOutcome(outcomeRow),
trader,
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.mcpIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, `http://${req.headers.host || 'x'}`);
const mint = (url.searchParams.get('mint') || '').trim();
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
if (!MINT_RE.test(mint))
return error(res, 400, 'invalid_mint', 'mint must be a base58 address');
const cacheKey = `${network}:${mint}`;
const now = Date.now();
const hit = CACHE.get(cacheKey);
if (hit && now - hit.at < TTL_MS) {
res.setHeader('cache-control', 'public, max-age=15, s-maxage=30');
return json(res, 200, hit.body);
}
const body = await buildDetail(mint, network);
CACHE.set(cacheKey, { at: now, body });
if (CACHE.size > 300) CACHE.delete(CACHE.keys().next().value);
res.setHeader('cache-control', 'public, max-age=15, s-maxage=30');
return json(res, 200, body);
});