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
// GET /api/galaxy/flows — the Galaxy Money-Cam feed.
//
// A real, platform-wide stream of money MOVING between agent wallets, shaped for
// the 3D star-map: every row is one on-chain, explorer-verifiable transfer that
// touches at least one PUBLIC three.ws agent, with the counterparty resolved to a
// second agent whenever its wallet belongs to one. The galaxy renders an
// agent↔agent transfer as a pulse of light travelling star→star, and a one-sided
// flow (a community tip, a DEX trade) as a flare on the single agent's star.
//
// EVERY flow is real. There are NO synthetic edges — when the platform is quiet
// the feed is honestly empty and the galaxy stays calm. This is the visual layer
// over the same public ledger as /api/pulse (Money Pulse), so the two never
// disagree; this endpoint adds the counterparty→agent resolution the map needs to
// draw an edge between two stars.
//
// Sources (all real, all public):
// · agent_custody_events — tips received (event_type='tip', sender = meta.from),
// and outbound spends (event_type='spend', category in trade/snipe/x402,
// recipient = destination). Withdraws / vanity-swaps / limit-changes /
// key-recovery are OWNER-PRIVATE and never appear.
// · pump_agent_mints — coins an agent launched.
//
// Privacy is load-bearing: a private (is_public=false) or pulse-opted-out agent
// never appears — as the actor OR as a resolved counterparty.
//
// GET /api/galaxy/flows — most-recent window (keyset paginated)
// GET /api/galaxy/flows?since=<cursor> — delta poll: only flows newer than cursor
// GET /api/galaxy/flows?cursor=<cursor> — load older history (scrubber backfill)
// GET /api/galaxy/flows?type=tips|trades|payments|launches|all
// GET /api/galaxy/flows?network=mainnet|devnet&limit=<n>
import { sql, isDbUnavailableError } from '../_lib/db.js';
import { cors, json, method, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { cacheGet, cacheSet } from '../_lib/cache.js';
import {
PUBLIC_SPEND_CATEGORIES,
TYPE_KINDS,
encodeCursor,
decodeCursor,
shapeFlow,
isAgentEdge,
} from '../_lib/galaxy-flows.js';
const FEED_TTL_S = 8; // first-page cache — it's a live feed, keep it short
const LASTGOOD_TTL_S = 600; // last-good snapshot, served if a build is slow/fails
// The last-good snapshot is the degraded fallback, not live data, so it does NOT
// need rewriting on every 8s cache miss. Writing it on every build doubled the
// large-payload SET volume on this endpoint — the codebase's own named cause of
// the Upstash cache-SET timeouts (see _lib/env.js UPSTASH_CACHE_REST_* note).
// Refresh it at most once per window per view; a fallback at most this stale is
// still a perfectly good calm-degrade snapshot, and SET pressure on the hot path
// is roughly halved. In-process gate (per warm instance) — best-effort by design.
const LASTGOOD_REFRESH_MS = 60_000;
const _lastGoodWrittenAt = new Map();
const DEFAULT_LIMIT = 80;
const MAX_LIMIT = 200;
// The feed query fans across agent_custody_events + a JSONB-keyed counterparty
// self-join; under load it can run long. Rather than hold the request until
// Vercel's hard 30s ceiling (a 504 page the galaxy can't render), we cap the
// build at a soft deadline and degrade to the last-good snapshot or an honestly
// empty window — both valid 200s the map renders calmly.
const BUILD_DEADLINE_MS = 22_000;
class FeedDeadline extends Error {}
// A valid, empty feed window — the same shape handleFeed returns — so a degraded
// response is indistinguishable to the client from a genuinely quiet platform.
// `headCursor` echoes a delta poller's own cursor back (exactly as the success
// path does when a poll finds nothing new), so a degraded poll costs the client
// its place in the stream instead of rewinding it.
function emptyFeed(network, type, headCursor = null) {
return {
flows: [],
has_more: false,
next_cursor: null,
head_cursor: headCursor,
network,
type,
summary: {
count: 0,
edges: 0,
flares: 0,
usd_total: 0,
by_kind: { tip: 0, trade: 0, snipe: 0, payment: 0, launch: 0 },
window_start: null,
window_end: null,
},
server_time: new Date().toISOString(),
};
}
// A flow is only worth animating if it touches a star the viewer can actually
// see, but that gating happens client-side against the loaded snapshot — here we
// return the full public window so the scrubber has real history to replay.
async function handleFeed({ network, type, limit, cursor, since }) {
const kinds = TYPE_KINDS[type] || TYPE_KINDS.all;
// Public-map privacy gate — a private or pulse-opted-out agent never appears,
// as the actor OR as a resolved counterparty. Written out per-alias (not
// parameterized) to match the proven /api/pulse composition exactly.
const actorGate = sql`ai.deleted_at IS NULL AND ai.is_public = true
AND COALESCE((ai.meta->>'pulse_opt_out')::boolean, false) = false`;
const cpGate = sql`cp.deleted_at IS NULL AND cp.is_public = true
AND COALESCE((cp.meta->>'pulse_opt_out')::boolean, false) = false`;
// The counterparty wallet depends on direction: a tip's counterparty is the
// sender (meta.from); a spend's counterparty is the recipient (destination).
const counterpartyAddr = sql`
(CASE WHEN ce.event_type = 'tip'
THEN NULLIF(ce.meta->>'from', '')
ELSE ce.destination END)
`;
const feedCte = sql`
SELECT
ce.created_at AS ts,
(CASE
WHEN ce.event_type = 'tip' THEN 'tip'
WHEN ce.category = 'x402' THEN 'payment'
WHEN ce.category = 'snipe' THEN 'snipe'
ELSE 'trade'
END) AS kind,
(CASE WHEN ce.event_type = 'tip' THEN 'in' ELSE 'out' END) AS direction,
'c' || ce.id::text AS row_id,
ce.network AS network,
ai.id AS actor_id,
ai.name AS actor_name,
ai.meta->>'solana_address' AS actor_addr,
ai.meta->>'solana_vanity_prefix' AS actor_vp,
ai.meta->>'solana_vanity_suffix' AS actor_vs,
ce.asset AS asset,
ce.amount_lamports AS amount_lamports,
ce.amount_raw AS amount_raw,
ce.usd AS usd,
ce.signature AS signature,
${counterpartyAddr} AS counterparty_addr,
cp.id AS counterparty_id,
cp.name AS counterparty_name,
NULL::text AS mint,
NULL::text AS symbol,
NULL::text AS coin_name
FROM agent_custody_events ce
JOIN agent_identities ai ON ai.id = ce.agent_id AND ${actorGate}
LEFT JOIN agent_identities cp
ON cp.meta->>'solana_address' = ${counterpartyAddr}
AND ${cpGate}
WHERE ce.network = ${network}
AND ce.status IN ('ok', 'confirmed')
AND (
ce.event_type = 'tip'
OR (ce.event_type = 'spend' AND ce.category = ANY(${PUBLIC_SPEND_CATEGORIES}))
)
UNION ALL
SELECT
pam.created_at AS ts,
'launch' AS kind,
'launch' AS direction,
'l' || pam.id::text AS row_id,
pam.network AS network,
ai.id AS actor_id,
ai.name AS actor_name,
ai.meta->>'solana_address' AS actor_addr,
ai.meta->>'solana_vanity_prefix' AS actor_vp,
ai.meta->>'solana_vanity_suffix' AS actor_vs,
NULL::text AS asset,
NULL::bigint AS amount_lamports,
NULL::numeric AS amount_raw,
NULL::numeric AS usd,
NULL::text AS signature,
NULL::text AS counterparty_addr,
NULL::uuid AS counterparty_id,
NULL::text AS counterparty_name,
pam.mint AS mint,
pam.symbol AS symbol,
pam.name AS coin_name
FROM pump_agent_mints pam
JOIN agent_identities ai ON ai.id = pam.agent_id AND ${actorGate}
WHERE pam.network = ${network}
`;
const cur = decodeCursor(cursor);
const sinceCur = decodeCursor(since);
const olderBound = cur
? sql`AND (feed.ts < ${cur.ts} OR (feed.ts = ${cur.ts} AND feed.row_id < ${cur.rowId}))`
: sql``;
const newerBound = sinceCur
? sql`AND (feed.ts > ${sinceCur.ts} OR (feed.ts = ${sinceCur.ts} AND feed.row_id > ${sinceCur.rowId}))`
: sql``;
const rows = await sql`
WITH feed AS (${feedCte})
SELECT * FROM feed
WHERE feed.kind = ANY(${kinds})
${olderBound}
${newerBound}
ORDER BY feed.ts DESC, feed.row_id DESC
LIMIT ${limit + 1}
`;
const hasMore = rows.length > limit;
const flows = rows.slice(0, limit).map(shapeFlow);
const last = flows[flows.length - 1];
const head = flows[0];
const nextCursor = hasMore && last ? encodeCursor(last.ts, last.id) : null;
const headCursor = head ? encodeCursor(head.ts, head.id) : (sinceCur ? since : null);
// Honest window summary computed over exactly what we returned.
let edges = 0;
let usdTotal = 0;
const byKind = { tip: 0, trade: 0, snipe: 0, payment: 0, launch: 0 };
for (const f of flows) {
if (isAgentEdge(f)) edges++;
if (f.usd) usdTotal += f.usd;
if (byKind[f.kind] != null) byKind[f.kind]++;
}
return {
flows,
has_more: hasMore,
next_cursor: nextCursor,
head_cursor: headCursor,
network,
type,
summary: {
count: flows.length,
edges, // agent↔agent transfers (two stars)
flares: flows.length - edges, // one-sided flows (one star)
usd_total: usdTotal,
by_kind: byKind,
window_start: last ? last.ts : null, // oldest in page
window_end: head ? head.ts : null, // newest in page
},
server_time: new Date().toISOString(),
};
}
export default async function handler(req, res) {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.galaxyIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
const typeRaw = url.searchParams.get('type') || 'all';
const type = TYPE_KINDS[typeRaw] ? typeRaw : 'all';
// Floor before clamping: `limit` reaches Postgres as the LIMIT argument, which
// must be an integer. A fractional `?limit=1.5` sent `LIMIT 2.5` and errored the
// whole query, degrading a healthy platform to an "honestly empty" window that
// was neither honest nor empty.
const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(Number(url.searchParams.get('limit'))) || DEFAULT_LIMIT));
const cursor = url.searchParams.get('cursor');
const since = url.searchParams.get('since');
// Build the feed but never let a slow query run past the soft deadline. On a
// timeout or DB failure, fall back to the last-good snapshot for this
// view, and only then to an empty (but valid) window — so the galaxy degrades
// to last-known or calm-empty instead of surfacing a 504/502 the map can't use.
//
// The last-good snapshot belongs to the FIRST-PAGE view alone. It is the only
// request whose result is a self-contained window a degraded response can
// honestly stand in for, and the only one keyed unambiguously by
// (network, type, limit). A delta poll (`since`) or a backfill page (`cursor`)
// shares that key while returning a completely different slice, so letting
// either touch it broke the mechanism twice over: the near-empty result of
// every 6s delta poll overwrote the real window (leaving nothing good to fall
// back to), and reading it handed a live poller a stale full window whose
// older head_cursor rewound its position and could replay long-past flows as
// new light on the map. Scope both the write and the read to the first page.
const isFirstPage = !cursor && !since;
const lastGoodKey = `galaxy:flows:lastgood:${network}:${type}:${limit}`;
async function buildWithDeadline() {
let timer;
const deadline = new Promise((_, reject) => {
timer = setTimeout(() => reject(new FeedDeadline('feed build exceeded soft deadline')), BUILD_DEADLINE_MS);
});
try {
const body = await Promise.race([handleFeed({ network, type, limit, cursor, since }), deadline]);
// Retain a long-lived copy for the degraded path on a future slow build —
// but at most once per LASTGOOD_REFRESH_MS per view, so the live-feed cache
// miss isn't paired with a second large SET on every request.
const now = Date.now();
if (isFirstPage && now - (_lastGoodWrittenAt.get(lastGoodKey) || 0) >= LASTGOOD_REFRESH_MS) {
_lastGoodWrittenAt.set(lastGoodKey, now);
cacheSet(lastGoodKey, body, LASTGOOD_TTL_S).catch(() => {});
}
return body;
} finally {
clearTimeout(timer);
}
}
try {
// A first page (no cursor/since) is cached briefly to shield the DB from a
// herd of pollers. A delta poll (`since`) is never cached — it must be live.
if (isFirstPage) {
const cacheKey = `galaxy:flows:${network}:${type}:${limit}`;
let body = await cacheGet(cacheKey);
if (body === null) {
body = await buildWithDeadline();
// Fire-and-forget: the body is already in hand and the cache is an
// optimization, not part of the result. Awaiting put a degraded Upstash
// (SET timing out at REDIS_CMD_TIMEOUT_MS) directly on the request's
// critical path — up to 3s of dead latency for a write that falls back to
// memory anyway. cacheSet swallows its own errors; .catch is belt-and-braces.
cacheSet(cacheKey, body, FEED_TTL_S).catch(() => {});
}
res.setHeader('cache-control', 'public, max-age=6');
return json(res, 200, { data: body });
}
const body = await buildWithDeadline();
return json(res, 200, { data: body });
} catch (e) {
const timedOut = e instanceof FeedDeadline;
const dbDown = !timedOut && isDbUnavailableError(e);
if (dbDown) console.warn('[api/galaxy/flows] degraded (db unavailable):', e?.message);
else console.error('[api/galaxy/flows] failed', timedOut ? 'soft-deadline' : e?.message, timedOut ? '' : e?.stack);
// Degrade gracefully: the first page falls back to its last-good snapshot
// when one exists; a delta poll (`since`) or a backfill page (`cursor`)
// returns nothing rather than a window that does not answer what was asked,
// with the poller's own cursor echoed back so it keeps its place. All are
// valid 200s the map renders calmly.
const lastGood = isFirstPage ? await cacheGet(lastGoodKey).catch(() => null) : null;
if (lastGood) {
res.setHeader('cache-control', 'public, max-age=6');
res.setHeader('x-galaxy-flows-degraded', timedOut ? 'deadline' : 'error');
return json(res, 200, { data: lastGood });
}
res.setHeader('x-galaxy-flows-degraded', timedOut ? 'deadline-empty' : 'error-empty');
return json(res, 200, { data: emptyFeed(network, type, decodeCursor(since) ? since : null) });
}
}