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/healthz
// ----------------
// Lightweight liveness/readiness endpoint. Returns 200 with uptime + a small
// summary block compatible with the pump-dashboard's API status panel.
//
// Core health is always green (no hard DB dependency). Optional sub-probes
// (Resend, x402) are cached for 5 minutes and fail gracefully: a DB outage
// degrades the `x402` block but never the top-level `status: 'ok'`.
import { cors, json, method, wrap } from './_lib/http.js';
import { countRecentPayments } from './_lib/x402/audit-log.js';
import { gatherSubsystemHealth } from './_lib/ops/subsystem-health.js';
import { ttsConfigured, nvidiaAsrConfigured } from './_lib/ai-speech.js';
import { alertsConfigured } from './_lib/alerts.js';
const STARTED_AT = Date.now();
const VERSION = process.env.VERCEL_GIT_COMMIT_SHA || process.env.npm_package_version || 'dev';
const CACHE_TTL_MS = 5 * 60 * 1000;
const RESEND_CACHE_TTL_MS = CACHE_TTL_MS;
// The pumpfun-monitor cron runs every 3 min and upserts bot_heartbeat. Allow 2×
// the interval before declaring the worker stopped, so a single skipped tick
// doesn't flap the status.
const HEARTBEAT_FRESH_MS = 6 * 60 * 1000;
const MONITOR_CACHE_TTL_MS = 8 * 1000;
// Subsystem health is a live read of in-process breaker state + one DB ping.
// Cache it briefly so a burst of /healthz hits (dashboards poll it) doesn't fire
// a DB ping each, but keep the TTL short so a breaker tripping shows up fast.
const SUBSYSTEMS_CACHE_TTL_MS = 5 * 1000;
let _resendCache = { value: null, expiresAt: 0 };
let _x402Cache = { value: null, expiresAt: 0 };
let _monitorCache = { value: null, expiresAt: 0 };
let _subsystemsCache = { value: null, expiresAt: 0 };
// Exported for tests so each case starts with a cold cache.
export function _resetResendCache() {
_resendCache = { value: null, expiresAt: 0 };
}
export function _resetX402Cache() {
_x402Cache = { value: null, expiresAt: 0 };
}
export function _resetMonitorCache() {
_monitorCache = { value: null, expiresAt: 0 };
}
export function _resetSubsystemsCache() {
_subsystemsCache = { value: null, expiresAt: 0 };
}
// Live subsystem health (cache breaker, Helius breaker, ring invariants, DB
// ping, world). Cached SUBSYSTEMS_CACHE_TTL_MS. Defensive: gatherSubsystemHealth
// never throws, but wrap anyway so /healthz stays green even if it did.
async function probeSubsystems() {
const now = Date.now();
if (_subsystemsCache.value && _subsystemsCache.expiresAt > now) return _subsystemsCache.value;
let value;
try {
value = await gatherSubsystemHealth();
} catch {
value = { status: 'unknown', checkedAt: now, counts: {}, degraded: [], subsystems: [] };
}
_subsystemsCache = { value, expiresAt: now + SUBSYSTEMS_CACHE_TTL_MS };
return value;
}
// Real bot/monitor status, sourced from Postgres:
// running : a bot_heartbeat row written by the pumpfun-monitor cron within
// the freshness window. When no row exists yet (or the DB is
// unreachable, e.g. in unit tests) we fall back to the serverless
// liveness signal: the function answering IS a liveness proof.
// mode : the worker's reported mode (the cron writes 'cron').
// claimsDetected: count of real graduation events the monitor has recorded.
// watches.total : users with at least one alert rule armed (server-side
// watchers that fire even with no tab open).
async function probeMonitor() {
const now = Date.now();
if (_monitorCache.value && _monitorCache.expiresAt > now) return _monitorCache.value;
let value;
try {
const { sql } = await import('./_lib/db.js');
const [beat] = await sql`
SELECT mode, last_beat_at FROM bot_heartbeat
ORDER BY last_beat_at DESC LIMIT 1
`;
const [{ graduations }] = await sql`
SELECT count(*)::int AS graduations FROM pumpfun_graduations
`;
const [{ watches }] = await sql`
SELECT count(*)::int AS watches FROM pump_alert_rules WHERE enabled
`;
const beatMs = beat?.last_beat_at ? new Date(beat.last_beat_at).getTime() : 0;
const fresh = beatMs > 0 && now - beatMs < HEARTBEAT_FRESH_MS;
value = {
monitor: {
// If a heartbeat row exists, trust its freshness. If none exists yet,
// the dedicated worker hasn't reported: report the serverless API's
// own liveness rather than a false "stopped".
running: beat ? fresh : true,
mode: beat?.mode || 'serverless',
claimsDetected: graduations,
},
watches: { total: watches, active: watches },
};
} catch {
value = {
monitor: { running: true, mode: 'serverless', claimsDetected: 0 },
watches: { total: 0, active: 0 },
};
}
_monitorCache = { value, expiresAt: now + MONITOR_CACHE_TTL_MS };
return value;
}
async function probeResend() {
const now = Date.now();
if (_resendCache.value && _resendCache.expiresAt > now) {
return _resendCache.value;
}
const key = process.env.RESEND_API_KEY;
if (!key) {
_resendCache = { value: 'missing', expiresAt: now + RESEND_CACHE_TTL_MS };
return 'missing';
}
let result;
try {
const r = await fetch('https://api.resend.com/domains', {
method: 'GET',
headers: { Authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(3000),
});
if (r.ok) {
result = 'configured';
} else if (r.status === 401) {
// Send-only ("restricted") keys legitimately can't list domains.
const body = await r.text().catch(() => '');
result = body.includes('restricted_api_key') ? 'configured' : 'key_invalid';
} else if (r.status === 403) {
result = 'configured';
} else {
result = 'key_invalid';
}
} catch {
result = 'key_invalid';
}
_resendCache = { value: result, expiresAt: now + RESEND_CACHE_TTL_MS };
return result;
}
async function probeX402() {
const now = Date.now();
if (_x402Cache.value && _x402Cache.expiresAt > now) {
return _x402Cache.value;
}
const result = {};
// Check if PAY_TO addresses are configured. A network counts as wired only
// when EVERY field its 402 accept needs is present: the same gate
// buildRequirements() applies before advertising it. Solana additionally
// requires a fee payer (no default): without it the accept is dropped, so a
// Solana-only paid endpoint (e.g. /api/x402/club-cover) fails closed with a
// 500. Surfacing it here turns a silent door outage into a visible warning.
const hasSolanaPayTo = !!process.env.X402_PAY_TO_SOLANA || !!process.env.X402_PAY_TO;
const hasSolanaFeePayer = !!process.env.X402_FEE_PAYER_SOLANA;
const hasBase = !!process.env.X402_PAY_TO_BASE;
const hasSolana = hasSolanaPayTo && hasSolanaFeePayer;
result.configured = hasBase || hasSolana;
result.networks = [];
if (hasBase) result.networks.push('base');
if (hasSolana) result.networks.push('solana');
result.warnings = [];
if (hasSolanaPayTo && !hasSolanaFeePayer) {
result.warnings.push(
'solana_fee_payer_missing: X402_PAY_TO_SOLANA is set but X402_FEE_PAYER_SOLANA is not, ' +
'Solana accepts are dropped, breaking Solana-only paid endpoints (club-cover, dance-tip).',
);
}
// The 402 challenge advertises a Solana fee payer PUBKEY (X402_FEE_PAYER_SOLANA),
// but a sponsor-mode settle can only complete if the matching SECRET is loaded
// to co-sign: a config where the pubkey is set and the secret is not passes
// every check above yet 502s on every settle (observed: club-cover's last
// on-chain settles failed with `sponsor_key_unconfigured`). Probe the co-sign
// key so that false-green stops reading as healthy. No key material is exposed:
// loadFeePayerKeypair throws on missing/mismatched secret and we report only a
// status word.
if (hasSolana) {
try {
const { SELF_FACILITATOR_ENABLED, loadFeePayerKeypair } = await import('./_lib/x402/self-facilitator.js');
if (!SELF_FACILITATOR_ENABLED) {
result.sponsor_cosign = 'facilitator_disabled';
} else {
try {
loadFeePayerKeypair();
result.sponsor_cosign = 'ready';
} catch (err) {
const mismatch = /!=|expected 64 bytes|mismatch/i.test(String(err?.message || ''));
result.sponsor_cosign = mismatch ? 'mismatch' : 'missing';
result.warnings.push(
`sponsor_cosign_${result.sponsor_cosign}: the Solana fee-payer pubkey is advertised but its ` +
'co-signing secret cannot be loaded, so sponsor-mode settlements 502 (club-cover, dance-tip). ' +
'Set/repair X402_FEE_PAYER_SECRET_BASE58 in the deploy environment.',
);
}
}
} catch {
result.sponsor_cosign = 'unknown';
}
}
// Probe facilitator connectivity (cached at this level, 5 min TTL)
const facilitatorUrl = process.env.X402_CDP_FACILITATOR_URL || process.env.X402_FACILITATOR_URL_BASE;
if (facilitatorUrl) {
try {
const r = await fetch(facilitatorUrl + '/supported', {
method: 'GET',
headers: { accept: 'application/json' },
signal: AbortSignal.timeout(5000),
});
result.facilitator = r.ok ? 'reachable' : 'error_' + r.status;
} catch {
result.facilitator = 'unreachable';
}
} else {
result.facilitator = 'not_configured';
}
// Provider Hub (zauthx402) x402 telemetry: report whether the SDK
// initialized so the integration is observable in prod. Booleans only:
// no key material is surfaced on this public, unauthenticated endpoint.
try {
const { status: zauthStatus } = await import('./_lib/zauth.js');
const z = zauthStatus();
result.telemetry = {
provider: 'zauthx402',
configured: z.hasKey,
initialized: z.initialized,
};
} catch {
result.telemetry = { provider: 'zauthx402', configured: false, initialized: false };
}
// Recent payments from audit log
result.recent_payments = await countRecentPayments(60);
// Self-facilitator verify/settle outcomes (last 24h), grouped by reason
// class. A paying buyer whose wallet mutates the prepared transaction gets a
// deterministic verify 402 with everything else on this endpoint green,
// without this block that failure mode is invisible outside the raw
// facilitator log. Only the reason prefix (before ':') is exposed: suffixes can
// carry wallet addresses, the prefix is a fixed validator code.
try {
const { sql } = await import('./_lib/db.js');
const rows = await sql`
SELECT action, ok, split_part(coalesce(reject_reason, ''), ':', 1) AS reason,
count(*)::int AS n
FROM x402_self_facilitator_log
WHERE ts > now() - interval '24 hours'
GROUP BY 1, 2, 3
ORDER BY n DESC
LIMIT 20
`;
const block = {
verify: { ok: 0, rejected: 0, reject_reasons: {} },
settle: { ok: 0, failed: 0, fail_reasons: {} },
};
for (const r of rows) {
const side = r.action === 'settle' ? block.settle : block.verify;
if (r.ok) {
side.ok += r.n;
} else if (r.action === 'settle') {
side.failed += r.n;
if (r.reason) side.fail_reasons[r.reason] = (side.fail_reasons[r.reason] || 0) + r.n;
} else {
side.rejected += r.n;
if (r.reason) side.reject_reasons[r.reason] = (side.reject_reasons[r.reason] || 0) + r.n;
}
}
result.self_facilitator = block;
} catch {
result.self_facilitator = 'unavailable';
}
// SIWX reachability (just check if the table exists)
try {
await (await import('./_lib/db.js')).sql`
SELECT 1 FROM siwx_payments LIMIT 1
`;
result.siwx = 'reachable';
} catch {
result.siwx = 'unavailable';
}
// Ring spend status: surface whether the autonomous closed-loop spend path is
// live as a dashboard field, so a fail-closed guard (or a deliberate pause) is
// visible here instead of only as recurring cron error logs. checkRingInvariants
// is a pure env read (no I/O); no key material is exposed, only flag names.
// `paused` reflects the existing kill switch (X402_AUTONOMOUS_ENABLED=false),
// which the loop honors before the guard check, so a deliberate pause reads as
// paused here, not as a violation.
try {
const { checkRingInvariants } = await import('./_lib/x402/ring-allowlist.js');
const inv = checkRingInvariants();
const paused = process.env.X402_AUTONOMOUS_ENABLED === 'false';
result.ring = {
spend_enabled: inv.ok && !paused,
paused,
violations: paused ? [] : inv.violations.map((v) => v.flag),
};
} catch {
result.ring = { spend_enabled: false, status: 'unavailable' };
}
_x402Cache = { value: result, expiresAt: now + CACHE_TTL_MS };
return result;
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const uptimeMs = Date.now() - STARTED_AT;
const [resend, x402, monitorBlock, subsystems] = await Promise.all([
probeResend(),
probeX402(),
probeMonitor(),
probeSubsystems(),
]);
return json(res, 200, {
// Top-level liveness stays 'ok' (this function answering IS liveness); the
// `subsystems` block carries the real health verdict so a degraded
// dependency is visible without ever making the liveness probe flap.
status: 'ok',
service: '3d-agent',
version: VERSION,
uptime: Math.floor(uptimeMs / 1000),
uptimeMs,
resend,
x402,
// Real bot/monitor status for the pump-dashboard stat cards (see
// probeMonitor). Falls back to serverless liveness when no worker
// heartbeat exists or the DB is unreachable.
monitor: monitorBlock.monitor,
watches: monitorBlock.watches,
// Live internal-dependency health: the exact degradation the reachability
// probe can't see (Redis on memory-fallback, ring half-armed, Helius
// throttled, DB slow, world unprotected). See api/_lib/ops/subsystem-health.js.
subsystems,
// Productized speech package (api/v1/ai/tts, api/v1/ai/asr). Honest env-gate
// status so a missing NVIDIA key shows here instead of only surfacing as a
// 503 on the endpoint. Sync env reads, no upstream probe, no key material.
speech: {
tts: { configured: ttsConfigured(), route: '/api/v1/ai/tts', requires: ['NVIDIA_API_KEY or GOOGLE_CLOUD_PROJECT'] },
asr: {
configured: nvidiaAsrConfigured(),
route: '/api/v1/ai/asr',
requires: ['NVIDIA_API_KEY', 'NVIDIA_ASR_FUNCTION_ID'],
},
},
// Ops alerts (api/_lib/alerts.js). Every sendOpsAlert() ALWAYS persists to
// the ops_alerts table, so alerts are never silently dropped; read them via
// the ops-secret-gated /api/ops/health surface. Telegram is an OPTIONAL
// extra push for real-time notification; its absence is expected, not a fault.
alerts: {
primary: 'ops_alerts',
read_via: '/api/ops/health',
telegram_push: alertsConfigured() ? 'enabled' : 'disabled',
telegram_requires: ['TELEGRAM_BOT_TOKEN', 'TELEGRAM_ALERTS_CHAT_ID'],
},
}, { 'cache-control': 'public, max-age=2, s-maxage=2' });
});