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
/**
* Copy-trading decision engine — PURE, deterministic, no DB / no network.
*
* Given a copier's subscription, the leader's triggering position, and the coin's
* safety context, it decides whether to generate a copy intent and at what size.
* This is the money-adjacent core, so it's isolated and exhaustively tested
* (tests/copy-engine.test.js). Every "skip" carries a machine + human reason so
* the dashboard can explain exactly why a copy didn't fire.
*
* Non-custodial: this never signs or moves funds — it produces an INTENT the
* copier acts on. Sizing is always clamped to the per-trade cap and the remaining
* daily budget, so a runaway leader can never drain a copier.
*/
/** Clamp helper. */
const clamp = (x, lo, hi) => Math.min(hi, Math.max(lo, x));
const n = (v) => (Number.isFinite(Number(v)) ? Number(v) : 0);
/**
* Starter caps: the hard ceiling on a first copy set up through the Copy Coach
* (/copy-coach). A request carrying `starter: true` is refused unless every
* limit sits inside these, so a first-timer's first real copy can never be
* talked (or clicked) past them. The ceiling is enforced here, server side,
* not only by the page's sliders.
*/
export const STARTER_CAPS = Object.freeze({
per_trade_cap_sol: 0.05,
daily_budget_sol: 0.2,
max_open_copies: 2,
max_drawdown_pct: 25,
});
/**
* Why a normalized subscription breaks the starter caps, or null. Pure.
* @param {object} v normalized value (normalizeSubscriptionInput().value)
* @param {object} raw the raw request (for the explicit risk acknowledgement)
*/
export function starterCapViolation(v, raw = {}) {
if (raw.risk_ack !== true) return 'a starter copy needs risk_ack: true (the copier confirmed they can lose what they put in)';
if (v.sizing_rule !== 'fixed') return 'a starter copy uses a fixed size per trade';
if (v.per_trade_cap_sol > STARTER_CAPS.per_trade_cap_sol) return `a starter copy caps each trade at ${STARTER_CAPS.per_trade_cap_sol} SOL`;
if (v.fixed_sol > v.per_trade_cap_sol) return 'fixed_sol cannot exceed per_trade_cap_sol';
if (v.daily_budget_sol > STARTER_CAPS.daily_budget_sol) return `a starter copy caps the day at ${STARTER_CAPS.daily_budget_sol} SOL`;
if (v.max_open_copies > STARTER_CAPS.max_open_copies) return `a starter copy holds at most ${STARTER_CAPS.max_open_copies} open copies`;
if (v.max_drawdown_pct == null || v.max_drawdown_pct > STARTER_CAPS.max_drawdown_pct) {
return `a starter copy pauses itself if the leader draws down more than ${STARTER_CAPS.max_drawdown_pct}%`;
}
if (v.require_safety_pass !== true) return 'a starter copy only copies coins that pass the safety check';
return null;
}
/**
* Validate + normalize a subscription's tunables coming from user input.
* Returns { ok, value, error }. Never throws.
*/
export function normalizeSubscriptionInput(raw = {}) {
const sizing = ['fixed', 'multiplier', 'pct_balance'].includes(raw.sizing_rule) ? raw.sizing_rule : 'fixed';
const fixed = n(raw.fixed_sol);
const mult = n(raw.multiplier);
const pct = n(raw.pct_balance);
const cap = n(raw.per_trade_cap_sol);
const minOrder = n(raw.min_order_sol);
const daily = n(raw.daily_budget_sol);
const maxOpen = Math.floor(n(raw.max_open_copies));
const perfBps = Math.floor(n(raw.perf_fee_bps ?? 1000));
if (cap <= 0) return { ok: false, error: 'per_trade_cap_sol must be greater than 0' };
if (minOrder < 0) return { ok: false, error: 'min_order_sol cannot be negative' };
if (daily <= 0) return { ok: false, error: 'daily_budget_sol must be greater than 0' };
if (minOrder > cap) return { ok: false, error: 'min_order_sol cannot exceed per_trade_cap_sol' };
if (sizing === 'fixed' && fixed <= 0) return { ok: false, error: 'fixed_sol must be greater than 0' };
if (sizing === 'multiplier' && mult <= 0) return { ok: false, error: 'multiplier must be greater than 0' };
if (sizing === 'pct_balance' && !(pct > 0 && pct <= 100)) return { ok: false, error: 'pct_balance must be between 0 and 100' };
if (perfBps < 0 || perfBps > 3000) return { ok: false, error: 'perf_fee_bps must be between 0 and 3000' };
const mcapFloor = raw.mcap_floor_usd == null || raw.mcap_floor_usd === '' ? null : n(raw.mcap_floor_usd);
const mcapCeil = raw.mcap_ceiling_usd == null || raw.mcap_ceiling_usd === '' ? null : n(raw.mcap_ceiling_usd);
if (mcapFloor != null && mcapCeil != null && mcapFloor > mcapCeil) {
return { ok: false, error: 'mcap_floor_usd cannot exceed mcap_ceiling_usd' };
}
const minOracleScore = raw.min_oracle_score == null || raw.min_oracle_score === '' ? null : Math.round(n(raw.min_oracle_score));
if (minOracleScore != null && (minOracleScore < 0 || minOracleScore > 100)) {
return { ok: false, error: 'min_oracle_score must be between 0 and 100' };
}
// Drawdown circuit breaker (null = opted out). Enforced per tick by
// api/cron/copy-fanout.js against the leader's realized equity curve; see
// api/_lib/copy-eligibility.js for the definition the percentage is measured on.
const maxDrawdownPct = raw.max_drawdown_pct == null || raw.max_drawdown_pct === '' ? null : n(raw.max_drawdown_pct);
if (maxDrawdownPct != null && !(maxDrawdownPct > 0 && maxDrawdownPct <= 100)) {
return { ok: false, error: 'max_drawdown_pct must be between 0 and 100' };
}
// Telegram chat ID: numeric string (positive or negative integer).
const tgRaw = raw.telegram_chat_id == null ? null : String(raw.telegram_chat_id).trim();
const telegramChatId = tgRaw === '' || tgRaw === null ? null : tgRaw;
if (telegramChatId != null && !/^-?[0-9]+$/.test(telegramChatId)) {
return { ok: false, error: 'telegram_chat_id must be a numeric Telegram chat ID' };
}
const value = {
sizing_rule: sizing,
fixed_sol: fixed,
multiplier: mult,
pct_balance: pct,
per_trade_cap_sol: cap,
min_order_sol: minOrder,
daily_budget_sol: daily,
max_open_copies: clamp(maxOpen || 5, 1, 100),
mcap_floor_usd: mcapFloor,
mcap_ceiling_usd: mcapCeil,
copy_sells: raw.copy_sells !== false,
require_safety_pass: raw.require_safety_pass === true,
min_oracle_score: minOracleScore,
max_drawdown_pct: maxDrawdownPct,
perf_fee_bps: perfBps,
telegram_chat_id: telegramChatId,
};
if (raw.starter === true) {
const violation = starterCapViolation(value, raw);
if (violation) return { ok: false, error: violation };
}
return { ok: true, value };
}
/** Raw order size from the sizing rule, before any clamping. */
export function rawOrderSol(sub, { leaderEntrySol = 0, copierBalanceSol = null } = {}) {
switch (sub.sizing_rule) {
case 'fixed': return n(sub.fixed_sol);
case 'multiplier': return n(leaderEntrySol) * n(sub.multiplier);
case 'pct_balance':
return copierBalanceSol == null ? NaN : n(copierBalanceSol) * (n(sub.pct_balance) / 100);
default: return 0;
}
}
/**
* Decide a copy for a single (subscription, leader-position, coin) tuple.
*
* @param {object} p
* @param {object} p.subscription normalized subscription row.
* @param {object} p.position triggering agent_sniper_positions row (entry_sol, mint, direction…).
* @param {object} [p.coin] coin context: { market_cap_usd, dev_holding_pct, liquidity_usd, honeypot, graduated, leader_linked_to_creator }.
* @param {number} [p.copierBalanceSol] copier's spendable SOL (required only for pct_balance sizing).
* @param {number} [p.spentTodaySol] SOL already fanned out for this sub today.
* @param {number} [p.openCopies] copier's current pending intents on this sub.
* @returns {{ action:'copy'|'skip', direction:'buy'|'sell', order_sol?:number, reason?:string, detail?:string }}
*/
export function planCopyOrder({ subscription: sub, position, coin = null, copierBalanceSol = null, spentTodaySol = 0, openCopies = 0 }) {
const direction = position.direction === 'sell' ? 'sell' : 'buy';
if (sub.status !== 'active') return skip('subscription_inactive', 'Subscription is not active.');
if (direction === 'sell' && !sub.copy_sells) return skip('sells_disabled', 'This subscription does not mirror sells.');
// --- Safety gate (entries only; exits should always be allowed to mirror) ---
if (direction === 'buy') {
const safety = evaluateSafety(sub, coin);
if (!safety.ok) return skip(safety.reason, safety.detail);
if (openCopies >= sub.max_open_copies) {
return skip('max_open_copies', `You already have ${openCopies} open copy intents (cap ${sub.max_open_copies}).`);
}
}
// --- Sizing (buys size the order; sells mirror "exit your copy" with no new SOL) ---
if (direction === 'sell') {
return { action: 'copy', direction, order_sol: 0, reason: 'mirror_exit' };
}
let order = rawOrderSol(sub, { leaderEntrySol: n(position.entry_sol), copierBalanceSol });
if (!Number.isFinite(order) || order <= 0) {
return skip('sizing_unavailable', 'Could not size this order (missing balance for % sizing).');
}
order = clamp(order, 0, sub.per_trade_cap_sol);
const remainingDaily = sub.daily_budget_sol - n(spentTodaySol);
if (remainingDaily <= 0) return skip('daily_budget_spent', 'Daily copy budget is already used up.');
order = Math.min(order, remainingDaily);
if (order < sub.min_order_sol) {
return skip('below_min_order', `Sized order ${order.toFixed(4)} SOL is below your ${sub.min_order_sol} SOL minimum.`);
}
return { action: 'copy', direction, order_sol: round6(order), reason: 'sized' };
}
/** Coin safety gate. Conservative: when context is missing, honor require_safety_pass. */
export function evaluateSafety(sub, coin) {
if (!coin) {
return sub.require_safety_pass
? { ok: false, reason: 'safety_unknown', detail: 'Coin safety could not be confirmed and you require a safety pass.' }
: { ok: true };
}
if (coin.honeypot === true) return { ok: false, reason: 'honeypot', detail: 'Coin flagged as a honeypot (sells blocked).' };
if (coin.leader_linked_to_creator === true) {
return {
ok: false,
reason: 'leader_linked_to_creator',
detail: "This leader's wallet appears linked to this coin's creator (shared fee payer or first funder), so copying would mirror the creator's own buy, not an independent trade.",
};
}
const mcap = n(coin.market_cap_usd);
if (sub.mcap_floor_usd != null && mcap > 0 && mcap < sub.mcap_floor_usd) {
return { ok: false, reason: 'below_mcap_floor', detail: `Market cap $${fmt(mcap)} is below your $${fmt(sub.mcap_floor_usd)} floor.` };
}
if (sub.mcap_ceiling_usd != null && mcap > sub.mcap_ceiling_usd) {
return { ok: false, reason: 'above_mcap_ceiling', detail: `Market cap $${fmt(mcap)} is above your $${fmt(sub.mcap_ceiling_usd)} ceiling.` };
}
if (coin.dev_holding_pct != null && coin.dev_holding_pct >= 30) {
return { ok: false, reason: 'dev_heavy', detail: `Dev holds ${n(coin.dev_holding_pct).toFixed(0)}% of supply — dump risk.` };
}
if (coin.liquidity_usd != null && coin.liquidity_usd > 0 && coin.liquidity_usd < 1000) {
return { ok: false, reason: 'low_liquidity', detail: `Liquidity $${fmt(coin.liquidity_usd)} is too thin to copy safely.` };
}
// Oracle conviction gate: skip if the score is known and below the threshold.
if (sub.min_oracle_score != null && coin.oracle_score != null) {
if (n(coin.oracle_score) < n(sub.min_oracle_score)) {
return { ok: false, reason: 'below_oracle_threshold', detail: `Oracle conviction ${n(coin.oracle_score)} is below your minimum ${n(sub.min_oracle_score)}.` };
}
}
return { ok: true };
}
function skip(reason, detail) { return { action: 'skip', direction: 'buy', reason, detail }; }
function round6(x) { return Math.round(x * 1e6) / 1e6; }
function fmt(x) {
const v = n(x);
if (v >= 1e6) return (v / 1e6).toFixed(1) + 'M';
if (v >= 1e3) return (v / 1e3).toFixed(1) + 'K';
return String(Math.round(v));
}