Skip to content

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.

feat(analytics): publish every platform total with a daily series at /api/platform/analytics

nirholas0af815c5bea2
diff --git a/api/_lib/agent-economy.js b/api/_lib/agent-economy.js
index 333ef3b78..fea8fc6e9 100644
--- a/api/_lib/agent-economy.js
+++ b/api/_lib/agent-economy.js
@@ -420,13 +420,17 @@ function emptyPlatformStats(windowDays) {
* @param {number} [opts.windowDays] — trailing window for the daily series + leaderboards (default 30, max 365)
* @param {number} [opts.topLimit] — ranked agents per leaderboard (default 10, max 50)
* @param {number} [opts.recentLimit] — recent settled hires in the feed (default 12, max 50)
+ * @param {number} [opts.maxWindowDays] - ceiling on windowDays (default 365). The public
+ * /api/agent-economy/volume endpoint keeps the default; the platform analytics roll-up
+ * raises it so its "all time" window never silently drops the oldest hires.
*/
export async function platformEconomyStats({
windowDays = 30,
topLimit = 10,
recentLimit = 12,
+ maxWindowDays = 365,
} = {}) {
- const win = Math.min(365, Math.max(1, Math.floor(Number(windowDays) || 30)));
+ const win = Math.min(maxWindowDays, Math.max(1, Math.floor(Number(windowDays) || 30)));
const top = Math.min(50, Math.max(1, Math.floor(Number(topLimit) || 10)));
const recent = Math.min(50, Math.max(1, Math.floor(Number(recentLimit) || 12)));
diff --git a/api/_lib/platform-analytics.js b/api/_lib/platform-analytics.js
new file mode 100644
index 000000000..b60182218
--- /dev/null
+++ b/api/_lib/platform-analytics.js
@@ -0,0 +1,431 @@
+// Platform analytics: every headline number three.ws publishes about itself,
+// in one read, each with a daily series and a plain-language `method`.
+//
+// This is the data layer behind GET /api/platform/analytics and the /analytics
+// page. It answers "how big is the platform and is it growing" from the real
+// tables that record each activity, never from a counter someone typed in.
+//
+// Contract:
+// - Every metric carries `total` (all time), `window_total` (inside the
+// requested window), a zero-filled `daily` series over the window, and a
+// `method` string saying exactly which rows were counted.
+// - Metrics are read in SOURCES (one or two queries per table). A source that
+// fails or times out yields `null` for each of its metrics plus one entry in
+// `errors`; it never fails the whole read and never reports a zero it did
+// not measure.
+// - Counting predicates match the endpoints that already publish the same
+// figure, so the analytics page and the home page can never disagree:
+// agents use the /api/home-stats and /api/platform/stats predicate, 3D
+// models the /api/home-stats one, marketplace sales the MARKET_PAID_KINDS
+// gate /pulse uses, and hire volume is read through platformEconomyStats(),
+// the helper behind /api/agent-economy/volume.
+
+import { sql } from './db.js';
+import { platformEconomyStats } from './agent-economy.js';
+import { MARKET_PAID_KINDS } from './marketplace-kinds.js';
+import { TOKEN_MINT, TOKEN_DECIMALS } from './token/config.js';
+import { SOLANA_USDC_MINT } from '../payments/_config.js';
+
+const DAY_MS = 86_400_000;
+const USDC_DECIMALS = 6;
+// A source slower than this is reported as unavailable rather than holding the
+// whole response hostage. The slowest measured source (x402 settlements over
+// 1.5M log rows) finished in under 5 s on production data on 2026-09-30.
+const SOURCE_TIMEOUT_MS = 15_000;
+
+export const ANALYTICS_WINDOWS = Object.freeze({ '30d': 30, '90d': 90, all: null });
+export const DEFAULT_WINDOW = '30d';
+
+/** Normalise a `?window=` value to one of ANALYTICS_WINDOWS' keys. */
+export function resolveWindow(raw) {
+ const key = String(Array.isArray(raw) ? raw[0] : raw ?? '').trim().toLowerCase();
+ return Object.hasOwn(ANALYTICS_WINDOWS, key) ? key : DEFAULT_WINDOW;
+}
+
+function utcDayKey(ms) {
+ return new Date(ms).toISOString().slice(0, 10);
+}
+
+function todayUtcMs(now) {
+ return Date.parse(`${utcDayKey(now)}T00:00:00Z`);
+}
+
+/**
+ * First UTC day of a bounded window, inclusive: a 30 day window is today plus
+ * the 29 days before it. `null` for the all-time window.
+ */
+export function windowStartDay(windowKey, now = Date.now()) {
+ const days = ANALYTICS_WINDOWS[windowKey];
+ if (!days) return null;
+ return utcDayKey(todayUtcMs(now) - (days - 1) * DAY_MS);
+}
+
+/** Every UTC day key from `fromDay` to today, inclusive. */
+export function dayRange(fromDay, now = Date.now()) {
+ const end = todayUtcMs(now);
+ const out = [];
+ for (let t = Date.parse(`${fromDay}T00:00:00Z`); t <= end; t += DAY_MS) out.push(utcDayKey(t));
+ return out;
+}
+
+function atomicToUnits(atomic, decimals) {
+ return Number(atomic || 0) / 10 ** decimals;
+}
+
+// ── Sources ─────────────────────────────────────────────────────────────────
+// Each source reads one table and returns { total: {key: n}, daily: [{day, key: n}] }.
+// `daily` rows only exist for days with activity; zero-filling happens once, below.
+
+async function agentsSource(sinceDay) {
+ const bound = sinceDay ? `${sinceDay}T00:00:00Z` : null;
+ const [totals, daily] = await Promise.all([
+ sql`
+ SELECT
+ COUNT(*)::bigint AS agents,
+ COUNT(*) FILTER (WHERE COALESCE(meta->>'solana_address', '') <> '' OR wallet_address IS NOT NULL)::bigint AS agents_with_wallet
+ FROM agent_identities
+ WHERE deleted_at IS NULL
+ `,
+ sql`
+ SELECT
+ to_char((created_at AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COUNT(*)::bigint AS agents,
+ COUNT(*) FILTER (WHERE COALESCE(meta->>'solana_address', '') <> '' OR wallet_address IS NOT NULL)::bigint AS agents_with_wallet
+ FROM agent_identities
+ WHERE deleted_at IS NULL
+ AND (${bound}::timestamptz IS NULL OR created_at >= ${bound}::timestamptz)
+ GROUP BY 1
+ `,
+ ]);
+ return {
+ total: { agents: Number(totals[0]?.agents || 0), agents_with_wallet: Number(totals[0]?.agents_with_wallet || 0) },
+ daily: daily.map((r) => ({ day: r.day, agents: Number(r.agents), agents_with_wallet: Number(r.agents_with_wallet) })),
+ };
+}
+
+async function launchesSource(sinceDay) {
+ const rows = await sql`
+ WITH launches AS (
+ SELECT created_at FROM pump_agent_mints WHERE network = 'mainnet'
+ UNION ALL
+ SELECT created_at FROM fixed_supply_launches WHERE network = 'mainnet'
+ )
+ SELECT
+ to_char((created_at AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COUNT(*)::bigint AS coins_launched
+ FROM launches
+ GROUP BY 1
+ `;
+ const daily = rows.map((r) => ({ day: r.day, coins_launched: Number(r.coins_launched) }));
+ return {
+ total: { coins_launched: daily.reduce((n, r) => n + r.coins_launched, 0) },
+ daily: sinceDay ? daily.filter((r) => r.day >= sinceDay) : daily,
+ };
+}
+
+async function forgeSource(sinceDay) {
+ const bound = sinceDay ? `${sinceDay}T00:00:00Z` : null;
+ const [totals, daily] = await Promise.all([
+ sql`
+ SELECT COUNT(*)::bigint AS n
+ FROM forge_creations
+ WHERE status = 'done' AND glb_url IS NOT NULL AND (outcome IS NULL OR outcome != 'rejected')
+ `,
+ sql`
+ SELECT
+ to_char((created_at AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COUNT(*)::bigint AS n
+ FROM forge_creations
+ WHERE status = 'done' AND glb_url IS NOT NULL AND (outcome IS NULL OR outcome != 'rejected')
+ AND (${bound}::timestamptz IS NULL OR created_at >= ${bound}::timestamptz)
+ GROUP BY 1
+ `,
+ ]);
+ return {
+ total: { models_generated: Number(totals[0]?.n || 0) },
+ daily: daily.map((r) => ({ day: r.day, models_generated: Number(r.n) })),
+ };
+}
+
+async function llmSource(sinceDay) {
+ // One pass over the partial index usage_events_llm_time: the all-time total
+ // is the sum of the all-time daily series, and a bounded window keeps only
+ // its own days of that series.
+ const allDaily = await sql`
+ SELECT
+ to_char((created_at AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COALESCE(SUM(COALESCE(input_tokens, 0) + COALESCE(output_tokens, 0)), 0)::bigint AS n
+ FROM usage_events
+ WHERE kind = 'llm'
+ GROUP BY 1
+ `;
+ const daily = allDaily.map((r) => ({ day: r.day, llm_tokens: Number(r.n) }));
+ return {
+ total: { llm_tokens: daily.reduce((n, r) => n + r.llm_tokens, 0) },
+ daily: sinceDay ? daily.filter((r) => r.day >= sinceDay) : daily,
+ };
+}
+
+async function x402Source(sinceDay) {
+ // Grouped by day over the (action, ok, ts) index; the all-time totals are the
+ // sum of the days, so the table is scanned once.
+ const rows = await sql`
+ SELECT
+ to_char((ts AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COUNT(*)::bigint AS settlements,
+ COALESCE(SUM(amount_atomic) FILTER (WHERE mint = ${SOLANA_USDC_MINT}), 0)::text AS usdc_atomic
+ FROM x402_self_facilitator_log
+ WHERE action = 'settle' AND ok = true
+ GROUP BY 1
+ `;
+ const daily = rows.map((r) => ({
+ day: r.day,
+ x402_settlements: Number(r.settlements),
+ x402_volume_usd: atomicToUnits(r.usdc_atomic, USDC_DECIMALS),
+ }));
+ return {
+ total: {
+ x402_settlements: daily.reduce((n, r) => n + r.x402_settlements, 0),
+ x402_volume_usd: daily.reduce((n, r) => n + r.x402_volume_usd, 0),
+ },
+ daily: sinceDay ? daily.filter((r) => r.day >= sinceDay) : daily,
+ };
+}
+
+async function marketplaceSource(sinceDay) {
+ const rows = await sql`
+ SELECT
+ to_char((COALESCE(confirmed_at, created_at) AT TIME ZONE 'UTC')::date, 'YYYY-MM-DD') AS day,
+ COUNT(*)::bigint AS sales,
+ COALESCE(SUM(amount) FILTER (WHERE currency_mint = ${TOKEN_MINT}), 0)::text AS three_atomic,
+ COALESCE(SUM(amount) FILTER (WHERE currency_mint = ${SOLANA_USDC_MINT}), 0)::text AS usdc_atomic
+ FROM skill_purchases
+ WHERE status = 'confirmed' AND kind = ANY(${MARKET_PAID_KINDS})
+ GROUP BY 1
+ `;
+ const daily = rows.map((r) => ({
+ day: r.day,
+ marketplace_sales: Number(r.sales),
+ marketplace_volume_three: atomicToUnits(r.three_atomic, TOKEN_DECIMALS),
+ marketplace_volume_usd: atomicToUnits(r.usdc_atomic, USDC_DECIMALS),
+ }));
+ const sum = (k) => daily.reduce((n, r) => n + r[k], 0);
+ return {
+ total: {
+ marketplace_sales: sum('marketplace_sales'),
+ marketplace_volume_three: sum('marketplace_volume_three'),
+ marketplace_volume_usd: sum('marketplace_volume_usd'),
+ },
+ daily: sinceDay ? daily.filter((r) => r.day >= sinceDay) : daily,
+ };
+}
+
+async function hiresSource(sinceDay, now) {
+ // Reuses the /api/agent-economy/volume read so hire volume is one number
+ // platform-wide. Its daily series is a trailing window in days; the all-time
+ // window asks for enough days to reach the platform's first hire.
+ const windowDays = sinceDay
+ ? Math.round((todayUtcMs(now) - Date.parse(`${sinceDay}T00:00:00Z`)) / DAY_MS) + 1
+ : 3650;
+ const stats = await platformEconomyStats({ windowDays, topLimit: 1, recentLimit: 1, maxWindowDays: 3650 });
+ return {
+ total: { hire_volume_usd: Number(stats.totals?.volume_usd || 0) },
+ daily: (stats.daily || []).map((r) => ({ day: String(r.day).slice(0, 10), hire_volume_usd: Number(r.volume_usd || 0) })),
+ };
+}
+
+// ── Metric catalogue ────────────────────────────────────────────────────────
+// Order here is the order the page renders. `unit` drives formatting:
+// count | tokens | usd | three.
+
+export const METRICS = Object.freeze([
+ {
+ key: 'agents',
+ source: 'agents',
+ label: 'Agents',
+ unit: 'count',
+ method: 'Every agent identity on three.ws that has not been deleted (table agent_identities, deleted_at is null), published or not. The daily series counts agents by the day they were created. Same rows /api/home-stats and /api/platform/stats count.',
+ },
+ {
+ key: 'agents_with_wallet',
+ source: 'agents',
+ label: 'Agents with a wallet',
+ unit: 'count',
+ method: 'Agents from the row above that hold a wallet: a Solana address in their record (the custodial wallet every new agent gets) or a linked EVM wallet address. Each agent is counted once even if it has both.',
+ },
+ {
+ key: 'coins_launched',
+ source: 'launches',
+ label: 'Coins launched',
+ unit: 'count',
+ method: 'Coins launched on Solana mainnet through three.ws: bonding-curve launches recorded in pump_agent_mints plus fixed-supply launches recorded in fixed_supply_launches. Devnet test launches are excluded. Counted by launch day.',
+ },
+ {
+ key: 'models_generated',
+ source: 'forge',
+ label: '3D models generated',
+ unit: 'count',
+ method: 'Finished 3D generations (table forge_creations): status done, a GLB file stored, and not rejected by the quality gate. Failed and in-progress jobs are not counted. Counted by the day the job was started. Same predicate /api/home-stats uses.',
+ },
+ {
+ key: 'llm_tokens',
+ source: 'llm',
+ label: 'LLM tokens processed',
+ unit: 'tokens',
+ method: 'Input plus output tokens of every metered language-model call the platform made for agents, chats and tools (usage_events rows of kind llm). Metering began on 2026-06-08, so earlier calls are not in the total.',
+ },
+ {
+ key: 'x402_settlements',
+ source: 'x402',
+ label: 'x402 settlements',
+ unit: 'count',
+ method: 'Successful on-chain settlements by the three.ws self-hosted Solana x402 facilitator (x402_self_facilitator_log, action settle, ok). Failed and verify-only attempts are excluded. This includes the platform\'s own self-cycled agent ring, reported on its own at /api/x402-ring.',
+ },
+ {
+ key: 'x402_volume_usd',
+ source: 'x402',
+ label: 'x402 volume',
+ unit: 'usd',
+ method: 'The amount moved by the settlements above that were paid in USDC, at face value (1 USDC = $1). Settlements paid in $THREE are counted in the settlement number but not added here, so no token price is assumed.',
+ },
+ {
+ key: 'marketplace_sales',
+ source: 'marketplace',
+ label: 'Marketplace sales',
+ unit: 'count',
+ method: 'Paid skill purchases on the marketplace (skill_purchases with status confirmed and kind purchase or time pass). Free trials, bundles and pending or expired checkouts are not sales and are excluded. Counted by confirmation day.',
+ },
+ {
+ key: 'marketplace_volume_three',
+ source: 'marketplace',
+ label: 'Marketplace volume ($THREE)',
+ unit: 'three',
+ method: 'The price paid for the sales above that settled in $THREE, in whole tokens.',
+ },
+ {
+ key: 'marketplace_volume_usd',
+ source: 'marketplace',
+ label: 'Marketplace volume (USD)',
+ unit: 'usd',
+ method: 'The price paid for the sales above that settled in USDC, at face value.',
+ },
+ {
+ key: 'hire_volume_usd',
+ source: 'hires',
+ label: 'Agent-to-agent hire volume',
+ unit: 'usd',
+ method: 'USD paid by one agent to another for a paid skill over x402 (agent_hires, status completed), by completion day. The same ledger /agent-economy-volume charts.',
+ },
+ {
+ key: 'creator_fees',
+ source: null,
+ label: 'Creator fees earned',
+ unit: 'usd',
+ method: 'coming with per-agent earnings',
+ },
+]);
+
+const SOURCES = {
+ agents: agentsSource,
+ launches: launchesSource,
+ forge: forgeSource,
+ llm: llmSource,
+ x402: x402Source,
+ marketplace: marketplaceSource,
+ hires: hiresSource,
+};
+
+function withTimeout(promise, ms, name) {
+ let timer;
+ const timeout = new Promise((_, reject) => {
+ timer = setTimeout(() => reject(new Error(`${name} timed out after ${ms} ms`)), ms);
+ });
+ return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+// Summing per-day decimal amounts drifts in the last float digits
+// (11752.067000000001). Six places is the finest unit any metric here has.
+function tidy(n) {
+ return Number.isInteger(n) ? n : Number(n.toFixed(6));
+}
+
+function zeroFill(days, rows, key) {
+ const byDay = new Map();
+ for (const r of rows) byDay.set(r.day, (byDay.get(r.day) || 0) + (Number(r[key]) || 0));
+ return days.map((day) => ({ day, value: tidy(byDay.get(day) || 0) }));
+}
+
+/**
+ * Read every metric for one window.
+ *
+ * @param {object} [opts]
+ * @param {'30d'|'90d'|'all'} [opts.window]
+ * @param {number} [opts.now] clock override for tests
+ * @param {Record<string, Function>} [opts.sources] source override for tests
+ */
+export async function readPlatformAnalytics({ window = DEFAULT_WINDOW, now = Date.now(), sources = SOURCES } = {}) {
+ const windowKey = resolveWindow(window);
+ const sinceDay = windowStartDay(windowKey, now);
+
+ const names = Object.keys(sources);
+ const settled = await Promise.allSettled(
+ names.map((name) => withTimeout(Promise.resolve().then(() => sources[name](sinceDay, now)), SOURCE_TIMEOUT_MS, name)),
+ );
+ const results = {};
+ const failures = {};
+ settled.forEach((s, i) => {
+ if (s.status === 'fulfilled') results[names[i]] = s.value;
+ else failures[names[i]] = s.reason;
+ });
+
+ // The all-time window starts on the first day any source recorded activity.
+ let fromDay = sinceDay;
+ if (!fromDay) {
+ const first = Object.values(results)
+ .flatMap((r) => r.daily.map((d) => d.day))
+ .sort()[0];
+ fromDay = first || utcDayKey(now);
+ }
+ const days = dayRange(fromDay, now);
+
+ const metrics = {};
+ const errors = [];
+ for (const m of METRICS) {
+ const base = { key: m.key, label: m.label, unit: m.unit, method: m.method };
+ if (!m.source) {
+ metrics[m.key] = { ...base, available: false, pending: true, total: null, window_total: null, daily: null };
+ continue;
+ }
+ const r = results[m.source];
+ if (!r) {
+ const err = failures[m.source];
+ console.warn(`[platform-analytics] source ${m.source} failed`, err?.message || err);
+ errors.push({
+ metric: m.key,
+ source: m.source,
+ error: /timed out/.test(String(err?.message)) ? 'timeout' : 'query_failed',
+ message: `The ${m.label.toLowerCase()} figure could not be read, so it is shown as unavailable rather than as zero.`,
+ });
+ metrics[m.key] = { ...base, available: false, total: null, window_total: null, daily: null };
+ continue;
+ }
+ const daily = zeroFill(days, r.daily, m.key);
+ metrics[m.key] = {
+ ...base,
+ available: true,
+ total: tidy(r.total[m.key]),
+ window_total: tidy(daily.reduce((n, d) => n + d.value, 0)),
+ daily,
+ };
+ }
+
+ return {
+ window: windowKey,
+ window_days: days.length,
+ from: fromDay,
+ to: utcDayKey(now),
+ updated_at: new Date(now).toISOString(),
+ metrics,
+ errors,
+ };
+}
diff --git a/api/platform/analytics.js b/api/platform/analytics.js
new file mode 100644
index 000000000..05c44306e
--- /dev/null
+++ b/api/platform/analytics.js
@@ -0,0 +1,59 @@
+// GET /api/platform/analytics?window=30d|90d|all
+//
+// Every public three.ws platform total in one read, each with a zero-filled
+// daily series over the window and a `method` string that says how it was
+// counted. The data layer is api/_lib/platform-analytics.js; this handler adds
+// the shared cache, the CDN header and the rate limit.
+//
+// A failing sub-query yields `null` for its metrics plus an `errors` entry. The
+// page still renders every other number, so this endpoint answers 200 even
+// when a table is unreachable. A partial read is cached for 30 seconds only, so
+// a transient failure is not parked on the CDN for five minutes.
+
+import { cors, json, method, wrap, rateLimited } from '../_lib/http.js';
+import { limits, clientIp } from '../_lib/rate-limit.js';
+import { cacheGet, cacheSet } from '../_lib/cache.js';
+import { readPlatformAnalytics, resolveWindow } from '../_lib/platform-analytics.js';
+
+export const config = { runtime: 'nodejs' };
+
+const CACHE_TTL_S = 300;
+const PARTIAL_TTL_S = 30;
+const CACHE_VERSION = 'v1';
+
+const inflight = new Map();
+
+async function computeCached(windowKey) {
+ const key = `platform:analytics:${CACHE_VERSION}:${windowKey}`;
+ const hit = await cacheGet(key);
+ if (hit && typeof hit === 'object' && hit.metrics) return hit;
+ // Single-flight per window: a cache expiry under traffic fires one set of
+ // aggregate queries, not one per concurrent request.
+ if (!inflight.has(windowKey)) {
+ const p = readPlatformAnalytics({ window: windowKey })
+ .then(async (body) => {
+ await cacheSet(key, body, body.errors.length ? PARTIAL_TTL_S : CACHE_TTL_S);
+ return body;
+ })
+ .finally(() => inflight.delete(windowKey));
+ inflight.set(windowKey, p);
+ }
+ return inflight.get(windowKey);
+}
+
+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.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const url = new URL(req.url, 'http://localhost');
+ const windowKey = resolveWindow(url.searchParams.get('window'));
+ const body = await computeCached(windowKey);
+
+ const cacheControl = body.errors.length
+ ? `public, s-maxage=${PARTIAL_TTL_S}`
+ : `public, s-maxage=${CACHE_TTL_S}, stale-while-revalidate=600`;
+ return json(res, 200, body, { 'cache-control': cacheControl });
+});