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
// Oracle — conviction alerts via Telegram.
//
// When the oracle-score cron produces a high-conviction coin for the first
// time, this module fires a Telegram message to the signals channel. A coin
// qualifies by tier (prime ≥86 / strong ≥72, see ORACLE_ALERT_MIN_TIER) OR by
// raw score (ORACLE_FEED_MIN_SCORE, default 56 = the Lean floor). The score
// path exists because tier-only gating starved the channel: the live score
// distribution tops out in the low 60s, so a strong-only feed never posts.
// The channel is separate from the ops alerts (TELEGRAM_ALERTS_CHAT_ID)
// and the changelog channel (TELEGRAM_CHANGELOG_CHAT_ID) — holders subscribe to
// it for actionable pump.fun conviction signals.
//
// Env:
// TELEGRAM_BOT_TOKEN — same bot used across the platform
// TELEGRAM_ORACLE_CHAT_ID — signals channel (@handle or -100… numeric)
// ORACLE_FEED_MIN_SCORE: score floor for channel posts (default 56;
// set 101 to disable the score path)
//
// Dedup: an in-memory Set of alerted mints per process restart, plus a DB flag
// (oracle_conviction.alerted_at) that persists across restarts so we never fire
// twice for the same coin even if the worker cold-starts.
//
// Fire-and-forget with a 4s abort — never delays the scoring loop.
import { sql } from '../db.js';
import { gmgnTokenUrl, axiomTokenUrl } from '../../../src/shared/trading-terminals.js';
import { fetchUpstream } from '../upstream-fetch.js';
const ALERT_TIMEOUT_MS = 4000;
// Minimum tier to alert on. 'prime' only = exclusive. 'strong' = more volume.
const MIN_ALERT_TIER = process.env.ORACLE_ALERT_MIN_TIER || 'strong';
const TIER_ORDER = { prime: 3, strong: 2, lean: 1, watch: 0, avoid: -1 };
const MIN_TIER_RANK = TIER_ORDER[MIN_ALERT_TIER] ?? 2;
// Score floor for the channel feed. 56 is the Lean tier boundary
// (api/_lib/oracle/conviction.js TIERS), the top slice of the real score
// distribution, roughly a dozen coins a day at current volume.
const FEED_MIN_SCORE = clampScore(process.env.ORACLE_FEED_MIN_SCORE, 56);
function clampScore(raw, fallback) {
const n = Number(raw);
return Number.isFinite(n) ? Math.max(0, Math.min(101, n)) : fallback;
}
/**
* Whether a scored coin qualifies for the channel feed: by tier
* (ORACLE_ALERT_MIN_TIER, default strong) OR by raw score
* (ORACLE_FEED_MIN_SCORE, default 56). Exported for tests.
*/
export function feedEligible(coin) {
const rank = TIER_ORDER[coin?.tier] ?? -1;
const score = Number(coin?.score) || 0;
return rank >= MIN_TIER_RANK || score >= FEED_MIN_SCORE;
}
// In-memory dedup for this process lifetime — prevents double-fire within the
// same worker even if alerted_at DB write is slow.
const _alerted = new Set();
// Personal signal dedup: map of "chatId:mint" → last alerted timestamp (ms).
// Prevents the 15-min cron window from firing the same personal signal 3×
// in a row. 1-hour cooldown per (subscriber, coin) pair.
const _personalSignalAt = new Map();
const PERSONAL_SIGNAL_COOLDOWN_MS = 60 * 60 * 1000;
const TIER_EMOJI = { prime: '🟣', strong: '🔵', lean: '🟡', watch: '⚪', avoid: '🔴' };
function tierEmoji(tier) { return TIER_EMOJI[tier] || '⚪'; }
function format(coin) {
const emoji = tierEmoji(coin.tier);
const pct = (n) => (n != null ? `${Math.round(Number(n))}` : '?');
const pillars = coin.pillars
? `Who ${pct(coin.pillars.pedigree)} · How ${pct(coin.pillars.structure)} · What ${pct(coin.pillars.narrative)} · Move ${pct(coin.pillars.momentum)}`
: '';
const category = coin.category ? ` · ${coin.category}` : '';
const smart = coin.smart_wallet_count ? ` · ${coin.smart_wallet_count} smart in` : '';
return [
`${emoji} <b>${escHtml(coin.symbol || '—')}</b> <code>${coin.score}</code> conviction <i>${escHtml(coin.tier)}</i>`,
escHtml(coin.name || ''),
pillars ? `<i>${pillars}</i>` : '',
`<code>${escHtml(coin.mint)}</code>`,
`${category}${smart}`,
`<a href="https://pump.fun/coin/${encodeURIComponent(coin.mint)}">pump.fun</a> · <a href="${gmgnTokenUrl(coin.mint)}">GMGN</a> · <a href="${axiomTokenUrl(coin.mint)}">Axiom</a> · <a href="https://three.ws/oracle/coin/${encodeURIComponent(coin.mint)}">Oracle</a>`,
].filter(Boolean).join('\n');
}
function escHtml(s) {
return String(s ?? '').replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
}
async function send(text) {
const token = process.env.TELEGRAM_BOT_TOKEN;
const chatId = process.env.TELEGRAM_ORACLE_CHAT_ID;
if (!token || !chatId) return;
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), ALERT_TIMEOUT_MS);
try {
await fetchUpstream(`https://api.telegram.org/bot${token}/sendMessage`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
chat_id: chatId,
text: text.slice(0, 4000),
parse_mode: 'HTML',
disable_web_page_preview: true,
}),
signal: ctrl.signal,
}, { name: 'telegram', timeoutMs: 10_000, attempts: 2, okWhen: () => true });
} catch { /* fire-and-forget */ } finally {
clearTimeout(timer);
}
}
/**
* Mark a coin as alerted in oracle_conviction so the flag survives restarts.
* Best-effort — never throws into the alert path.
*/
async function markAlerted(mint, network) {
try {
await sql`
update oracle_conviction set alerted_at = now()
where mint = ${mint} and network = ${network} and alerted_at is null
`;
} catch { /* non-fatal */ }
}
/**
* Fire a Telegram alert when an agent's open position resolves as a win.
* Called by the settle-loop after grading.
*
* @param {Array<{agent_name:string, agent_id:string, symbol:string, mint:string, tier:string, conviction:number, mode:string, size_sol:number, realized_pnl_sol:number, peak_multiple:number, network:string}>} exits
* @returns {Promise<number>} number of alerts sent
*/
export async function alertProfitableExit(exits) {
const token = process.env.TELEGRAM_BOT_TOKEN;
const chatId = process.env.TELEGRAM_ORACLE_CHAT_ID;
if (!token || !chatId || !exits?.length) return 0;
let sent = 0;
for (const e of exits) {
// Only alert live-mode wins with positive PnL or a meaningful ATH.
if (e.mode !== 'live' && e.mode !== 'simulate') continue;
if ((e.realized_pnl_sol ?? 0) <= 0 && (e.peak_multiple ?? 0) < 2) continue;
const pnlStr = e.realized_pnl_sol != null
? `+${Number(e.realized_pnl_sol).toFixed(4)} SOL`
: `${(e.peak_multiple ?? 0).toFixed(2)}× peak`;
const peakStr = e.peak_multiple != null ? `${Number(e.peak_multiple).toFixed(2)}×` : '?';
const sizeStr = e.size_sol != null ? `${Number(e.size_sol).toFixed(3)} SOL` : '?';
const emoji = e.mode === 'simulate' ? '🤖 [sim]' : '🤖';
const tierE = tierEmoji(e.tier);
const agentName = escHtml(e.agent_name || e.agent_id || 'Agent');
const sym = escHtml(e.symbol || '?');
const modeLabel = e.mode === 'simulate' ? ' <i>(simulated)</i>' : '';
const text = [
`${emoji} <b>${agentName}</b> made <b>${escHtml(pnlStr)}</b> on <b>$${sym}</b>${modeLabel}`,
`Peak: <b>${peakStr}</b> · Size: ${escHtml(sizeStr)} · Entry: ${tierE} ${escHtml(e.tier)} conviction (${e.conviction ?? '?'})`,
`<a href="https://pump.fun/coin/${encodeURIComponent(e.mint)}">pump.fun</a> · <a href="${gmgnTokenUrl(e.mint)}">GMGN</a> · <a href="https://three.ws/oracle/coin/${encodeURIComponent(e.mint)}">Oracle</a> · <a href="https://three.ws/agents/${encodeURIComponent(e.agent_id)}">Track record</a>`,
].join('\n');
await send(text);
sent++;
}
return sent;
}
/**
* Fire a Telegram alert the moment an agent makes a live oracle buy.
* Called by the agent-loop after each filled action so followers can copy
* before the coin moves.
*
* Only live-mode actions are alerted. Simulate actions generate too much
* volume and carry no real cost.
*
* @param {Array<{agent_id:string, agent_name?:string, symbol:string, mint:string, tier:string, conviction:number, size_sol:number, network:string}>} entries
* @returns {Promise<number>} number of alerts sent
*/
export async function alertAgentEntry(entries) {
const token = process.env.TELEGRAM_BOT_TOKEN;
const chatId = process.env.TELEGRAM_ORACLE_CHAT_ID;
if (!token || !chatId || !entries?.length) return 0;
let sent = 0;
for (const e of entries) {
const tierE = tierEmoji(e.tier);
const agentName = escHtml(e.agent_name || 'Agent');
const sym = escHtml((e.symbol || e.mint.slice(0, 6)).toUpperCase());
const sizeStr = e.size_sol != null ? `${Number(e.size_sol).toFixed(3)} SOL` : '?';
const convStr = e.conviction != null ? ` (${e.conviction})` : '';
const text = [
`${tierE} <b>${agentName}</b> entered <b>$${sym}</b>`,
`${escHtml(e.tier)} conviction${convStr} · ${escHtml(sizeStr)}`,
`<a href="https://pump.fun/coin/${encodeURIComponent(e.mint)}">pump.fun</a> · <a href="${gmgnTokenUrl(e.mint)}">GMGN</a> · <a href="https://three.ws/oracle/coin/${encodeURIComponent(e.mint)}">Oracle ↗</a> · <a href="https://three.ws/trader/${encodeURIComponent(e.agent_id)}">Copy trades →</a>`,
].join('\n');
await send(text);
sent++;
}
return sent;
}
/**
* Fire alerts for newly-scored coins that cross the tier threshold for the
* first time. Called by the oracle-score cron after each score pass.
*
* @param {Array<{mint:string, symbol:string, name:string, score:number, tier:string, pillars?:object, category?:string, smart_wallet_count?:number}>} coins
* @param {string} network
* @returns {Promise<number>} number of alerts sent
*/
export async function alertNewHighConviction(coins, network = 'mainnet') {
const token = process.env.TELEGRAM_BOT_TOKEN;
const chatId = process.env.TELEGRAM_ORACLE_CHAT_ID;
if (!token || !chatId) return 0; // silently no-op when not configured
// Filter to coins that qualify (by tier OR by raw score) and haven't been
// alerted. The score path keeps the feed alive at the top of the real
// distribution even while no coin reaches the strong/prime tiers.
const candidates = coins.filter((c) => feedEligible(c) && !_alerted.has(c.mint));
if (!candidates.length) return 0;
// Check the DB to skip any already-alerted mints (across restarts).
const mints = candidates.map((c) => c.mint);
let alreadyAlerted = new Set();
try {
const rows = await sql`
select mint from oracle_conviction
where mint = any(${mints}::text[]) and network = ${network} and alerted_at is not null
`;
alreadyAlerted = new Set(rows.map((r) => r.mint));
} catch { /* treat as empty on DB error */ }
let sent = 0;
for (const coin of candidates) {
if (alreadyAlerted.has(coin.mint)) { _alerted.add(coin.mint); continue; }
_alerted.add(coin.mint);
await send(format(coin));
await markAlerted(coin.mint, network);
sent++;
}
return sent;
}
/**
* Send a personal entry alert directly to one subscriber's Telegram chat.
* Called by the agent-loop for every watch that has a telegram_chat_id, whether
* simulate or live (marked clearly in the message).
*
* @param {string} chatId
* @param {{agent_name?:string, symbol:string, mint:string, tier:string, conviction:number, size_sol:number, mode:string, network:string}} entry
* @returns {Promise<void>}
*/
export async function alertPersonalEntry(chatId, entry) {
const token = process.env.TELEGRAM_BOT_TOKEN;
if (!token || !chatId) return;
const tierE = tierEmoji(entry.tier);
const sym = escHtml((entry.symbol || entry.mint.slice(0, 6)).toUpperCase());
const sizeStr = entry.size_sol != null ? `${Number(entry.size_sol).toFixed(3)} SOL` : '?';
const convStr = entry.conviction != null ? ` (score ${entry.conviction})` : '';
const modeLabel = entry.mode === 'simulate' ? ' <i>[simulated]</i>' : '';
const agentName = escHtml(entry.agent_name || 'Your agent');
const text = [
`${tierE} <b>${agentName}</b> entered <b>$${sym}</b>${modeLabel}`,
`${escHtml(entry.tier)} conviction${convStr} · ${escHtml(sizeStr)}`,
`<a href="https://pump.fun/coin/${encodeURIComponent(entry.mint)}">pump.fun</a> · <a href="https://three.ws/oracle/coin/${encodeURIComponent(entry.mint)}">Oracle ↗</a>`,
].join('\n');
await sendTo(chatId, text);
}
/**
* Send a personal conviction signal to one subscriber when a coin crosses their
* agent's min_score threshold. Only fires for coins the platform hasn't already
* alerted in this run — the platform channel gets one alert per coin, but the
* personal alert fires for every subscriber whose threshold the coin crosses.
*
* @param {string} chatId
* @param {object} coin oracle_conviction row (score, tier, symbol, mint, pillars, …)
* @param {number} minScore subscriber's personal threshold
* @returns {Promise<void>}
*/
export async function alertPersonalSignal(chatId, coin, minScore) {
const token = process.env.TELEGRAM_BOT_TOKEN;
if (!token || !chatId) return;
if ((Number(coin.score) || 0) < minScore) return;
const dedupKey = `${chatId}:${coin.mint}`;
const last = _personalSignalAt.get(dedupKey) || 0;
if (Date.now() - last < PERSONAL_SIGNAL_COOLDOWN_MS) return;
_personalSignalAt.set(dedupKey, Date.now());
const text = format(coin) + `\n<i>Your agent threshold: ${minScore}</i>`;
await sendTo(chatId, text);
}
/**
* Fire a personal conviction-drop warning when a coin's score falls
* significantly below the subscriber's entry conviction AND below their
* min_score threshold. Signals that the thesis for an open position is
* weakening — the subscriber should reassess.
*
* @param {string} chatId
* @param {{ symbol:string, mint:string, newScore:number, newTier:string, entryScore:number, minScore:number }} drop
*/
export async function alertPersonalConvictionDrop(chatId, drop) {
const token = process.env.TELEGRAM_BOT_TOKEN;
if (!token || !chatId) return;
const sym = escHtml((drop.symbol || drop.mint.slice(0, 6)).toUpperCase());
const newTier = escHtml(drop.newTier || 'unknown');
const emoji = TIER_EMOJI[drop.newTier] || '⚪';
const delta = Math.round(drop.entryScore - drop.newScore);
const mintLink = encodeURIComponent(drop.mint);
const text = [
`⚠️ <b>$${sym}</b> conviction weakened`,
`${emoji} ${newTier} · score <b>${drop.newScore}</b> (was ${drop.entryScore} at entry, −${delta} pts)`,
`Below your threshold of ${drop.minScore} — consider reviewing your position.`,
`<a href="https://pump.fun/coin/${mintLink}">pump.fun</a> · <a href="https://three.ws/oracle/coin/${mintLink}">Oracle ↗</a>`,
].join('\n');
await sendTo(chatId, text);
}
/**
* Fan-out entry alert to all Telegram subscribers of a given agent.
* Called by the agent-loop after every filled action (simulate or live).
* Each follower only receives the alert if the coin's score meets their
* personal min_score threshold.
*
* @param {string} agentId UUID of the agent that acted
* @param {{ symbol:string, mint:string, tier:string, score:number, size_sol?:number, mode:string, network:string }} entry
* @returns {Promise<number>} followers alerted
*/
export async function alertFollowers(agentId, entry) {
const token = process.env.TELEGRAM_BOT_TOKEN;
if (!token || !agentId) return 0;
const network = entry.network || 'mainnet';
const score = Number(entry.score) || 0;
const rows = await sql`
select f.chat_id
from oracle_followers f
where f.agent_id = ${agentId}
and f.network = ${network}
and f.min_score <= ${score}
`.catch(() => []);
if (!rows.length) return 0;
const tierE = tierEmoji(entry.tier);
const sym = escHtml((entry.symbol || entry.mint.slice(0, 6)).toUpperCase());
const sizeStr = entry.size_sol != null ? `${Number(entry.size_sol).toFixed(3)} SOL` : '?';
const modeLabel = entry.mode === 'simulate' ? ' <i>[sim]</i>' : '';
const text = [
`${tierE} Followed agent entered <b>$${sym}</b>${modeLabel}`,
`${escHtml(entry.tier)} conviction (${score}) · ${escHtml(sizeStr)}`,
`<a href="https://pump.fun/coin/${encodeURIComponent(entry.mint)}">pump.fun</a> · <a href="https://three.ws/oracle/coin/${encodeURIComponent(entry.mint)}">Oracle ↗</a>`,
].join('\n');
let sent = 0;
for (const { chat_id } of rows) {
sendTo(chat_id, text).catch(() => {});
sent++;
}
return sent;
}
/** Send to a specific chat ID (not the platform channel). */
async function sendTo(chatId, text) {
const token = process.env.TELEGRAM_BOT_TOKEN;
if (!token) return;
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), ALERT_TIMEOUT_MS);
try {
await fetchUpstream(`https://api.telegram.org/bot${token}/sendMessage`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
chat_id: chatId,
text: text.slice(0, 4000),
parse_mode: 'HTML',
disable_web_page_preview: true,
}),
signal: ctrl.signal,
}, { name: 'telegram', timeoutMs: 10_000, attempts: 2, okWhen: () => true });
} catch { /* fire-and-forget */ } finally {
clearTimeout(timer);
}
}