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
// ExitDecisionEngine - pure exit decision. No I/O, no time source of its own.
//
// The single source of truth for "should this position exit, and why", evaluated
// in strict priority order: stop-loss → signal-flip → trailing-stop → take-profit
// → timeout. The hard stop-loss always wins; `signal_flip` is an early cut that
// only fires while underwater. Because the clock is always passed in (never read
// from wall time here), the exact same function governs live evaluation and
// historical backtests - the two can never drift.
//
// Ported near-verbatim from three.ws `workers/agent-sniper/exit-logic.js`.
// Solana lamports → EVM wei: entry/value/peak are `bigint`. Ratio comparisons run
// in float64 (see types/exit.ts for why that is precision-safe).
/**
* Coerce to a finite number, or `null`. A `null`/blank input is "disabled"
* (`null`) - NOT `0`. (`Number(null) === 0`, so a missing take-profit / trailing
* stop would otherwise fire immediately; `null` documents "no TP / no trailing
* stop", and this is the single source of truth that honors it.)
*/
export function pct(n) {
if (n == null)
return null;
const x = Number(n);
return Number.isFinite(x) ? x : null;
}
/** A confident bearish sentiment read. `minConfidence` defaults to 0.7. */
function isBearishFlip(sentiment) {
if (!sentiment || sentiment.signal !== 'bearish')
return false;
const conf = Number(sentiment.confidence);
const floor = Number(sentiment.minConfidence);
return Number.isFinite(conf) && conf >= (Number.isFinite(floor) ? floor : 0.7);
}
/**
* Decide the exit reason for a position, or `null` to hold. Evaluated in priority
* order: stop-loss → signal-flip → trailing-stop → take-profit → timeout.
*
* The hard stop-loss always wins. `signal_flip` is an EARLY warning that cuts a
* losing position before it reaches the stop; it only fires while the position is
* underwater and never overrides a take-profit. It is inert unless the caller
* passes a `sentiment`, so replays that omit it are byte-for-byte unchanged.
*
* @param pos position to evaluate
* @param value current value of the position (wei)
* @param peak high-water mark of `value` since entry (wei)
* @param now epoch ms for the timeout clock - always injected, never wall time
* @param sentiment live sentiment read; `null`/omitted disables signal_flip
*/
export function decideExit(pos, value, peak, now, sentiment = null) {
const entry = pos.entryQuoteWei ?? 0n;
if (entry <= 0n)
return null;
const ev = Number(entry);
const v = Number(value);
const pk = Number(peak);
const sl = pct(pos.stopLossPct);
const ts = pct(pos.trailingStopPct);
const tp = pct(pos.takeProfitPct);
if (sl != null && v <= ev * (1 - sl / 100))
return 'stop_loss';
if (isBearishFlip(sentiment) && v < ev)
return 'signal_flip';
// Trailing stop arms only once the peak has been ABOVE entry, so a coin that
// never moves up can't trail-stop on entry noise.
if (ts != null && pk > ev && v <= pk * (1 - ts / 100))
return 'trailing_stop';
if (tp != null && v >= ev * (1 + tp / 100))
return 'take_profit';
const heldS = (now - pos.openedAt) / 1000;
if (pos.maxHoldSeconds != null && heldS >= pos.maxHoldSeconds)
return 'timeout';
return null;
}
/** The take-initials multiple (× entry) or `null` when the ladder is off. Must be
* > 1 to make sense - you can't recover initials below cost. */
export function ladderMultiple(n) {
const x = pct(n);
return x != null && x > 1 ? x : null;
}
/** Moon-bag floor as a fraction of the position that must ALWAYS be kept on the
* take-initials event. Default 15%, clamped to [0, 0.95] so a sell can never be
* the whole bag. */
export function moonbagFraction(n) {
const x = pct(n);
const frac = x == null ? 15 : x;
return Math.max(0, Math.min(0.95, frac / 100));
}
/**
* Laddered exit decision: the reason AND what fraction of the CURRENT remaining
* position to sell. This is the live-trading source of truth; `decideExit` above
* stays the single-shot decider a backtester replays.
*
* The ladder is OPT-IN: with no `initialsOutMultiple` set it is byte-for-byte the
* classic full-exit behavior (sellFraction 1 on any `decideExit` reason), so
* existing strategies are unchanged. When set, it encodes the owner's rule:
*
* - Protective exits are always FULL exits of whatever remains, and the hard
* stop-loss still wins: stop_loss → signal_flip → trailing_stop.
* - The FIRST time the position reaches `initialsOutMultiple`× entry (e.g. 2×),
* sell exactly enough to return the initial cost basis (fraction =
* entry/value), but NEVER more than 1 − moonbag floor - so a moon bag always
* rides. At 2× that is a 0.5 sell (keep half); at 5× a 0.2 sell (keep 80%).
* - After initials are recovered, the moon bag runs, protected by the trailing
* stop; an optional classic `takeProfitPct` acts as a ceiling that exits the
* remainder. Timeout exits the remainder.
*
* It NEVER returns a full take-PROFIT exit before initials are recovered - that
* is the "sold too much too soon" mistake the rule exists to prevent.
*/
export function decideLadderedExit(pos, value, peak, now, sentiment = null) {
const mult = ladderMultiple(pos.initialsOutMultiple);
if (mult == null) {
// Ladder off → classic single-shot full exit (unchanged behavior).
const reason = decideExit(pos, value, peak, now, sentiment);
return reason ? { reason, sellFraction: 1 } : null;
}
const entry = pos.entryQuoteWei ?? 0n;
if (entry <= 0n)
return null;
const ev = Number(entry);
const v = Number(value);
const pk = Number(peak);
const sl = pct(pos.stopLossPct);
const ts = pct(pos.trailingStopPct);
const tp = pct(pos.takeProfitPct);
const moonbag = moonbagFraction(pos.moonbagMinPct);
const recovered = pos.initialsRecovered === true;
// Protective exits - full exit of the remainder; stop-loss wins on conflict.
if (sl != null && v <= ev * (1 - sl / 100))
return { reason: 'stop_loss', sellFraction: 1 };
if (isBearishFlip(sentiment) && v < ev)
return { reason: 'signal_flip', sellFraction: 1 };
// Trailing stop arms only once the peak has been ABOVE entry (see decideExit).
if (ts != null && pk > ev && v <= pk * (1 - ts / 100))
return { reason: 'trailing_stop', sellFraction: 1 };
// Take-initials - the first profit event, once, before initials are recovered.
if (!recovered && v >= ev * mult) {
const recoverFraction = ev / v; // f·value = cost basis
const sellFraction = Math.max(0, Math.min(recoverFraction, 1 - moonbag));
if (sellFraction > 0)
return { reason: 'take_initials', sellFraction, recoversInitials: true };
}
// Moon-bag ceiling - optional classic take-profit, only AFTER initials are out.
if (recovered && tp != null && v >= ev * (1 + tp / 100))
return { reason: 'take_profit', sellFraction: 1 };
// Timeout - full exit of the remainder.
const heldS = (now - pos.openedAt) / 1000;
if (pos.maxHoldSeconds != null && heldS >= pos.maxHoldSeconds)
return { reason: 'timeout', sellFraction: 1 };
return null;
}