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
// Shared bonding-curve view builder for a pump.fun mint.
//
// One RPC + Jupiter-fallback path, two doors: the authenticated dashboard route
// (api/pump/curve.js) and the free GET /api/v1/pump/curve endpoint both call
// getCurveView() and relay its { httpStatus, cacheControl, body } verbatim, so
// behavior (including cache headers) stays byte-identical between the two.
//
// Combines @nirholas/pump-sdk reads via the shared RpcFallback + sdk-bridge
// helpers: bonding curve raw state, current price + market cap, graduation
// progress. A coin can graduate (curve closed or left behind with complete=true)
// yet still trade on its AMM pool — Jupiter is the fallback price source for
// that case, enriched with a market cap since pump.fun mints a fixed 1B supply
// entirely into the curve/pool (FDV == market cap post-graduation).
import { rpcFallbackFromEnv, getBondingCurveState, getTokenPrice, getGraduationProgress } from './solana/index.js';
import { createCache } from './mem-cache.js';
import { cacheGet, cacheSet } from './cache.js';
import { hasThreeWsMark } from '../../src/solana/vanity/brand.js';
import { fetchUpstreamJson } from './upstream-fetch.js';
import { fetchTokenPriceUsd } from './market/token-market.js';
// Mints that can never carry a pump.fun bonding curve. These are coin-agnostic
// payment-rail / native tokens, listed only so we can *exclude* them from curve
// lookups — never to promote them. (USDC mainnet+devnet, wrapped SOL.)
export const NON_CURVE_MINTS = new Set([
'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC (mainnet)
'4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU', // USDC (devnet)
'So11111111111111111111111111111111111111112', // wrapped SOL
]);
// pump.fun mints a fixed total supply of exactly 1B tokens, the whole of which
// is sold through the curve and then seeded into the AMM pool on graduation. For
// these tokens fully-diluted value therefore equals market cap.
export const PUMP_TOTAL_SUPPLY = 1_000_000_000;
// Cheap, RPC-free pre-filter for "could this address carry a pump.fun bonding
// curve?". It exists to keep a misconfigured (e.g. USDC) mount, or a probe
// sweep, from turning into an RPC read per request. It is not the last word on
// what has a curve. Three shapes qualify, all decided from the address alone:
//
// 1. pump.fun's own launcher grinds every mint to end in the literal suffix
// "pump".
// 2. three.ws grinds its custodial launches to carry the "3ws" mark as a
// PREFIX (src/solana/vanity/brand.js) and never the "pump" suffix. Every
// agent token minted that way therefore lands here, and the suffix test
// alone used to reject all of them with a 300s-cached `not_a_pump_mint`
// 404: the curve read for our own coins could never succeed.
// 3. Anything on devnet. Nothing grinds a mark on the rehearsal cluster (a
// launch from the owner's own wallet mints a plain generated address), so
// an address-shape test there rejects real curves and answers nothing.
// Devnet traffic is owner rehearsals, not the probe volume the fast-path
// is defending against.
//
// A known settlement/native token is excluded outright on every cluster: it has
// no curve and never will. A mainnet mint of an unrecognized shape is NOT
// settled here: getCurveView asks the platform's own launch registry before it
// answers, because a coin launched from a user's wallet has no mark to read.
export function isPumpMint(mint, network = 'mainnet') {
if (typeof mint !== 'string' || NON_CURVE_MINTS.has(mint)) return false;
if (network === 'devnet') return isPlausibleMint(mint);
return mint.endsWith('pump') || hasThreeWsMark(mint);
}
export function isPlausibleMint(s) {
return /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(s);
}
// Mints the platform's own launch registry has confirmed, and mints it has
// denied, so an unmarked coin costs at most one DB read per TTL rather than one
// per request. Small and short-lived on purpose: the answer only changes when a
// launch lands, and a fresh launch's first curve read may wait out one TTL at
// worst.
const _registryAnswers = createCache({ max: 512 });
const REGISTRY_TTL_MS = 5 * 60_000;
/**
* Is this mint a coin three.ws itself launched? Reads pump_agent_mints, the
* platform's own launch directory: the same table /launches and the agent
* profile's launch history render from.
*
* A launch from the owner's own wallet (/api/agents/tokens/launch-confirm)
* mints a plain generated address with no brand mark, so the shape fast-path
* cannot recognize it and this registry is the only authority that can. Any
* failure (no database configured, a transient error) answers `false`, which
* degrades to exactly the pre-existing behaviour instead of a 500.
*
* @param {string} mint
* @param {'mainnet'|'devnet'} network
* @returns {Promise<boolean>}
*/
async function isRegisteredPlatformLaunch(mint, network) {
const key = `${network}:${mint}`;
const hit = _registryAnswers.get(key);
if (hit && Date.now() - hit.at < REGISTRY_TTL_MS) return hit.known;
let known = false;
try {
// Imported lazily: this module is loaded by pure-function tests and by
// routes that never reach this branch, and api/_lib/db.js throws at import
// time when DATABASE_URL is unset.
const { sql } = await import('./db.js');
const rows = await sql`
select 1 from pump_agent_mints
where mint = ${mint} and network = ${network}
limit 1
`;
known = rows.length > 0;
} catch (err) {
console.warn('[pump-curve-view] launch-registry lookup unavailable: %s', String(err?.message || err).slice(0, 120));
return false;
}
_registryAnswers.set(key, { known, at: Date.now() });
return known;
}
// Last good curve view per network:mint, kept so an RPC flake degrades the read
// to slightly-old real data instead of an unhandled 500. Same serve-stale tier
// as api/pump/price-history: never fabricated, only ever a body a healthy read
// really produced.
// Bounded by true LRU: trimming with `delete(keys().next().value)` evicted the
// oldest INSERTED mint, so the most-requested curve could lose its stale copy
// while colder mints kept theirs. Staleness stays an explicit field because the
// entry must remain readable to serve degraded data.
const _lastGood = createCache({ max: 256 }); // `${network}:${mint}` → { body, at }
const STALE_MAX_MS = 10 * 60_000;
// The shared tier outlives a single instance: a cold Cloud Run instance used to
// hold no memory copy at all, so the first read during an RPC outage answered
// 502 no matter how recently a warm sibling had served the same mint.
const SHARED_LKG_TTL_S = 24 * 3600;
function lkgKey(network, mint) {
return `pump:curve:lkg:${network}:${mint}`;
}
function rememberGood(network, mint, body) {
const entry = { body, at: Date.now() };
_lastGood.set(`${network}:${mint}`, entry);
// Fire-and-forget: cacheSet never rejects, and the response is already in hand.
cacheSet(lkgKey(network, mint), entry, SHARED_LKG_TTL_S).catch(() => {});
}
async function recallGood(network, mint) {
const hit = _lastGood.get(`${network}:${mint}`);
if (hit && Date.now() - hit.at <= STALE_MAX_MS) return hit;
let shared = null;
try {
shared = await cacheGet(lkgKey(network, mint));
} catch {
shared = null;
}
if (shared && shared.body && typeof shared.at === 'number') return shared;
return hit || null;
}
async function jupiterPriceFallback(mint) {
try {
const data = await fetchUpstreamJson(
`https://lite-api.jup.ag/price/v3?ids=${mint}`,
{},
{ name: 'jupiter:price', timeoutMs: 6000, attempts: 2 },
);
const usd = data?.[mint]?.usdPrice ?? data?.[mint]?.price;
const n = Number(usd);
if (Number.isFinite(n) && n > 0) return { priceUsd: n, source: 'jupiter' };
// Jupiter has no price for this mint (or could not answer). The shared
// market chain covers the mints Jupiter misses, which for a bonding-curve
// token is most of the interesting ones.
const alt = Number(await fetchTokenPriceUsd(mint));
return Number.isFinite(alt) && alt > 0 ? { priceUsd: alt, source: 'market-chain' } : null;
} catch {
return null;
}
}
export function serializeBNs(obj) {
if (obj == null || typeof obj !== 'object') return obj;
const out = Array.isArray(obj) ? [] : {};
for (const [k, v] of Object.entries(obj)) {
if (
v &&
typeof v === 'object' &&
typeof v.toString === 'function' &&
(v.constructor?.name === 'BN' || typeof v.toNumber === 'function')
) {
out[k] = v.toString();
} else if (v && typeof v === 'object') {
out[k] = serializeBNs(v);
} else {
out[k] = v;
}
}
return out;
}
/**
* Build the full curve-view payload for a mint. Returns a discriminated result
* `{ httpStatus, cacheControl, body }` — callers relay it verbatim via their own
* `json(res, httpStatus, body, { 'cache-control': cacheControl })` (or without
* the cache-control header when it's null, letting the secure-by-default
* no-store apply — matches every error response before this extraction).
*
* Caller is expected to have already validated `mint` with isPlausibleMint().
*/
export async function getCurveView({ mint, network = 'mainnet' }) {
// The shape fast-path answers for pump.fun-ground and three.ws-marked mints
// without touching anything. An unrecognized mainnet address gets one more
// question (is it a coin we launched?) before it is refused, because an
// agent token launched from the owner's own wallet carries no mark at all.
if (!isPumpMint(mint, network) && !(await isRegisteredPlatformLaunch(mint, network))) {
// Negative-cacheable so the CDN edge serves repeat probes without hitting
// the function at all — no cold start, no RPC reads, no warning spam.
return {
httpStatus: 404,
cacheControl: 'public, s-maxage=300, max-age=300',
body: { error: 'not_a_pump_mint', error_description: 'mint has no pump.fun bonding curve' },
};
}
const rpc = rpcFallbackFromEnv({ network });
let result;
try {
result = await rpc.withFallback(async (connection) => {
const [curve, price, grad] = await Promise.all([
getBondingCurveState(connection, mint),
getTokenPrice(connection, mint),
getGraduationProgress(connection, mint),
]);
return { curve, price, graduation: grad };
});
} catch (err) {
// Every RPC lane failed. That is an upstream outage, not an answer about
// the coin, so degrade like price-history does: serve the last good view
// for this mint marked stale, else a well-formed 502 the clients' existing
// error states already render.
console.error('[pump-curve-view] all RPC lanes failed', err?.message);
const stale = await recallGood(network, mint);
if (stale) {
return {
httpStatus: 200,
cacheControl: 'public, max-age=10, s-maxage=10',
body: { ...stale.body, stale: true, as_of: new Date(stale.at).toISOString(), as_of_unix: Math.floor(stale.at / 1000) },
};
}
return {
httpStatus: 502,
cacheControl: null,
body: {
error: 'upstream_error',
error_description: 'bonding-curve state is temporarily unavailable for this mint',
},
};
}
if (!result.curve) {
// No on-chain bonding curve account. Two cases to disambiguate:
// 1. Graduated coin — the curve account is closed once a coin migrates
// to its AMM pool, but the token still trades with a live DEX price.
// Fall back to Jupiter and return a 200 "graduated" view so callers
// render the real price instead of a dead 404. (Our own $THREE lives
// here post-migration.)
// 2. A mint that never had a curve — Jupiter has nothing either, so the
// 404 stands and the client's stop-on-404 path fires as before.
const graduatedPrice = await jupiterPriceFallback(mint);
if (graduatedPrice) {
const marketCapUsd = graduatedPrice.priceUsd * PUMP_TOTAL_SUPPLY;
const body = {
mint,
network,
curve: null,
graduated: true,
price: null,
graduation: { isGraduated: true, progressBps: 10_000 },
graduatedPrice: { ...graduatedPrice, marketCapUsd },
};
rememberGood(network, mint, body);
return {
httpStatus: 200,
cacheControl: 'public, max-age=15, s-maxage=30, stale-while-revalidate=60',
body,
};
}
return {
httpStatus: 404,
cacheControl: null,
body: { error: 'no_curve', error_description: 'no bonding curve found for that mint' },
};
}
// Graduated coins have no bonding-curve price. A coin can graduate yet leave
// its on-chain curve account behind (closed, reserves zeroed, complete=true) —
// this is exactly the case for our own $THREE. Fall back to Jupiter so callers
// always get a usable price even after migration to a DEX, and surface the same
// `graduated: true` + market-cap-enriched `graduatedPrice` shape as the
// curve-gone path above so every consumer renders graduated coins identically.
let pricePayload = result.price ? serializeBNs(result.price) : null;
const curveComplete = Boolean(result.curve?.complete);
let graduatedPrice = null;
if (!pricePayload && curveComplete) {
const jup = await jupiterPriceFallback(mint);
if (jup) {
graduatedPrice = { ...jup, marketCapUsd: jup.priceUsd * PUMP_TOTAL_SUPPLY };
}
}
const body = {
mint,
network,
curve: result.curve,
...(curveComplete ? { graduated: true } : {}),
price: pricePayload,
graduation: result.graduation ? serializeBNs(result.graduation) : null,
...(graduatedPrice ? { graduatedPrice } : {}),
};
rememberGood(network, mint, body);
return {
httpStatus: 200,
cacheControl: 'public, max-age=5, s-maxage=10, stale-while-revalidate=30',
body,
};
}