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/ibm/twin?token=<mint>|pool=<addr>[&timeframe=hour&aggregate=1]
// GET /api/ibm/twin?list=trending
// POST /api/ibm/twin { token|pool, network?, timeframe?, aggregate?, scenario }
// --------------------------------------------------------------------------
// The Digital Twin: a living virtual replica of a real Solana market. Unlike the
// one-shot Granite Oracle, the twin (1) mirrors its real-time vitals from live
// on-chain telemetry, (2) carries an IBM Granite TimeSeries model that projects
// its near future, (3) validates itself by back-testing that model against
// reality, and (4) lets you run real what-if simulations — perturbing the twin's
// recent history and re-forecasting so you can see how its trajectory bends.
//
// Candles come keyless from GeckoTerminal and are ALWAYS returned, so the twin's
// vitals + chart render from real history even when watsonx is not configured.
// The Granite projection, fidelity back-test, first-person persona, and Guardian
// governance appear only when watsonx.ai is reachable. There is no mock path: a
// scenario forecast is the real Granite model evaluating a transformed-but-real
// input series, clearly labelled as a counterfactual.
import { cors, json, method, wrap, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { watsonxConfig, watsonxChatComplete } from '../_lib/watsonx.js';
import { watsonxForecast, forecastModelFor } from '../_lib/watsonx-forecast.js';
import { guardianConfig, assessRisk } from '../_lib/granite-guardian.js';
import { fetchOhlcv, topPoolForToken, trendingPools } from '../_lib/market/ohlcv.js';
import {
callMarket,
isMarketUpstreamError,
marketUpstreamError,
} from '../_lib/market/upstream-error.js';
const isBase58 = (s) => /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(s);
const isoOf = (unixSec) => new Date(unixSec * 1000).toISOString();
const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
const HORIZON = 96; // every Granite TTM model forecasts 96 steps ahead
// ── Vitals: the twin's biometrics, computed from real OHLCV (no watsonx) ──────
function avg(arr) {
return arr.length ? arr.reduce((s, x) => s + x, 0) / arr.length : 0;
}
function stddev(arr) {
if (arr.length < 2) return 0;
const m = avg(arr);
return Math.sqrt(arr.reduce((s, x) => s + (x - m) ** 2, 0) / (arr.length - 1));
}
function logReturns(values) {
const r = [];
for (let i = 1; i < values.length; i++) {
if (values[i - 1] > 0 && values[i] > 0) r.push(Math.log(values[i] / values[i - 1]));
}
return r;
}
function pctChange(from, to) {
return from ? ((to - from) / from) * 100 : 0;
}
// Classify the twin's "state" from its vitals — drives hue + avatar emotion.
function twinState({ momentumPct, volatilityPct, activityRatio }) {
if (activityRatio < 0.25) return { key: 'dormant', label: 'Dormant', emotion: 'patience' };
if (volatilityPct >= 5) {
return momentumPct >= 0
? { key: 'euphoric', label: 'Euphoric', emotion: 'celebration' }
: { key: 'stressed', label: 'Stressed', emotion: 'concern' };
}
if (momentumPct >= 3) return { key: 'ascending', label: 'Ascending', emotion: 'curiosity' };
if (momentumPct <= -3) return { key: 'declining', label: 'Declining', emotion: 'empathy' };
return { key: 'calm', label: 'Calm', emotion: 'patience' };
}
function computeVitals(candles) {
const closes = candles.map((c) => c.c);
const vols = candles.map((c) => (Number.isFinite(c.v) ? c.v : 0));
const n = closes.length;
const currentPrice = closes[n - 1];
const momWindow = Math.min(24, n - 1);
const momentumPct = pctChange(closes[n - 1 - momWindow], currentPrice);
const dayWindow = Math.min(24, n - 1);
const change24hPct = pctChange(closes[n - 1 - dayWindow], currentPrice);
const volWindow = Math.min(48, n - 1);
const volatilityPct = stddev(logReturns(closes.slice(-volWindow - 1))) * 100;
const recentVol = avg(vols.slice(-6));
const baseVol = avg(vols.slice(-Math.min(48, n))) || 1;
const activityRatio = recentVol / baseVol;
const heartbeatBpm = Math.round(clamp(60 * activityRatio, 28, 184));
const priorVol = avg(vols.slice(-Math.min(48, n), -24)) || baseVol;
const volumeTrendPct = pctChange(priorVol, avg(vols.slice(-24)) || baseVol);
const state = twinState({ momentumPct, volatilityPct, activityRatio });
return {
currentPrice,
momentumPct,
change24hPct,
volatilityPct,
activityRatio,
heartbeatBpm,
liquidityUsd: baseVol,
volumeTrendPct,
// Normalised, viz-ready control signals in tidy ranges.
signals: {
trend: clamp(Math.tanh(momentumPct / 15), -1, 1),
momentum: clamp(momentumPct / 30, -1, 1),
volatility: clamp(volatilityPct / 8, 0, 1),
activity: clamp(activityRatio / 2, 0, 1),
},
state,
};
}
// ── Forecast helpers ─────────────────────────────────────────────────────────
// TTM requires the input length to equal the model's context window, so pick the
// largest window the history can fill and send exactly that many points.
function contextLenFor(historyLength) {
if (historyLength >= 1536) return 1536;
if (historyLength >= 1024) return 1024;
return 512;
}
function pointsFrom(fc) {
return fc.timestamps.map((iso, i) => ({
t: Math.floor(Date.parse(iso) / 1000),
c: Number(fc.values[i]),
}));
}
function forecastStats(currentPrice, points, timeframe, aggregate) {
const end = points[points.length - 1]?.c ?? currentPrice;
const fv = points.map((p) => p.c).filter(Number.isFinite);
return {
currentPrice,
end,
low: Math.min(...fv),
high: Math.max(...fv),
changePct: pctChange(currentPrice, end),
direction: end > currentPrice ? 'up' : end < currentPrice ? 'down' : 'flat',
horizonHours: timeframe === 'hour' ? points.length * aggregate : points.length,
};
}
// Mean absolute percentage error + a directional hit, comparing a back-test
// forecast against the candles that actually came to pass.
function fidelityOf(realized, predicted, cutoffPrice) {
const k = Math.min(realized.length, predicted.length);
let sumApe = 0;
let cnt = 0;
for (let i = 0; i < k; i++) {
const a = realized[i].c;
const p = predicted[i].c;
if (a > 0 && Number.isFinite(p)) {
sumApe += Math.abs((p - a) / a);
cnt++;
}
}
const mapePct = cnt ? (sumApe / cnt) * 100 : null;
const realUp = realized[k - 1].c >= cutoffPrice;
const predUp = predicted[k - 1].c >= cutoffPrice;
return {
mapePct,
accuracyPct: mapePct == null ? null : clamp(100 - mapePct, 0, 100),
directionalHit: realUp === predUp,
};
}
// ── What-if scenario: a real, deterministic perturbation of the input tail ────
// Reshapes the last ~12% of the conditioning window, then the genuine Granite
// model projects forward from it. This is the twin's counterfactual, not a mock.
function clampScenario(raw = {}) {
return {
priceShockPct: clamp(Number(raw.priceShockPct) || 0, -90, 300),
volatilityScale: clamp(Number(raw.volatilityScale) || 1, 0.1, 5),
momentumFlip: Boolean(raw.momentumFlip),
};
}
function scenarioLabel(s) {
const parts = [];
if (s.priceShockPct)
parts.push(`${s.priceShockPct > 0 ? '+' : ''}${s.priceShockPct}% demand shock`);
if (s.volatilityScale !== 1) parts.push(`${s.volatilityScale}× volatility`);
if (s.momentumFlip) parts.push('momentum reversal');
return parts.length ? parts.join(' · ') : 'baseline (no perturbation)';
}
function applyScenario(values, s) {
const w = Math.min(values.length, Math.max(8, Math.round(values.length * 0.12)));
const start = values.length - w;
const windowMean = avg(values.slice(start));
const anchor = values[start];
const out = values.slice();
for (let i = start; i < values.length; i++) {
const f = (i - start) / Math.max(1, w - 1); // 0 → 1 ramp toward "now"
let v = out[i];
if (s.volatilityScale !== 1) v = windowMean + (v - windowMean) * s.volatilityScale;
if (s.momentumFlip) v = anchor - (v - anchor); // mirror the recent move
if (s.priceShockPct) v = v * (1 + (s.priceShockPct / 100) * f);
out[i] = Math.max(v, 1e-12); // keep strictly positive for the model
}
return out;
}
// ── Granite persona: the twin narrates itself, governed by Guardian ──────────
async function narratePersona(cfg, system, user) {
const { text, model } = await watsonxChatComplete(cfg, {
messages: [
{ role: 'system', content: system },
{ role: 'user', content: user },
],
maxTokens: 170,
temperature: 0.65,
});
return { text: (text || '').trim(), model };
}
async function governPersona(text) {
const gcfg = guardianConfig();
if (!gcfg.configured || !text) return null;
try {
const g = await assessRisk(gcfg, { risk: 'harm', input: text });
return {
passed: !g.flagged,
risk: g.risk,
label: g.label,
probability: g.probability ?? null,
};
} catch (e) {
return { passed: null, error: String(e.message || e) };
}
}
const PERSONA_SYSTEM =
'You are a Digital Twin: an embodied AI replica of a live crypto market on three.ws that ' +
'speaks in the first person as the asset itself ("I"). You are given your own real vitals and ' +
'an IBM Granite TimeSeries projection of your near future. Reply in exactly two short, vivid ' +
'sentences. State how you feel (your state) and where Granite projects you are heading ' +
'(direction, magnitude, horizon). No financial advice, no hashtags, no emojis, and never ' +
'invent numbers beyond those you are given.';
// ── Shared series loader ──────────────────────────────────────────────────────
async function loadSeries(params) {
const network = (params.network || 'solana').trim();
let pool = (params.pool || '').trim();
const token = (params.token || '').trim();
if (!pool && token) {
if (!isBase58(token))
throw Object.assign(new Error('token must be a base58 mint'), {
status: 400,
code: 'bad_token',
});
pool = await callMarket(() => topPoolForToken(token, network));
}
if (!pool || !isBase58(pool)) {
throw Object.assign(new Error('provide ?pool=<addr> or ?token=<mint>, or ?list=trending'), {
status: 400,
code: 'bad_request',
});
}
const timeframe = ['minute', 'hour', 'day'].includes(params.timeframe)
? params.timeframe
: 'hour';
const aggregate = clamp(parseInt(params.aggregate || '1', 10) || 1, 1, 60);
const { candles, base, quote, freq } = await callMarket(() =>
fetchOhlcv({ pool, network, timeframe, aggregate, limit: 1000 }),
);
if (candles.length < 64) {
throw Object.assign(new Error('not enough candle history to model this pool'), {
status: 422,
code: 'insufficient_history',
});
}
const token_ = {
name: base?.name || 'Token',
symbol: base?.symbol || '',
quoteSymbol: quote?.symbol || 'USD',
pool,
network,
};
return { candles, token: token_, freq, timeframe, aggregate };
}
// ── GET: the live twin snapshot ───────────────────────────────────────────────
async function handleGet(req, res) {
const params = Object.fromEntries(new URL(req.url, 'http://x').searchParams);
if (params.list === 'trending') {
const pools = await callMarket(() => trendingPools('solana', 8));
return json(res, 200, { pools }, { 'cache-control': 'public, max-age=30, s-maxage=60' });
}
const { candles, token, freq, timeframe, aggregate } = await loadSeries(params);
const vitals = computeVitals(candles);
const out = {
token,
timeframe,
aggregate,
freq,
history: candles.map((c) => ({ t: c.t, c: c.c })),
vitals,
projection: null,
fidelity: null,
persona: null,
governance: null,
ibm: { configured: false },
generatedAt: new Date().toISOString(),
};
const cfg = watsonxConfig();
if (!cfg.configured) {
out.ibm = { configured: false, reason: 'WATSONX_API_KEY + project not set' };
return json(res, 200, out, { 'cache-control': 'public, max-age=20, s-maxage=30' });
}
if (candles.length < 512) {
out.ibm = {
configured: true,
error: `need ≥512 candles for Granite TimeSeries, have ${candles.length}`,
};
return json(res, 200, out, { 'cache-control': 'public, max-age=20' });
}
const ctxLen = contextLenFor(candles.length);
const proj = candles.slice(-ctxLen);
const projModel = forecastModelFor(ctxLen);
// Back-test: forecast on the window ending HORIZON candles ago, then compare
// against the candles that actually followed. Needs ctx + HORIZON of history.
const canBacktest = candles.length >= ctxLen + HORIZON;
const btSlice = canBacktest ? candles.slice(0, candles.length - HORIZON).slice(-ctxLen) : null;
const realized = canBacktest ? candles.slice(candles.length - HORIZON) : null;
try {
const [projFc, btFc] = await Promise.all([
watsonxForecast(cfg, {
model: projModel,
timestamps: proj.map((c) => isoOf(c.t)),
values: proj.map((c) => c.c),
freq,
targetColumn: 'price',
}),
btSlice
? watsonxForecast(cfg, {
model: forecastModelFor(btSlice.length),
timestamps: btSlice.map((c) => isoOf(c.t)),
values: btSlice.map((c) => c.c),
freq,
targetColumn: 'price',
}).catch(() => null)
: Promise.resolve(null),
]);
const points = pointsFrom(projFc);
const stats = forecastStats(vitals.currentPrice, points, timeframe, aggregate);
out.projection = { points, stats, model: projFc.model };
out.ibm = {
configured: true,
forecastModel: projFc.model,
inputWindow: projFc.inputWindow,
};
// An empty predicted series (a forecast that answers with no points) would
// make fidelityOf index realized[-1] and throw, and that throw lands in the
// outer catch below, which replaces the good `ibm` block with an error and
// skips the persona entirely. A back-test with nothing to score simply has
// no fidelity to report.
const predicted = btFc && realized ? pointsFrom(btFc) : null;
if (predicted?.length) {
const cutoffPrice = btSlice[btSlice.length - 1].c;
const f = fidelityOf(realized, predicted, cutoffPrice);
out.fidelity = {
horizonHours: timeframe === 'hour' ? HORIZON * aggregate : HORIZON,
mapePct: f.mapePct,
accuracyPct: f.accuracyPct,
directionalHit: f.directionalHit,
cutoffPrice,
realized: realized.map((c) => ({ t: c.t, c: c.c })),
predicted,
model: btFc.model,
};
}
// First-person persona + Guardian governance (best-effort).
try {
const user =
`I am the digital twin of ${token.name}${token.symbol ? ` (${token.symbol})` : ''}. ` +
`My current price is $${vitals.currentPrice.toPrecision(6)}. My state is ${vitals.state.label} ` +
`(momentum ${vitals.momentumPct.toFixed(1)}% over the last ${Math.min(24, candles.length)} bars, ` +
`volatility ${vitals.volatilityPct.toFixed(2)}% per bar, activity ${vitals.activityRatio.toFixed(2)}× normal). ` +
`IBM Granite TimeSeries projects my price moving ${stats.direction} by ${stats.changePct.toFixed(1)}% ` +
`over the next ${stats.horizonHours} hours (low $${stats.low.toPrecision(6)}, high $${stats.high.toPrecision(6)}). ` +
`Speak as me.`;
const persona = await narratePersona(cfg, PERSONA_SYSTEM, user);
out.persona = persona;
out.governance = await governPersona(persona.text);
} catch (pErr) {
out.persona = { text: '', error: String(pErr.message || pErr) };
}
} catch (fErr) {
out.ibm = { configured: true, error: String(fErr.message || fErr) };
}
return json(res, 200, out, { 'cache-control': 'public, max-age=20, s-maxage=30' });
}
// ── POST: a what-if simulation ────────────────────────────────────────────────
async function handlePost(req, res) {
// `null`, a bare string, or a number is valid JSON, and readJson hands it back
// as-is on the raw-stream path (Vercel-style invocation, the MCP server, a
// direct handler call). Reading params off it throws a TypeError that surfaces
// as a sanitized 500, when malformed input belongs in the documented 4xx
// contract. Collapsing a non-object to {} routes it through the normal
// bad_request path instead.
const parsed = await readJson(req);
const body = parsed && typeof parsed === 'object' ? parsed : {};
const { candles, token, freq, timeframe, aggregate } = await loadSeries(body);
const scenario = clampScenario(body.scenario);
const label = scenarioLabel(scenario);
const out = {
token,
timeframe,
aggregate,
freq,
scenario: { ...scenario, label },
baseline: null,
simulated: null,
divergence: null,
persona: null,
governance: null,
ibm: { configured: false },
generatedAt: new Date().toISOString(),
};
const cfg = watsonxConfig();
if (!cfg.configured) {
out.ibm = { configured: false, reason: 'WATSONX_API_KEY + project not set' };
return json(res, 200, out);
}
if (candles.length < 512) {
out.ibm = {
configured: true,
error: `need ≥512 candles for Granite TimeSeries, have ${candles.length}`,
};
return json(res, 200, out);
}
const ctxLen = contextLenFor(candles.length);
const slice = candles.slice(-ctxLen);
const timestamps = slice.map((c) => isoOf(c.t));
const baseValues = slice.map((c) => c.c);
const simValues = applyScenario(baseValues, scenario);
const model = forecastModelFor(ctxLen);
try {
const [baseFc, simFc] = await Promise.all([
watsonxForecast(cfg, {
model,
timestamps,
values: baseValues,
freq,
targetColumn: 'price',
}),
watsonxForecast(cfg, {
model,
timestamps,
values: simValues,
freq,
targetColumn: 'price',
}),
]);
const basePoints = pointsFrom(baseFc);
const simPoints = pointsFrom(simFc);
const baseStats = forecastStats(
baseValues[baseValues.length - 1],
basePoints,
timeframe,
aggregate,
);
const simStats = forecastStats(
simValues[simValues.length - 1],
simPoints,
timeframe,
aggregate,
);
out.baseline = { points: basePoints, stats: baseStats };
out.simulated = { points: simPoints, stats: simStats };
out.divergence = {
changePctDelta: simStats.changePct - baseStats.changePct,
endDeltaPct: pctChange(baseStats.end, simStats.end),
};
out.ibm = {
configured: true,
forecastModel: baseFc.model,
inputWindow: baseFc.inputWindow,
};
try {
const user =
`I am the digital twin of ${token.name}${token.symbol ? ` (${token.symbol})` : ''}. ` +
`A what-if scenario was applied to me: ${label}. In my baseline, IBM Granite TimeSeries projects ` +
`me moving ${baseStats.direction} by ${baseStats.changePct.toFixed(1)}% over the next ${baseStats.horizonHours} hours. ` +
`Under this scenario, Granite now projects me moving ${simStats.direction} by ${simStats.changePct.toFixed(1)}%. ` +
`In exactly two sentences, speak as me about how this scenario reshapes my trajectory.`;
const persona = await narratePersona(cfg, PERSONA_SYSTEM, user);
out.persona = persona;
out.governance = await governPersona(persona.text);
} catch (pErr) {
out.persona = { text: '', error: String(pErr.message || pErr) };
}
} catch (fErr) {
out.ibm = { configured: true, error: String(fErr.message || fErr) };
}
return json(res, 200, out);
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
// Global hourly ceiling on the shared watsonx server key (same bucket as
// api/watsonx/embed) — a hard aggregate cost cap independent of any one IP.
// Only consumed when watsonx is configured; the keyless candles-only path
// stays unaffected.
if (watsonxConfig().configured) {
const global = await limits.watsonxEmbedGlobal();
if (!global.success)
return rateLimited(res, global, 'watsonx capacity reached — try again shortly');
}
// A market-data outage is a third party's problem, not a bug here: answer it
// with its real contract instead of letting a 502 reach wrap(), which would
// log an unhandled 5xx, capture it to Sentry, and page ops once per request.
// The handler's own validation errors and any genuine bug still bubble.
try {
if (req.method === 'POST') return await handlePost(req, res);
return await handleGet(req, res);
} catch (err) {
if (isMarketUpstreamError(err)) return marketUpstreamError(res, err);
throw err;
}
});