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
// agent-mm — the market-maker decision engine.
//
// For one policy this sweep: re-quote the coin (curve pre-grad, AMM post-grad),
// snapshot inventory, run the graduation transition once, then pick AT MOST ONE
// bounded, non-reflexive action — seed → defend → recycle → rebalance — and fire
// it through executeAgentTrade (the same firewall + spend-guard + custody path a
// manual trade uses). The engine adds NO new way to move funds; it only decides
// WHEN and HOW MUCH, inside the policy's published limits.
//
// Anti-manipulation is enforced HERE, in code, every action:
// • interval gate — no action, and NEVER a side flip, inside min_action_interval
// (× a multiple for flips). The MM physically cannot wash-trade / round-trip.
// • volume cap — a single action can't exceed max_volume_pct of LIVE volume; if
// volume can't be measured, it won't act above a tiny conservative slice (it
// never paints a no-volume tape).
// • bounded sizing — defend buys are capped by the dip budget, daily budget,
// wallet SOL, and the inventory ceiling; recycle sells by recycle_pct and the
// volume cap. Nothing is reflexive; it never chases.
import { executeAgentTrade, parseTradeInput } from '../../api/agents/agent-trade.js';
import { getTradeLimits } from '../../api/_lib/agent-trade-guards.js';
import { GUARDS, SOL } from '../../api/_lib/market-maker.js';
import { quoteMarket, getHolding, getSolBalanceLamports, getWindowVolumeLamports } from './market.js';
import { provideLp } from './graduation.js';
import {
markEvaluated, recordActionAndAdvance, markSeedDone, markGraduation,
getDeployedLamports24h, getDefenseLamports24h,
} from './store.js';
import { log } from './log.js';
const MIN_TRADE_LAMPORTS = BigInt(GUARDS.MIN_TRADE_LAMPORTS);
const WALLET_HEADROOM_LAMPORTS = 5_000_000n; // leave 0.005 SOL for fees
function lamports(sol) { return BigInt(Math.max(0, Math.round(sol * SOL))); }
function bigMin(...xs) { return xs.reduce((a, b) => (a < b ? a : b)); }
/**
* Evaluate + (maybe) act on one policy. `agent` is { id, userId, meta }. Returns
* a short outcome tag for logging. Never throws past the per-policy try in the
* sweep — a single policy's failure can't abort the others.
*/
export async function runPolicy({ cfg, policy, agent }) {
const network = policy.network;
const mint = policy.mint;
const owner = agent.meta?.solana_address || null;
// LIVE only when BOTH the worker and the policy are live; otherwise the full
// logic runs against real quotes but never signs or spends (clearly labeled).
const simulate = !(cfg.mode === 'live' && policy.mode === 'live');
const tag = { policy: policy.id, mint, mode: simulate ? 'simulate' : 'live' };
// Read-only render collector: the helpers below mutate it as they size + fill,
// and runPolicy returns it merged with the outcome tag. NONE of these reads
// touch the decision/guard logic — they only describe what was decided so the
// arena can draw the floor line and route emotes off the same numbers.
const render = {
mint,
simulate,
floorSol: Number(policy.floor_price_sol) || 0,
priceSol: null,
sizeSol: 0,
sideBuy: null,
signature: null,
};
const out = (t) => ({ tag: t, ...render });
if (!owner || !agent.meta?.encrypted_solana_secret) {
await markEvaluated(policy.id, { error: 'no_wallet' });
return out('no_wallet');
}
const market = await quoteMarket({ network, mint });
if (!market || !(market.price_sol > 0)) {
await markEvaluated(policy.id, { error: 'no_price' });
return out('no_price');
}
const price = market.price_sol; // SOL per whole token
render.priceSol = price;
const holding = await getHolding({ network, mint, owner });
const inventoryWhole = holding?.whole ?? 0;
const inventoryRaw = holding?.raw ?? 0n;
const inventoryValueLamports = lamports(inventoryWhole * price);
await markEvaluated(policy.id, { priceSol: price, inventoryTokens: inventoryWhole, inventoryValueLamports, error: null });
const solBal = (await getSolBalanceLamports({ network, owner })) ?? 0n;
// ── graduation transition (once) ──────────────────────────────────────────
if (market.graduated && !policy.graduation_done_at) {
return out(await runGraduation({ cfg, policy, agent, price, inventoryWhole, inventoryRaw, solBal, simulate, tag, render }));
}
// ── decide intent (priority: seed → defend → recycle → rebalance) ─────────
const slippageBps = Math.round(Number(policy.slippage_bps) || 500);
const floorPrice = Number(policy.floor_price_sol) || 0;
const floorBand = Number(policy.floor_band_pct) || 0;
const takeBand = Number(policy.take_profit_band_pct) || 0;
const recyclePct = Number(policy.recycle_pct) || 0;
const maxInv = Number(policy.max_inventory_tokens) || 0;
const floorTrigger = floorPrice * (1 - floorBand / 100);
const takeTrigger = floorPrice * (1 + takeBand / 100);
let intent = null; // { kind, side, lamports?|tokens?, reason }
if (Number(policy.seed_lamports) > 0 && !policy.seed_done_at) {
intent = { kind: 'seed', side: 'buy', lamports: BigInt(policy.seed_lamports), reason: 'seed_initial_liquidity' };
} else if (floorPrice > 0 && price <= floorTrigger) {
// Defend: buy a measured slice. The per-action slice is a quarter of the dip
// budget (defend in tranches, never the whole budget at once).
const dipBudget = BigInt(policy.dip_buy_budget_lamports);
const slice = dipBudget > 0n ? dipBudget / 4n : lamports(0.02);
intent = { kind: 'defend_buy', side: 'buy', lamports: slice, reason: `price ${price.toExponential(3)} ≤ floor band ${floorTrigger.toExponential(3)}` };
} else if (takeBand >= 0 && price >= takeTrigger && inventoryWhole > 0) {
const tokens = inventoryWhole * (recyclePct / 100);
if (tokens > 0) intent = { kind: 'recycle_sell', side: 'sell', tokens, reason: `price ${price.toExponential(3)} ≥ take band ${takeTrigger.toExponential(3)}` };
} else if (maxInv > 0 && inventoryWhole > maxInv) {
const tokens = inventoryWhole - maxInv;
intent = { kind: 'rebalance_trim', side: 'sell', tokens, reason: `inventory ${inventoryWhole.toFixed(2)} > ceiling ${maxInv.toFixed(2)}` };
}
if (!intent) return out('in_band'); // nothing to do — markEvaluated already recorded the heartbeat
// ── anti-manipulation: interval + side-flip gate ──────────────────────────
const interval = Number(policy.min_action_interval_seconds) || 60;
const lastAt = policy.last_action_at ? new Date(policy.last_action_at).getTime() : 0;
const sinceSec = lastAt ? (Date.now() - lastAt) / 1000 : Infinity;
if (sinceSec < interval) {
return out(await skip({ policy, intent, price, status: 'skipped', detail: `interval guard — ${Math.ceil(interval - sinceSec)}s until next action allowed`, reason: 'interval_guard' }));
}
if (policy.last_action_side && policy.last_action_side !== intent.side && sinceSec < interval * GUARDS.SIDE_FLIP_INTERVAL_MULTIPLE) {
return out(await skip({ policy, intent, price, status: 'blocked', detail: `anti-wash guard — a ${intent.side} cannot follow a ${policy.last_action_side} within ${interval * GUARDS.SIDE_FLIP_INTERVAL_MULTIPLE}s`, reason: 'anti_wash_guard' }));
}
// ── anti-manipulation: live-volume cap (lamports per action) ──────────────
const windowVol = await getWindowVolumeLamports({ mint, windowSeconds: cfg.volumeWindowSeconds });
const volumeCapLamports = windowVol == null
? BigInt(GUARDS.NO_VOLUME_FALLBACK_LAMPORTS)
: (windowVol * BigInt(Math.round(Number(policy.max_volume_pct) * 1000))) / 100000n;
const volumeUnmeasured = windowVol == null;
// ── size + execute ────────────────────────────────────────────────────────
if (intent.side === 'buy') {
return out(await doBuy({ cfg, policy, agent, intent, price, inventoryWhole, maxInv, solBal, volumeCapLamports, volumeUnmeasured, slippageBps, simulate, tag, render }));
}
return out(await doSell({ cfg, policy, agent, intent, price, inventoryWhole, inventoryRaw, volumeCapLamports, volumeUnmeasured, slippageBps, simulate, tag, render }));
}
// ── buys (seed + defend) ──────────────────────────────────────────────────────
async function doBuy({ cfg, policy, agent, intent, price, inventoryWhole, maxInv, solBal, volumeCapLamports, volumeUnmeasured, slippageBps, simulate, tag, render }) {
let size = intent.lamports;
// Daily budget (all buys) and dip budget (defense only), measured rolling-24h.
const dailyBudget = BigInt(policy.daily_budget_lamports);
if (dailyBudget > 0n) {
const deployed = await getDeployedLamports24h(policy.id);
const remaining = dailyBudget > deployed ? dailyBudget - deployed : 0n;
if (remaining <= 0n) return skip({ policy, intent, price, status: 'skipped', detail: 'daily budget exhausted (24h)', reason: 'daily_budget' });
size = bigMin(size, remaining);
}
if (intent.kind === 'defend_buy') {
const dipBudget = BigInt(policy.dip_buy_budget_lamports);
if (dipBudget > 0n) {
const spent = await getDefenseLamports24h(policy.id);
const remaining = dipBudget > spent ? dipBudget - spent : 0n;
if (remaining <= 0n) return skip({ policy, intent, price, status: 'skipped', detail: 'dip-buy budget exhausted (24h)', reason: 'dip_budget' });
size = bigMin(size, remaining);
}
}
// Inventory ceiling — never buy past it.
if (maxInv > 0) {
const headroomTokens = maxInv - inventoryWhole;
if (headroomTokens <= 0) return skip({ policy, intent, price, status: 'skipped', detail: 'at inventory ceiling', reason: 'at_max_inventory' });
size = bigMin(size, lamports(headroomTokens * price));
}
// Volume cap — the maker can't be more than max_volume_pct of live volume.
size = bigMin(size, volumeCapLamports);
// Wallet SOL headroom (leave fees).
const spendable = solBal > WALLET_HEADROOM_LAMPORTS ? solBal - WALLET_HEADROOM_LAMPORTS : 0n;
if (spendable <= 0n) return skip({ policy, intent, price, status: 'skipped', detail: 'wallet has no spendable SOL', reason: 'insufficient_sol' });
size = bigMin(size, spendable);
if (size < MIN_TRADE_LAMPORTS) {
const reason = volumeUnmeasured ? 'volume_unmeasured' : 'below_min';
return skip({ policy, intent, price, status: 'skipped', detail: volumeUnmeasured ? 'live volume unmeasured — holding to the conservative no-volume slice' : 'sized below the dust floor', reason });
}
const body = { mint: policy.mint, network: policy.network, side: 'buy', amount: Number(size) / SOL, slippageBps };
return execute({ cfg, policy, agent, intent, price, body, sizeLamports: size, simulate, tag, render });
}
// ── sells (recycle + rebalance) ──────────────────────────────────────────────
async function doSell({ cfg, policy, agent, intent, price, inventoryWhole, inventoryRaw, volumeCapLamports, volumeUnmeasured, slippageBps, simulate, tag, render }) {
let tokens = Math.min(intent.tokens, inventoryWhole);
if (!(tokens > 0)) return skip({ policy, intent, price, status: 'skipped', detail: 'no inventory to sell', reason: 'no_inventory' });
// Volume cap → max tokens this action.
const capTokens = Number(volumeCapLamports) / SOL / price;
if (capTokens < tokens) tokens = capTokens;
const sizeLamports = lamports(tokens * price);
if (sizeLamports < MIN_TRADE_LAMPORTS) {
const reason = volumeUnmeasured ? 'volume_unmeasured' : 'below_min';
return skip({ policy, intent, price, status: 'skipped', detail: volumeUnmeasured ? 'live volume unmeasured — holding to the conservative no-volume slice' : 'sized below the dust floor', reason });
}
// Sell whole tokens (executeAgentTrade resolves the base units + venue).
const body = { mint: policy.mint, network: policy.network, side: 'sell', amount: tokens, slippageBps };
return execute({ cfg, policy, agent, intent, price, body, sizeLamports, tokens, simulate, tag, render });
}
// ── execute through the shared, audited trade path ────────────────────────────
async function execute({ cfg, policy, agent, intent, price, body, sizeLamports, tokens = null, simulate, tag, render }) {
const tradeLimits = getTradeLimits(agent.meta);
let input;
try {
input = parseTradeInput(body, tradeLimits);
} catch (e) {
return skip({ policy, intent, price, status: 'failed', detail: `invalid trade: ${e?.code || e?.message || 'error'}`, reason: 'invalid_trade' });
}
// Idempotency bucket = the interval window, so two overlapping sweeps can't
// double-fire the same action; a fresh window allows the next one.
const bucket = Math.floor(Date.now() / (Math.max(30, Number(policy.min_action_interval_seconds) || 60) * 1000));
input.idempotencyKey = `mm:${policy.id}:${intent.kind}:${bucket}`;
input.simulate = simulate;
let result;
try {
result = await executeAgentTrade({
id: agent.id, userId: agent.userId, meta: agent.meta, input,
source: `mm:${intent.kind}`, sourceMeta: { policy_id: policy.id, mint: policy.mint },
});
} catch (e) {
return skip({ policy, intent, price, status: 'failed', detail: `execute crashed: ${e?.message?.slice(0, 120) || 'error'}`, reason: 'execute_error' });
}
if (!result.ok) {
const status = result.code === 'firewall_blocked' ? 'blocked' : 'failed';
await recordActionAndAdvance({
policy,
action: { kind: intent.kind, side: body.side, triggerReason: intent.reason, priceSol: price, status, detail: `${result.code}: ${result.message || ''}`.slice(0, 280), meta: { code: result.code } },
});
log.warn('mm action blocked', { ...tag, kind: intent.kind, code: result.code });
return result.code || 'failed';
}
const d = result.data || {};
const isSim = d.simulated === true || simulate;
const status = isSim ? 'simulated' : 'executed';
const solMoved = body.side === 'buy'
? (isSim ? Number(sizeLamports) : Math.round((d.sol_spent ?? 0) * SOL))
: (isSim ? Number(sizeLamports) : Math.round((d.sol_received ?? 0) * SOL));
const tokenAmount = body.side === 'buy'
? (d.tokens_received != null ? Number(d.tokens_received) / 1e6 : null)
: (tokens ?? null);
await recordActionAndAdvance({
policy,
action: {
kind: intent.kind, side: body.side, triggerReason: intent.reason, priceSol: price,
solLamports: solMoved, tokenAmount, priceImpactPct: d.price_impact_pct ?? null,
venue: d.venue || null, signature: d.signature && d.signature !== 'SIMULATED' ? d.signature : null,
custodyEventId: d.custody_event_id ?? null, status,
detail: isSim ? 'paper fill (simulate)' : null, meta: { mode: isSim ? 'simulate' : 'live' },
},
effect: { solLamports: solMoved },
});
if (intent.kind === 'seed') await markSeedDone(policy.id);
// Render enrichment (read-only): the actual SOL moved + side + on-chain sig so
// the arena renders the real fill, not the pre-size estimate.
if (render) {
render.sizeSol = Math.max(0, solMoved) / SOL;
render.sideBuy = body.side === 'buy';
render.signature = d.signature && d.signature !== 'SIMULATED' ? d.signature : null;
}
log.trade('mm action', { ...tag, kind: intent.kind, side: body.side, status, sol: solMoved / SOL, sig: d.signature || null, impact: d.price_impact_pct ?? null });
return intent.kind;
}
// ── graduation transition (provide_lp | distribute | hold) ────────────────────
async function runGraduation({ cfg, policy, agent, price, inventoryWhole, inventoryRaw, solBal, simulate, tag, render }) {
const action = policy.graduation_action || 'hold';
const slippagePct = (Number(policy.slippage_bps) || 500) / 100;
log.info('graduation transition', { ...tag, action });
if (action === 'hold') {
await recordActionAndAdvance({ policy, action: { kind: 'graduation_hold', triggerReason: 'graduated', priceSol: price, status: 'executed', detail: 'holding inventory; continuing two-sided on the AMM' } });
await markGraduation(policy.id, { status: 'done', terminal: false });
return 'graduation_hold';
}
if (action === 'provide_lp') {
if (!(inventoryWhole > 0)) {
await recordActionAndAdvance({ policy, action: { kind: 'graduation_lp', triggerReason: 'graduated', priceSol: price, status: 'skipped', detail: 'no inventory to provide as LP' } });
await markGraduation(policy.id, { status: 'done', terminal: true });
return 'graduation_lp_empty';
}
try {
const lp = await provideLp({
network: policy.network, mint: policy.mint, meta: agent.meta, userId: agent.userId, agentId: agent.id,
inventoryRaw, walletLamports: solBal, slippagePct, confirmTimeoutMs: 60_000, simulate,
});
await recordActionAndAdvance({
policy,
action: {
kind: 'graduation_lp', triggerReason: 'graduated', priceSol: price,
solLamports: lp.quoteLamports, tokenAmount: Number(lp.baseDeposited) / 1e6, venue: 'lp',
signature: lp.signature, status: lp.simulated ? 'simulated' : 'executed',
detail: lp.simulated ? 'paper LP deposit (simulate)' : 'provided LP into the canonical AMM pool',
meta: { base_deposited: lp.baseDeposited, quote_lamports: lp.quoteLamports },
},
});
await markGraduation(policy.id, { status: 'done', signature: lp.signature, terminal: true });
if (render) {
render.sizeSol = Math.max(0, Number(lp.quoteLamports) || 0) / SOL;
render.sideBuy = null; // an LP deposit is two-sided, neither a buy nor a sell
render.signature = lp.signature && lp.signature !== 'SIMULATED' ? lp.signature : null;
}
log.trade('graduation lp', { ...tag, sig: lp.signature, base: lp.baseDeposited, quote: lp.quoteLamports, simulated: lp.simulated });
return 'graduation_lp';
} catch (e) {
await recordActionAndAdvance({ policy, action: { kind: 'graduation_lp', triggerReason: 'graduated', priceSol: price, status: 'failed', detail: `${e?.code || e?.message || 'lp_failed'}`.slice(0, 280) } });
await markGraduation(policy.id, { status: `failed:${e?.code || 'lp_failed'}`, terminal: false });
log.warn('graduation lp failed (will retry)', { ...tag, code: e?.code, err: e?.message });
return 'graduation_lp_failed';
}
}
// distribute — liquidate the managed inventory back to SOL in the agent wallet
// (the owner can then withdraw / distribute). Routed through the audited path.
if (!(inventoryWhole > 0)) {
await recordActionAndAdvance({ policy, action: { kind: 'graduation_distribute', triggerReason: 'graduated', priceSol: price, status: 'skipped', detail: 'no inventory to distribute' } });
await markGraduation(policy.id, { status: 'done', terminal: true });
return 'graduation_distribute_empty';
}
const body = { mint: policy.mint, network: policy.network, side: 'sell', amount: 'max', slippageBps: Math.round(Number(policy.slippage_bps) || 500) };
const tradeLimits = getTradeLimits(agent.meta);
let input;
try { input = parseTradeInput(body, tradeLimits); }
catch (e) {
await markGraduation(policy.id, { status: `failed:${e?.code || 'invalid'}`, terminal: false });
return 'graduation_distribute_failed';
}
input.idempotencyKey = `mm:${policy.id}:graduation_distribute`;
input.simulate = simulate;
let result;
try {
result = await executeAgentTrade({ id: agent.id, userId: agent.userId, meta: agent.meta, input, source: 'mm:graduation_distribute', sourceMeta: { policy_id: policy.id, mint: policy.mint } });
} catch (e) {
await markGraduation(policy.id, { status: `failed:${e?.message?.slice(0, 60) || 'error'}`, terminal: false });
return 'graduation_distribute_failed';
}
if (!result.ok) {
await recordActionAndAdvance({ policy, action: { kind: 'graduation_distribute', triggerReason: 'graduated', priceSol: price, side: 'sell', status: result.code === 'firewall_blocked' ? 'blocked' : 'failed', detail: `${result.code}: ${result.message || ''}`.slice(0, 280) } });
await markGraduation(policy.id, { status: `failed:${result.code}`, terminal: false });
return 'graduation_distribute_failed';
}
const d = result.data || {};
const isSim = d.simulated === true || simulate;
const solMoved = isSim ? lamports(inventoryWhole * price) : Math.round((d.sol_received ?? 0) * SOL);
await recordActionAndAdvance({
policy,
action: { kind: 'graduation_distribute', side: 'sell', triggerReason: 'graduated', priceSol: price, solLamports: Number(solMoved), tokenAmount: inventoryWhole, venue: d.venue || 'amm', signature: d.signature && d.signature !== 'SIMULATED' ? d.signature : null, custodyEventId: d.custody_event_id ?? null, status: isSim ? 'simulated' : 'executed', detail: isSim ? 'paper distribute (simulate)' : 'liquidated inventory to SOL for distribution' },
effect: { solLamports: Number(solMoved) },
});
await markGraduation(policy.id, { status: 'done', signature: d.signature || null, terminal: true });
if (render) {
render.sizeSol = Math.max(0, Number(solMoved) || 0) / SOL;
render.sideBuy = false;
render.signature = d.signature && d.signature !== 'SIMULATED' ? d.signature : null;
}
return 'graduation_distribute';
}
// Record a non-firing decision. Routine pacing/budget/dust gates fire on EVERY
// sweep, so persisting each one would flood the ledger — those update the
// heartbeat (last_eval_at + last_error) instead, which the UI shows as a "what
// it's doing right now" note. Only NOTABLE events — an anti-wash block or a
// failure — earn a permanent ledger row.
async function skip({ policy, intent, price, status, detail, reason }) {
if (status === 'blocked' || status === 'failed') {
await recordActionAndAdvance({
policy,
action: { kind: intent.kind, side: intent.side, triggerReason: intent.reason, priceSol: price, status, detail, meta: { reason } },
});
} else {
await markEvaluated(policy.id, { error: `holding: ${detail}`.slice(0, 200) });
}
return reason;
}