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
/**
* $THREE Token Protocol API
* -------------------------
* GET /api/three-token/stats — protocol-level metrics (public)
* GET /api/three-token/revenue-share — authenticated user's revenue share position
* GET /api/three-token/burns: platform burn ledger (always empty: no platform burns)
* GET /api/three-token/activity — protocol activity feed
* GET /api/three-token/leaderboard — ranked $THREE holders (public, paginated)
* GET /api/three-token/wallets: treasury + rewards wallet addresses and live balances (public)
*
* Market data (price, market cap, supply, holders) comes from the shared market
* module — Birdeye → DexScreener → GeckoTerminal failover with a stale cache —
* so a Birdeye 429 transparently falls over to the keyless sources instead of
* blanking the price panel. Protocol data (agents, revenue) is derived from the
* application database. The platform never burns $THREE (api/_lib/token/config.js);
* its supply commitment is the revenue buyback reported under `buyback`.
*/
import { sql } from '../_lib/db.js';
import { getSessionUser } from '../_lib/auth.js';
import { cors, error, json, method, wrap } from '../_lib/http.js';
import { TOKEN_MINT as THREE_MINT } from '../_lib/token/config.js';
import { fetchTokenMarketData } from '../_lib/market/token-market.js';
import { threeHolderBalances, threeHolderCount } from '../_lib/coin/three-holders.js';
import { buybackStats } from '../_lib/token/buyback.js';
import { microbuyStats } from '../_lib/token/microbuy.js';
import { fetchPumpVerification } from '../_lib/pump-verification.js';
import { publicWalletBalances } from '../_lib/token/wallet-balances.js';
// Truncate a base58 wallet for display: "FeMb…Jpump".
function shortWallet(addr) {
const s = String(addr || '');
return s.length > 10 ? `${s.slice(0, 4)}…${s.slice(-4)}` : s;
}
// Protocol tokenomics (fixed parameters of the $THREE protocol).
// REVENUE_SHARE_POOL_PCT: share of platform revenue distributed to holders.
const REVENUE_SHARE_POOL_PCT = 10;
// Degrade a failed panel query without hiding WHY it failed. A silent
// `.catch(() => [])` is how the deploy-burn ledger shipped permanently empty:
// the query named a column agent_identities never had, the fallback turned the
// error into a plausible zero, and nothing in the logs said otherwise.
function degrade(label, value) {
return (err) => {
console.error(`[three-token] ${label} query failed:`, err?.message || err);
return value;
};
}
async function fetchPlatformMetrics() {
const [agentCount, revenueData, paymentCount] = await Promise.all([
sql`SELECT count(*)::int AS total FROM agent_identities WHERE deleted_at IS NULL`.catch(
degrade('agent_count', [{ total: 0 }]),
),
sql`SELECT coalesce(sum(gross_amount), 0)::bigint AS total_gross, coalesce(sum(fee_amount), 0)::bigint AS total_fee FROM agent_revenue_events`.catch(
degrade('revenue_totals', [{ total_gross: 0, total_fee: 0 }]),
),
sql`SELECT count(*)::int AS total FROM agent_revenue_events`.catch(
degrade('payment_count', [{ total: 0 }]),
),
]);
return {
total_agents: agentCount[0]?.total ?? 0,
total_revenue_gross: Number(revenueData[0]?.total_gross ?? 0),
total_revenue_fee: Number(revenueData[0]?.total_fee ?? 0),
total_payments: paymentCount[0]?.total ?? 0,
};
}
async function fetchRecentActivity() {
const rows = await sql`
SELECT
e.id,
e.skill,
e.gross_amount,
e.fee_amount,
e.created_at,
a.name AS agent_name
FROM agent_revenue_events e
LEFT JOIN agent_identities a ON a.id = e.agent_id
ORDER BY e.created_at DESC
LIMIT 30
`.catch(degrade('activity_events', []));
return rows;
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const url = new URL(req.url, 'http://x');
const parts = url.pathname.split('/').filter(Boolean);
const action = parts[2];
if (action === 'stats') {
const [market, platform, buyback, microbuy, holderCount, verification] = await Promise.all([
fetchTokenMarketData(THREE_MINT).catch(() => null),
fetchPlatformMetrics(),
// Programmatic buyback summary (revenue → $THREE bought into treasury).
// Resilient: returns zeros before the first run / migration.
buybackStats().catch(() => null),
// High-frequency micro-buy summary (continuous small buys → treasury).
// Same resilience contract; null before the first buy / migration.
microbuyStats().catch(() => null),
// Holder count from our own snapshot — the keyless market sources
// (DexScreener / GeckoTerminal) don't return holders, so without this the
// panel shows "—" whenever Birdeye is rate-limited. Cheap meta read only.
threeHolderCount().catch(() => null),
// pump.fun's own verification flag for the mint, read live (5-min cached
// upstream). Never hardcoded: the badge our surfaces render has to be
// whatever pump.fun publishes right now, or it is decoration.
fetchPumpVerification(THREE_MINT).catch(() => null),
]);
return json(
res,
200,
{
token: {
mint: THREE_MINT,
symbol: '$THREE',
price_usd: market?.price_usd ?? null,
price_change_24h: market?.price_change_24h ?? null,
market_cap: market?.market_cap ?? null,
volume_24h: market?.volume_24h ?? null,
holders: market?.holders ?? holderCount ?? null,
liquidity: market?.liquidity ?? null,
supply: market?.supply ?? null,
decimals: market?.decimals ?? 6,
source: market?.source ?? null,
// true = pump.fun publishes the verified badge for this mint,
// false = it does not, null = we could not read it this request.
verified: verification?.verified ?? null,
verified_source: 'pumpfun',
pump_url: verification?.url ?? `https://pump.fun/coin/${THREE_MINT}`,
},
protocol: {
total_agents: platform.total_agents,
total_revenue_usd: platform.total_revenue_gross / 1_000_000,
total_payments: platform.total_payments,
revenue_share_pool_pct: REVENUE_SHARE_POOL_PCT,
},
// Revenue converted to onchain buy pressure — programmatic, no burn.
// Commitment fields mirror buybackStats() so the page renders the
// published promise even on a transient stats failure.
buyback: buyback ?? {
enabled: false,
commit_bps: 5000,
commit_pct: 50,
committed_usd: 0,
commitment_progress_pct: 0,
revenue_usd: 0,
deployed_usd: 0,
deployed_pct: 0,
three_bought: 0,
runs: 0,
recent_runs: [],
last_run: null,
},
// Continuous micro-buy pressure (many tiny x402-settled buys → treasury).
// Sibling of buyback; same resilient default before the first buy.
microbuy: microbuy ?? {
enabled: false,
buy_usd: 0.01,
lifetime: { buys: 0, confirmed: 0, pending: 0, usdc_deployed: 0, three_bought: 0 },
today: { buys: 0, usdc_deployed: 0, cap_usd: 50, cap_used_pct: 0 },
},
},
// Edge-cache the public stats at the CDN so most page loads never reach
// the lambda (or Birdeye). 20s freshness is invisible for a token price;
// stale-while-revalidate keeps the panel populated during a refresh.
{ 'cache-control': 'public, s-maxage=20, stale-while-revalidate=120' },
);
}
if (action === 'wallets') {
// The two public receivers of every $THREE split, with what each holds right
// now. Unset wallets come back `configured: false` (never hidden), and a
// balance the RPC chain could not read comes back `ok: false` (never zero).
const snapshot = await publicWalletBalances();
return json(res, 200, snapshot, { 'cache-control': 'public, s-maxage=30, stale-while-revalidate=60' });
}
if (action === 'revenue-share') {
const user = await getSessionUser(req, res);
if (!user) return error(res, 401, 'unauthorized', 'sign in required');
const [platform, market, holderCount] = await Promise.all([
fetchPlatformMetrics(),
fetchTokenMarketData(THREE_MINT).catch(() => null),
// Same snapshot fallback /stats uses: the keyless market sources carry no
// holder count, and the two actions must not disagree about how many holders
// exist just because the price came from DexScreener on this request.
threeHolderCount().catch(() => null),
]);
const totalSupply = market?.supply ?? null;
const totalRevenue = platform.total_revenue_gross / 1_000_000;
const poolPct = REVENUE_SHARE_POOL_PCT;
const revenuePool = totalRevenue * (poolPct / 100);
return json(res, 200, {
user_id: user.id,
token_price: market?.price_usd ?? null,
total_supply: totalSupply,
total_holders: market?.holders ?? holderCount ?? null,
platform_revenue_usd: totalRevenue,
revenue_share_pool_pct: poolPct,
revenue_share_pool_usd: revenuePool,
...(totalSupply > 0 ? { per_token_yield: revenuePool / totalSupply } : {}),
});
}
if (action === 'burns') {
// The platform never burns $THREE, so there is no burn ledger to report.
// This endpoint once derived "burns" from the agent count with no on-chain
// transaction behind them; it now answers with the policy and an empty
// ledger, and points callers at the buyback figures that are real.
return json(
res,
200,
{
policy: 'no_platform_burns',
burns: [],
total_burned: 0,
burn_per_deploy: 0,
see: '/api/three-token/stats#buyback',
},
{ 'cache-control': 'public, s-maxage=3600' },
);
}
if (action === 'activity') {
const events = await fetchRecentActivity();
return json(res, 200, {
events: events.map((e) => ({
id: e.id,
type: e.skill || 'payment',
gross_usd: e.gross_amount ? Number(e.gross_amount) / 1_000_000 : null,
fee_usd: e.fee_amount ? Number(e.fee_amount) / 1_000_000 : null,
agent_name: e.agent_name || 'Agent',
created_at: e.created_at,
})),
});
}
if (action === 'leaderboard') {
// Non-finite input (?limit=abc, ?offset=1e999) falls back to the default
// rather than propagating NaN/Infinity into the slice and the JSON body.
const limitRaw = Number(url.searchParams.get('limit'));
const limit = Number.isFinite(limitRaw) && limitRaw >= 1 ? Math.min(100, Math.floor(limitRaw)) : 50;
const offsetRaw = Number(url.searchParams.get('offset'));
const offset = Number.isFinite(offsetRaw) && offsetRaw > 0 ? Math.floor(offsetRaw) : 0;
try {
// Holder set from the cached snapshot (three-holders-snapshot cron) — the
// full $THREE holder list across all token programs, without a per-request
// Helius DAS walk. Market data gives supply → % of supply. Both are
// independently resilient; a market-data blip just nulls the percentages.
const [balances, market] = await Promise.all([
threeHolderBalances(),
fetchTokenMarketData(THREE_MINT).catch(() => null),
]);
const decimals = Number(market?.decimals ?? 6);
const atomicsPerToken = 10 ** decimals;
const supply = market?.supply != null ? Number(market.supply) : null;
// Rank by exact atomic balance (BigInt) so huge holders order correctly
// even past Number's 2^53 precision; only convert to a display Number
// for the page slice we actually return.
const ranked = [...balances.entries()]
.filter(([, atomic]) => atomic > 0n)
.sort((a, b) => (a[1] < b[1] ? 1 : a[1] > b[1] ? -1 : 0));
const total = ranked.length;
const holders = ranked.slice(offset, offset + limit).map(([wallet, atomic], i) => {
const amount = Number(atomic) / atomicsPerToken;
return {
rank: offset + i + 1,
wallet,
wallet_short: shortWallet(wallet),
amount,
pct_of_supply: supply ? amount / supply : null,
};
});
return json(
res,
200,
{ holders, total, limit, offset, supply, mint: THREE_MINT, decimals },
// Holder sets change slowly; cache at the edge so the Helius scan
// (seconds, thousands of accounts) runs at most once a minute.
{ 'cache-control': 'public, s-maxage=60, stale-while-revalidate=300' },
);
} catch (err) {
// Never 500 a public board — Helius unconfigured / rate-limited returns an
// empty board so the page renders its empty state instead of an error.
console.error('[three-token/leaderboard]', err?.message || err);
return json(
res,
200,
{ holders: [], total: 0, limit, offset, supply: null, mint: THREE_MINT },
{ 'cache-control': 'public, s-maxage=30' },
);
}
}
return error(res, 404, 'not_found', `unknown action: ${action}`);
});