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
/**
* Trade card model: the shared truth behind a single shareable pump.fun trade.
*
* One closed `agent_sniper_positions` row becomes one card. Both the OG image
* (api/trade-og.js) and the share page (api/trade-share.js) render from THIS
* model, so the picture that unfurls on X and the page a click lands on can
* never disagree about a number.
*
* Everything here is pure: row in, view model out. No database, no network, no
* clock. That is what makes the numbers testable (tests/trade-card.test.js).
*
* Honesty rules baked into the model, per the Arena trust standard:
* - A paper fill (simulate mode) is FLAGGED, never dressed up as a live trade.
* `paper: true` drives a visible marker on the card and in the share text.
* - A moon-bag exit is not a full exit. `moonbag: true` says the initials came
* out and the rest still rides, so a "+180%" headline is not read as "sold".
* - Losses render exactly like wins. There is no branch that hides a red card.
*/
import { holdTime, fmtSol, fmtPct, shortAddr } from '../../src/trader-format.js';
export const LAMPORTS_PER_SOL = 1e9;
/** The paper-fill sentinel the sniper writes into buy_sig/sell_sig in simulate mode. */
export const SIMULATED_SIG = 'SIMULATED';
/** Exit reasons the engine can write, mapped to language a spectator understands. */
const EXIT_LABELS = {
take_profit: 'Take-profit',
stop_loss: 'Stop-loss',
trailing_stop: 'Trailing stop',
timeout: 'Max hold reached',
manual: 'Closed by owner',
kill_switch: 'Kill switch',
graduated: 'Graduated to AMM',
error: 'Closed on error',
signal_flip: 'Signal turned bearish',
liquidity_decay: 'Liquidity dried up',
take_initials: 'Initials recovered',
};
/** Accent per outcome. Used by the SVG card and the share page alike. */
export const TONE_ACCENT = { win: '#34d399', loss: '#f87171', flat: '#94a3b8' };
export function exitReasonLabel(reason) {
if (!reason) return 'Closed';
return EXIT_LABELS[reason] || String(reason).replace(/_/g, ' ');
}
function num(v) {
if (v == null) return null;
const n = Number(v);
return Number.isFinite(n) ? n : null;
}
function lamportsToSol(v) {
if (v == null) return null;
try {
return Number(BigInt(v)) / LAMPORTS_PER_SOL;
} catch {
const n = Number(v);
return Number.isFinite(n) ? n / LAMPORTS_PER_SOL : null;
}
}
/** A real on-chain signature, or null for a paper fill / missing leg. */
function realSig(sig) {
const s = typeof sig === 'string' ? sig.trim() : '';
return s && s !== SIMULATED_SIG ? s : null;
}
export function solscanTx(sig, network) {
const s = realSig(sig);
if (!s) return null;
return network === 'devnet' ? `https://solscan.io/tx/${s}?cluster=devnet` : `https://solscan.io/tx/${s}`;
}
export function solscanToken(mint, network) {
if (!mint) return null;
return network === 'devnet'
? `https://solscan.io/token/${mint}?cluster=devnet`
: `https://solscan.io/token/${mint}`;
}
/**
* Seconds held, from the two timestamps the engine stamps. Returns null when
* either end is missing or the clock ran backwards, so the card shows a dash
* instead of inventing a duration.
*/
export function heldSeconds(openedAt, closedAt) {
if (!openedAt || !closedAt) return null;
const a = new Date(openedAt).getTime();
const b = new Date(closedAt).getTime();
if (!Number.isFinite(a) || !Number.isFinite(b) || b < a) return null;
return (b - a) / 1000;
}
/**
* Return multiple on the entry: 4.12 for a +312% trade. Null when the entry
* size is unknown or zero, which is the only case where a multiple is undefined.
*/
export function returnMultiple(pnlPct) {
const p = num(pnlPct);
if (p == null) return null;
const m = 1 + p / 100;
return m > 0 ? m : 0;
}
/**
* The single biggest number on the card. Percent is the memecoin lingua franca,
* so it leads; the multiple rides alongside once a trade more than doubled.
*/
export function headlineFor(pnlPct) {
const p = num(pnlPct);
if (p == null) return { primary: 'CLOSED', secondary: null };
const primary = fmtPct(p, { sign: true, dp: Math.abs(p) >= 100 ? 0 : 1 });
const mult = returnMultiple(p);
const secondary = mult != null && mult >= 2 ? `${mult.toFixed(mult >= 10 ? 0 : 1)}x` : null;
return { primary, secondary };
}
/**
* SOL for display, with a floor that never lies. fmtSol prints three decimals,
* so a real but sub-milli-SOL move rounds to "0.000" and reads as a broken
* number on a card. Below the printable floor we say "<0.001" and keep the sign,
* which is both true and legible.
*/
export function solStr(v, { sign = true } = {}) {
const n = num(v);
if (n == null) return null;
const floor = 0.0005;
if (n !== 0 && Math.abs(n) < floor) {
const mark = n > 0 ? '+' : '−';
return `${sign ? mark : ''}<0.001 ◎`;
}
return fmtSol(n, { sign });
}
export function toneFor(pnlPct) {
const p = num(pnlPct);
if (p == null || Math.abs(p) < 0.05) return 'flat';
return p > 0 ? 'win' : 'loss';
}
/**
* Shape a joined position + agent row into the card model.
*
* @param {object} row agent_sniper_positions joined to agent_identities:
* id, agent_id, network, mint, symbol, name, status, exit_reason,
* entry_quote_lamports, exit_quote_lamports, realized_pnl_lamports,
* realized_pnl_pct, buy_sig, sell_sig, moonbag_base_amount,
* moonbag_last_value_lamports, opened_at, closed_at,
* agent_name, agent_image
* @param {{ origin?: string }} [opts]
* @returns {object} the view model both renderers read
*/
export function shapeTradeCard(row, { origin = 'https://three.ws' } = {}) {
const network = row.network === 'devnet' ? 'devnet' : 'mainnet';
const pnlPct = num(row.realized_pnl_pct);
const pnlSol = lamportsToSol(row.realized_pnl_lamports);
const entrySol = lamportsToSol(row.entry_quote_lamports);
const exitSol = lamportsToSol(row.exit_quote_lamports);
const buyUrl = solscanTx(row.buy_sig, network);
const sellUrl = solscanTx(row.sell_sig, network);
// A fill is paper when the engine wrote the sentinel (or no signature at all)
// on the entry leg. The entry is the honest test: every live position has one.
const paper = !realSig(row.buy_sig);
const secs = heldSeconds(row.opened_at, row.closed_at);
const moonbagTokens = num(row.moonbag_base_amount) || 0;
const moonbagSol = moonbagTokens > 0 ? lamportsToSol(row.moonbag_last_value_lamports) : null;
const tone = toneFor(pnlPct);
const headline = headlineFor(pnlPct);
const symbol = String(row.symbol || row.name || 'coin').replace(/^\$+/, '') || 'coin';
const agentName = String(row.agent_name || 'Agent').trim() || 'Agent';
const pnlSolStr = solStr(pnlSol);
const holdLabel = secs != null ? holdTime(secs) : null;
const model = {
id: row.id,
agentId: row.agent_id,
agentName,
agentImage: row.agent_image || row.agent_avatar || null,
network,
mint: row.mint,
mintShort: shortAddr(row.mint, 4, 4),
symbol,
coinName: row.name || null,
paper,
moonbag: moonbagTokens > 0,
moonbagSol,
tone,
accent: TONE_ACCENT[tone],
win: tone === 'win',
pnlPct,
pnlSol,
entrySol,
exitSol,
multiple: returnMultiple(pnlPct),
headline: headline.primary,
multipleLabel: headline.secondary,
heldSeconds: secs,
holdLabel,
exitReason: row.exit_reason || null,
exitLabel: exitReasonLabel(row.exit_reason),
buyUrl,
sellUrl,
mintUrl: solscanToken(row.mint, network),
agentUrl: `${origin}/trader/${encodeURIComponent(row.agent_id)}`,
shareUrl: `${origin}/trade/${encodeURIComponent(row.id)}`,
// Absolute for the crawlers (og:image must be absolute), relative for the
// on-page <img> so the card still renders on a preview host or localhost.
ogImageUrl: `${origin}/api/trade-og?id=${encodeURIComponent(row.id)}`,
ogImagePath: `/api/trade-og?id=${encodeURIComponent(row.id)}`,
pnlSolStr,
entrySolStr: solStr(entrySol, { sign: false }),
exitSolStr: solStr(exitSol, { sign: false }),
};
model.title = buildTitle(model);
model.description = buildDescription(model);
model.shareText = buildShareText(model);
return model;
}
/** Page + OG title. Leads with the outcome, names the agent, never hypes. */
export function buildTitle(m) {
const result = m.pnlPct != null ? m.headline : 'Closed';
const paper = m.paper ? ' (paper)' : '';
return `${m.agentName} ${result} on $${m.symbol}${paper} · three.ws Arena`;
}
/** OG description. Every clause is a number that exists on the row. */
export function buildDescription(m) {
const parts = [];
if (m.paper) parts.push('Paper trade (simulate mode), not a live fill');
if (m.entrySolStr && m.exitSolStr) parts.push(`${m.entrySolStr} in, ${m.exitSolStr} out`);
else if (m.entrySolStr) parts.push(`${m.entrySolStr} in`);
if (m.pnlSolStr) parts.push(`${m.pnlSolStr} realized`);
if (m.holdLabel) parts.push(`held ${m.holdLabel}`);
parts.push(m.exitLabel.toLowerCase());
if (m.moonbag) parts.push('initials out, moon-bag still riding');
parts.push(m.paper ? 'labeled paper, never counted as live' : 'every leg links to its on-chain transaction');
return parts.join(' · ');
}
/**
* The text pre-filled into an X post. Short, factual, no price call, no promise.
* The link carries the proof, so the copy does not have to oversell.
*/
export function buildShareText(m) {
const lead = m.paper
? `${m.agentName} paper-traded $${m.symbol}`
: `${m.agentName} traded $${m.symbol} on pump.fun`;
const result = m.pnlPct != null ? `${m.headline}${m.multipleLabel ? ` (${m.multipleLabel})` : ''}` : 'closed';
const held = m.holdLabel ? ` in ${m.holdLabel}` : '';
const proof = m.paper ? 'Paper mode, labeled as such.' : 'On-chain, verifiable.';
return `${lead}: ${result}${held}. ${proof}`;
}