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-sniper — the only module that signs and broadcasts.
//
// executeBuy / executeSell own every guardrail, the idempotency lock, the trade
// build, the broadcast, and the agent_sniper_positions writes. In `simulate`
// mode the full path runs against REAL on-chain quotes but the broadcast is
// skipped (sig = 'SIMULATED') — an ops safety toggle, never the default.
import { sql } from '../../api/_lib/db.js';
import { log } from './log.js';
import { loadAgentKeypair } from './keys.js';
import { mayhemGate } from './mayhem-gate.js';
import { reviewBuy, resolveRiskOfficerLevel } from './risk-officer.js';
import { marketCapBandReason } from './scorer.js';
import { recordJournal, journalEntry } from './journal.js';
import { getTradeCtx, signAndSend, submitProtectedTrade } from './trade-client.js';
import { countOpenPositions, getDailySpend, getRealizedNetLamports, effectiveDailyLossLimitLamports } from './strategy-store.js';
import { notifyBuy, notifySell } from '../../api/_lib/sniper/notify.js';
import { getPolicyRules } from '../../api/_lib/spend-policy-rules.js';
import {
getSpendLimits, enforceSpendLimit, SpendLimitError, recordSpend, lamportsToUsd,
checkConcurrency, checkDailyBudgetLamports, checkPriceImpact,
checkDailyLoss, recordCustodyEvent, resolveEntrySize,
} from '../../api/_lib/agent-trade-guards.js';
import { shouldGiveUpReconcile, reconcileParkAnchor } from './exit-logic.js';
import { buildAmmSellInstructions, quoteAmmBuy, buildAmmBuyInstructions } from './amm-exit.js';
import { getWalletBaseBalance, reconcileVanishedBag } from './reconcile.js';
import { assessTradeSafety, recordFirewallDecision, criticalFirewallReason } from '../../api/_lib/trade-firewall.js';
import { recordDecision } from '../../api/_lib/reasoning-ledger.js';
import { searchMemories } from '../../api/_lib/memory-store.js';
import { screenPush } from './screen-push.js';
import { buildAgentTradeFee } from '../../api/_lib/pump-platform-fee.js';
import { reclaimMintRent } from './rent-reclaim.js';
// Self-rated conviction for a snipe entry, 0..1. Lower price impact and a clean
// firewall verdict raise it; a warned verdict and heavy impact lower it. This is
// the prediction the Reasoning Ledger later scores for calibration — does an
// 80%-confidence snipe actually exit profitably 80% of the time?
function snipeConfidence({ priceImpactPct, maxImpactPct, firewallVerdict }) {
const impactPenalty = Math.min(1, Math.max(0, priceImpactPct) / (maxImpactPct > 0 ? maxImpactPct : 10)) * 0.4;
const fwBonus = firewallVerdict === 'allow' ? 0.1 : firewallVerdict === 'warn' ? -0.15 : 0;
const c = 0.6 + fwBonus - impactPenalty;
return Math.min(0.95, Math.max(0.05, c));
}
// Capture an opened snipe as a tamper-evident decision in the agent's reasoning
// ledger. Best-effort: the on-chain buy has already settled, so a ledger-write
// failure must never throw the trade away. Reconciled later against the closed
// position's realized P&L by api/cron/reconcile-decisions.js.
async function recordSnipeDecision({ strat, network, mint, posId, sig, mode, priceImpactPct, firewall, perTradeLamports, riskOfficer }) {
try {
const perTradeSol = Number(BigInt(perTradeLamports)) / 1e9;
const confidence = snipeConfidence({
priceImpactPct,
maxImpactPct: Number(strat.max_price_impact_pct) || 10,
firewallVerdict: firewall?.verdict || null,
});
const trigger = mint.entry_trigger || 'new_mint';
const rationale =
`Sniped $${(mint.symbol || mint.mint.slice(0, 4)).toUpperCase()} on a ${trigger} trigger ` +
`with ${priceImpactPct.toFixed(2)}% price impact` +
(firewall ? `; firewall verdict ${firewall.verdict} (score ${firewall.score}).` : '.') +
` Committed ${perTradeSol.toFixed(4)} SOL expecting a profitable exit.`;
// Memories the agent already holds about this token. Their ids ride along on
// the decision so the closed position's P&L can be written back onto them.
const recalled = await searchMemories(strat.agent_id, mint.mint, { topK: 5, minScore: 0.5, bump: false })
.then((r) => r.results)
.catch(() => []);
await recordDecision({
agentId: strat.agent_id,
kind: 'snipe',
recallIds: recalled.map((m) => m.id),
subjectRef: mint.mint,
actionRef: String(posId),
confidence,
network,
inputs: {
entry_trigger: trigger,
trigger_ref: mint.trigger_ref || null,
price_impact_pct: Number(priceImpactPct.toFixed(4)),
per_trade_sol: Number(perTradeSol.toFixed(6)),
firewall: firewall ? { verdict: firewall.verdict, score: firewall.score } : null,
position_id: posId,
buy_sig: sig && sig !== 'SIMULATED' ? sig : null,
mode,
symbol: mint.symbol || null,
llm: mint.llm ? { model: mint.llm.model, confidence: mint.llm.confidence, thesis: mint.llm.thesis } : null,
// The adversarial second opinion, when one was ENFORCED on this trade.
// A shadow-mode review is a counterfactual, not part of the decision,
// so it lives in sniper_risk_reviews and never in the ledger's inputs.
risk_officer: riskOfficer || null,
},
prediction: { direction: 'up', basis: 'snipe entry expects a profitable exit', metric: 'realized_pnl' },
rationale,
});
} catch (err) {
log.warn?.('ledger_record_failed', { agent: strat.agent_id, mint: mint.mint, message: err?.message });
}
}
// How long a position may sit in reconcile_pending (bag provably gone, emptying
// tx not found) before the executor gives up, books it closed with unknown
// proceeds, and frees the arm's concurrency slot. Generous enough to cover RPC
// history lag by orders of magnitude — the observed lag is seconds to minutes,
// and anything still unresolved after this is not coming back.
const RECONCILE_GIVE_UP_MS = 6 * 60 * 60 * 1000;
// ── per-agent serialization ────────────────────────────────────────────────
// Single-worker assumption: a per-agent in-process lock makes the budget +
// concurrency checks race-free without a DB reservation. (Scaling to N workers
// would require an atomic spend reservation instead — documented in README.)
const _locks = new Map();
async function withAgentLock(agentId, fn) {
const prev = _locks.get(agentId) || Promise.resolve();
let release;
const next = new Promise((r) => (release = r));
_locks.set(agentId, prev.then(() => next));
await prev;
try {
return await fn();
} finally {
release();
if (_locks.get(agentId) === next) _locks.delete(agentId);
}
}
function bn(ctx, v) {
return new ctx.BN(BigInt(v).toString());
}
// ── shared per-agent spend policy ────────────────────────────────────────────
// Bridges the sniper to the same ceiling that governs withdraw / x402 / trade
// (api/_lib/agent-trade-guards.js). Returns { blocked, reason }. Never throws:
// the sniper's own lamports caps stay the hard backstop, so a pricing or DB
// hiccup here degrades to "allow" rather than stalling the trader.
async function enforceSharedSpendPolicy(agentId, network, perTradeLamports, { holderRef = null, target = null } = {}) {
try {
const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
const limits = getSpendLimits(row?.meta);
const policy = getPolicyRules(row?.meta);
// Gate when there's something to enforce: a USD ceiling, least-privilege mode
// (require_capabilities), or any natural-language policy rule. Otherwise skip —
// keep the hot path price-call- and query-free.
const needGate = limits.require_capabilities || limits.daily_usd != null || limits.per_tx_usd != null || policy.rules.length > 0;
if (!needGate) return { blocked: false };
let usdValue = null;
try {
usdValue = await lamportsToUsd(perTradeLamports);
} catch {
// Can't price the SOL spend right now. If a capability is REQUIRED we still
// enforce scope (action/target/expiry/revoked) with a null USD value — only
// the per-use/aggregate USD metering is skipped. If capabilities aren't
// required, the USD caps can't bite, so don't block (lamports caps hold).
if (!limits.require_capabilities) return { blocked: false };
}
// Pass the strategy as the capability holder + the mint as the spend target so
// a strategy-scoped, mint-restricted session key is resolved + enforced here.
const res = await enforceSpendLimit({
agentId, limits, policyRules: policy, category: 'snipe', usdValue, asset: 'SOL', network,
capabilityHolderRef: holderRef, target,
});
return { blocked: false, capabilityId: res?.capabilityId || null };
} catch (err) {
if (err instanceof SpendLimitError) return { blocked: true, reason: err.code || 'spend_limit' };
log.warn?.('spend_policy_check_failed', { agent: agentId, message: err?.message });
return { blocked: false };
}
}
// Record a confirmed/simulated snipe buy into the shared custody ledger so it
// counts toward the per-agent daily ceiling and shows in the audit trail.
// Awaited by the caller (not fire-and-forget): the on-chain buy has already
// settled, so a ledger-write failure must never throw the trade away — but we
// must finish the write before returning so a rapid next snipe sees this spend
// against the ceiling rather than racing an unwritten record. Prices the SOL
// spend best-effort; a pricing hiccup records lamports with a null USD value.
async function recordSnipeSpend({ agentId, userId, network, lamports, signature, mode, mint, capabilityId = null }) {
try {
let usd = null;
try { usd = await lamportsToUsd(lamports); } catch { usd = null; }
await recordSpend({
agentId, userId, category: 'snipe', network, asset: 'SOL',
amountLamports: lamports, usd, capabilityId,
signature: signature && signature !== 'SIMULATED' ? signature : null,
status: mode === 'live' ? 'confirmed' : 'ok',
meta: { mint, mode },
});
} catch (err) {
log.warn?.('snipe_spend_record_failed', { agent: agentId, message: err?.message });
}
}
// Build the spend-guard hook the execution engine calls BEFORE appending a Jito
// tip. A tip is real SOL leaving the agent wallet, so it must obey the SAME
// ceilings as the trade itself: the kill switch (frozen wallet), the rolling
// daily SOL budget (tip + already-committed spend must fit the strategy's
// daily_budget_lamports), and the cross-path USD ceiling. On a breach the hook
// THROWS with code 'spend_guard' — the engine vetoes the tip and falls back to
// the protected route, so a tip can never bypass a limit. On allow it records the
// real tip outflow into agent_custody_events (category 'mev_tip') so it counts
// toward the daily ceiling and shows in the owner's audit trail.
function makeTipGuard({ strat, network, alreadyCommittedLamports, dailySpentLamports }) {
return async function onTip(tipLamports, route) {
const tip = BigInt(tipLamports);
if (tip <= 0n) return;
// Kill switch / wallet freeze — the same gate every autonomous spend honors.
if (strat.kill_switch === true) {
throw Object.assign(new Error('strategy kill switch is on'), { code: 'spend_guard' });
}
let limits;
let policyDoc = null;
try {
const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${strat.agent_id} AND deleted_at IS NULL`;
limits = getSpendLimits(row?.meta);
policyDoc = getPolicyRules(row?.meta);
} catch {
limits = null;
}
if (limits?.frozen) {
throw Object.assign(new Error('agent wallet is frozen'), { code: 'spend_guard' });
}
// Daily SOL budget — the tip stacks on the buy already committed this attempt
// plus the day's prior spend. Keep the wallet inside the strategy budget.
const budget = BigInt(strat.daily_budget_lamports);
if (dailySpentLamports + alreadyCommittedLamports + tip > budget) {
throw Object.assign(new Error('tip would exceed daily budget'), { code: 'spend_guard' });
}
// Cross-path USD ceiling (best-effort price; a pricing outage records lamports
// without a USD value rather than blocking — the lamports budget above holds).
let usd = null;
try {
usd = await lamportsToUsd(tip);
await enforceSpendLimit({ agentId: strat.agent_id, limits, policyRules: policyDoc, category: 'snipe', usdValue: usd, asset: 'SOL', network });
} catch (err) {
if (err instanceof SpendLimitError) {
throw Object.assign(new Error(err.message), { code: 'spend_guard' });
}
// pricing/RPC hiccup — fall through and record lamports only.
}
// Record the real tip outflow into the shared custody ledger.
await recordCustodyEvent({
agentId: strat.agent_id, userId: strat.user_id, eventType: 'spend',
category: 'mev_tip', network, asset: 'SOL', amountLamports: tip, usd,
status: 'confirmed', reason: 'jito_tip',
meta: { mint: strat._tip_mint || null, route, mode: strat.mev_tip_mode || 'off' },
}).catch((err) => log.warn?.('mev_tip_record_failed', { agent: strat.agent_id, message: err?.message }));
};
}
/**
* Attempt to snipe `mint` for `strat`. All checks short-circuit before any tx.
* @returns {Promise<{ status: string, reason?: string, sig?: string }>}
*/
export async function executeBuy({ cfg, strat, mint, throttle }) {
return withAgentLock(strat.agent_id, async () => {
let perTrade = BigInt(strat.per_trade_lamports);
const tag = { agent: strat.agent_id, mint: mint.mint, symbol: mint.symbol };
// 0. Mayhem exclusion (owner rule) — NEVER buy pump.fun Mayhem tokens, only
// regular launches. First gate, so a Mayhem mint costs no throttle slot,
// no decrypt, and no position row. This is the chokepoint every trigger
// path (new_mint / intel / alpha / first_claim / radar / swarm) flows
// through, so the rule holds everywhere, not just the standalone fleet.
const mayhem = await mayhemGate(mint.mint, cfg);
if (!mayhem.pass) return skip(tag, mayhem.reason);
// 0b. Market-cap band (owner rule: buy only $10k–$100k). Enforced HERE at the
// shared chokepoint — not just in scoreMint/scoreIntel — so alpha_hunt,
// first_claim, prelaunch_radar and swarm can't bypass the band the way
// they did before. FAIL CLOSED: a strategy that declares a band never buys
// a coin whose market cap we can't confirm is inside it. Paths that carry
// no mcap (e.g. pre-launch triggers) are correctly skipped when a band is
// set — you cannot buy "$10k–$100k" on a coin you can't price.
const bandReason = marketCapBandReason(mint.market_cap_usd, strat);
if (bandReason) return skip(tag, bandReason);
// 2. concurrency cap
const open = await countOpenPositions(strat.agent_id, cfg.network);
const concurrency = checkConcurrency(open, strat.max_concurrent_positions);
if (concurrency) return skip(tag, concurrency.reason);
// 3. daily budget cap — shrink to the day's remainder rather than sitting out.
// An arm whose configured size grew past its OWN daily budget (optimizer
// drift moves the two knobs independently) could never clear `spent + size
// <= budget` even on a fresh day with zero spend: permanently armed,
// permanently unable to buy, and silent about it. Two arms sat dead this way
// for a week. Shrinking honours the cap exactly — the day's total still
// cannot exceed `daily_budget_lamports` — and only ever lowers risk, the
// same shrink-don't-skip rule the wallet headroom below already applies.
const spent = await getDailySpend(strat.agent_id, cfg.network);
const dailyBudget = BigInt(strat.daily_budget_lamports);
const budget = checkDailyBudgetLamports(spent, perTrade, dailyBudget);
if (budget) {
const remaining = dailyBudget - BigInt(spent);
if (remaining < cfg.minTradeLamports) return skip(tag, budget.reason);
log.info('trade size clamped to the day\'s remaining budget', {
...tag, configured: perTrade.toString(), clamped: remaining.toString(),
});
perTrade = remaining;
}
// 3c. realized-loss circuit breaker (portfolio layer). The per-trade caps
// above (budget, headroom, impact) can't stop a fleet that bleeds one
// losing entry at a time — this does. Once the day's NET realized loss
// crosses the cap the agent stops opening positions AND the auto-funder
// stops refilling its wallet, so the master can't keep pouring SOL after
// a wallet that only loses. Priced only when a cap is configured (env
// SNIPER_MAX_DAILY_LOSS_SOL or per-strategy), so the hot path stays free
// otherwise. A DB hiccup never blocks — the lamports caps stay the backstop.
const lossLimit = effectiveDailyLossLimitLamports(strat);
if (lossLimit != null) {
try {
const netRealized = await getRealizedNetLamports(strat.agent_id, cfg.network);
const loss = checkDailyLoss(netRealized, lossLimit);
if (loss) return skip(tag, loss.reason);
} catch (err) {
log.warn('realized-loss check failed — allowing on lamports backstop', { ...tag, err: err?.message });
}
}
// 3b. shared per-agent spend policy (the same ceiling that governs
// withdraw / x402 / trade). Opt-in: only priced + enforced when the owner
// has actually set a USD ceiling, so the hot snipe path stays price-call-
// free otherwise. Pricing/DB hiccups never block — the lamports caps above
// remain the hard backstop.
const policy = await enforceSharedSpendPolicy(strat.agent_id, cfg.network, perTrade, {
holderRef: String(strat.id), target: mint.mint,
});
if (policy.blocked) return skip(tag, policy.reason);
const spendCapabilityId = policy.capabilityId || null;
// 4. wallet + funds PRE-CHECK, before claiming a slot. An agent with no
// wallet or too little SOL can never fill the buy — skip it cleanly rather
// than write a 'failed' position row that only noises up the feeds. (These
// were the dominant 'failed' rows: every unfunded agent evaluating every
// mint left one behind.)
let keypair;
let address;
let ctx;
let preBalance;
try {
const loaded = await loadAgentKeypair(strat.agent_id, strat.user_id, 'sniper_buy');
if (!loaded) return skip(tag, 'no_wallet');
({ keypair, address } = loaded);
ctx = await getTradeCtx(cfg.network);
preBalance = BigInt(await ctx.connection.getBalance(keypair.publicKey, 'confirmed'));
} catch (err) {
log.warn('wallet precheck failed', { ...tag, err: err?.message });
return skip(tag, 'wallet_precheck_failed');
}
// Learning > profit (owner directive): a wallet too poor for the strategy's
// configured size still trades, shrunk to what it can actually afford. It
// sits out only when even a shrunk buy could not clear the pre-broadcast
// simulations. Safe to shrink: every check already passed above (budget,
// spend policy) is a ceiling a smaller trade only clears more easily.
const sized = resolveEntrySize(preBalance, perTrade, cfg.minTradeLamports);
if (sized.skip) return skip(tag, sized.skip);
perTrade = sized.sizeLamports;
// 4b. global throttle (platform-wide backstop), taken only by an entry that
// can actually proceed. It used to be the first gate, so a dry arm burned
// a slot on every candidate before discovering it could not pay: in one
// 6-hour window a starved arm took 1,428 throttle slots while the one
// funded arm lost entries to the same throttle.
if (!throttle.tryConsume()) return skip(tag, 'global_throttle');
// 5. idempotency lock — claim the (agent,mint,network) slot BEFORE the tx.
// The wallet is known now, so it's written on the claim (no later UPDATE).
const claimed = await sql`
INSERT INTO agent_sniper_positions
(strategy_id, agent_id, user_id, wallet, network, mint, symbol, name, status,
entry_trigger, trigger_ref)
VALUES (${strat.id}, ${strat.agent_id}, ${strat.user_id}, ${address}, ${cfg.network},
${mint.mint}, ${mint.symbol || null}, ${mint.name || null}, 'opening',
${mint.entry_trigger || 'new_mint'}, ${mint.trigger_ref || null})
ON CONFLICT (agent_id, mint, network) DO NOTHING
RETURNING id
`;
if (!claimed.length) return skip(tag, 'already_held');
const posId = claimed[0].id;
try {
const mintPk = new ctx.web3.PublicKey(mint.mint);
const slippagePct = strat.slippage_bps / 100;
// Venue: an 'amm' entry (graduation_ride) trades the post-migration pump
// AMM pool; everything else prices the bonding curve. The AMM path
// enforces a wSOL quote itself (amm_quote_not_sol), so the explicit
// require_sol_quote check below only guards the curve branch.
const ammEntry = mint.venue === 'amm';
// 6. quote + price-impact circuit breaker. Priced through a helper so the
// trade can be re-quoted at a smaller size if the risk officer (6c)
// cuts it; the impact we RECORD must describe the trade we actually
// send, not the larger one that was refused.
const quoteFor = async (size) => {
if (ammEntry) {
const ammQuote = await quoteAmmBuy({
network: cfg.network, mint: mint.mint, quoteAmount: bn(ctx, size), slippagePct,
});
return { priceImpactPct: ammQuote.priceImpactPct };
}
const curveQuote = await ctx.client.quoteForBuy({ mint: mintPk, quoteAmount: bn(ctx, size), slippagePct });
if (strat.require_sol_quote && !curveQuote.quoteMint.equals(ctx.web3.PublicKey.default) && curveQuote.quoteMint.toBase58() !== 'So11111111111111111111111111111111111111112') {
return { rejected: 'quote_not_sol' };
}
return curveQuote;
};
let quote = await quoteFor(perTrade);
if (quote.rejected) return await fail(posId, tag, quote.rejected);
const impact = checkPriceImpact(Number(quote.priceImpactPct), Number(strat.max_price_impact_pct));
if (impact) return await fail(posId, tag, impact.reason);
// 6b. rug/honeypot firewall — a REAL on-chain simulated buy→sell
// round-trip + authority audit, run after the quote and BEFORE any
// broadcast. Per-strategy `firewall_level`: 'block' (default) aborts a
// 'block' verdict; 'warn' logs the verdict but proceeds (raw speed);
// 'off' skips the check. Never throws — the kernel degrades to 'warn'
// when a data source is down, so a firewall hiccup can't stall the trader.
const firewallLevel = ['warn', 'off'].includes(strat.firewall_level) ? strat.firewall_level : 'block';
let firewallSnapshot = null; // captured for the reasoning ledger
if (firewallLevel !== 'off') {
const assessment = await assessTradeSafety({
network: cfg.network,
mint: mint.mint,
side: 'buy',
payer: keypair.publicKey,
quoteAmount: perTrade,
connection: ctx.connection,
priceImpactPct: Number(quote.priceImpactPct),
// The balance is already in hand from the step-4 precheck. Handing it to
// the firewall lets the round-trip probe shrink to a size this wallet can
// simulate, so a thin wallet reads as a thin wallet — not as a honeypot.
payerBalanceLamports: preBalance,
}).catch((err) => {
log.warn?.('firewall_check_failed', { ...tag, message: err?.message });
return null;
});
// FAIL CLOSED. Two ways this used to buy an unvetted rug and no longer does:
// 1. assessment === null (the whole firewall threw) → a 'block'-level
// strategy must NOT broadcast a coin it never vetted.
// 2. verdict === 'warn' but a CRITICAL check (round-trip sim couldn't
// run, mint/freeze authority active, authority unreadable) → the
// warning means "couldn't prove it's safe", not "safe". Block it.
if (!assessment) {
if (firewallLevel === 'block') {
await sql`
UPDATE agent_sniper_positions
SET status = 'failed', error = 'firewall_block: firewall_unavailable', closed_at = now()
WHERE id = ${posId}
`;
log.warn('buy blocked — firewall unavailable (fail-closed)', { ...tag });
screenPush(`$${(mint.symbol || mint.mint.slice(0, 6)).toUpperCase()} blocked — safety check unavailable`, 'analysis');
return { status: 'failed', reason: 'firewall_unavailable' };
}
// warn/off levels keep the raw-speed escape hatch: proceed without a vet.
} else {
const critical = criticalFirewallReason(assessment);
const enforced = firewallLevel === 'block' && (assessment.verdict === 'block' || !!critical);
recordFirewallDecision({
mint: mint.mint, network: cfg.network, side: 'buy',
verdict: assessment.verdict, score: assessment.score, simulated: assessment.simulated,
checks: assessment.checks, reasons: assessment.reasons,
source: 'sniper', agentId: strat.agent_id, userId: strat.user_id,
quoteLamports: perTrade, enforced,
}).catch(() => {});
if (enforced) {
const reason = critical || assessment.reasons?.[0] || 'firewall_blocked';
await sql`
UPDATE agent_sniper_positions
SET status = 'failed', error = ${`firewall_block: ${reason}`.slice(0, 280)}, closed_at = now()
WHERE id = ${posId}
`;
log.warn('buy blocked by firewall', { ...tag, score: assessment.score, critical: critical || null, reasons: assessment.reasons });
screenPush(`$${(mint.symbol || mint.mint.slice(0, 6)).toUpperCase()} blocked by firewall: ${reason}`, 'analysis');
return { status: 'failed', reason: 'firewall_block' };
}
if (assessment.verdict !== 'allow') {
log.info('firewall warn (proceeding)', { ...tag, level: firewallLevel, verdict: assessment.verdict, score: assessment.score });
}
firewallSnapshot = { verdict: assessment.verdict, score: assessment.score };
}
}
// 6c. adversarial Risk Officer: the independent second opinion. Every
// gate above answers a question with a number; this one is handed the
// proposed trade plus the agent's own thesis and told to find what the
// agent missed. Runs LAST so it sees the real price impact and the real
// firewall verdict. Default level is 'shadow': it records the veto it
// WOULD have cast and changes nothing, because enforcement decides what
// the live fleet buys with real SOL and arming that is an owner call.
// Fails OPEN, unlike the firewall: it sits behind a safety proof that
// already passed, so a reviewer outage must never halt the fleet.
const officer = await reviewBuy({
cfg, strat, mint, posId,
perTradeLamports: perTrade,
minTradeLamports: cfg.minTradeLamports,
budgetLeftLamports: dailyBudget > BigInt(spent) ? dailyBudget - BigInt(spent) : 0n,
slotsLeft: Math.max(0, Number(strat.max_concurrent_positions) - open),
priceImpactPct: Number(quote.priceImpactPct),
firewall: firewallSnapshot,
agentReason: mint.llm?.thesis || null,
});
if (officer.blocked) {
await sql`
UPDATE agent_sniper_positions
SET status = 'failed', error = ${`risk_officer_veto: ${officer.reason}`.slice(0, 280)}, closed_at = now()
WHERE id = ${posId}
`;
log.warn('buy vetoed by the risk officer', { ...tag, reasons: officer.review?.reasons });
screenPush(`$${(mint.symbol || mint.mint.slice(0, 6)).toUpperCase()} vetoed by risk review: ${officer.reason}`, 'analysis');
return { status: 'failed', reason: 'risk_officer_veto' };
}
if (officer.resized) {
log.info('trade size cut by the risk officer', {
...tag, from: perTrade.toString(), to: officer.sizeLamports.toString(),
reasons: officer.review?.reasons,
});
perTrade = officer.sizeLamports;
// A smaller buy can only move the curve less, so the breaker above
// cannot newly trip; re-quote purely so the recorded entry impact is
// the one this trade actually pays.
const reQuote = await quoteFor(perTrade).catch(() => null);
if (reQuote && !reQuote.rejected) quote = reQuote;
}
const officerSnapshot = officer.review
? {
level: resolveRiskOfficerLevel(strat, cfg.riskOfficer),
severity: officer.review.severity,
reasons: officer.review.reasons,
resized: officer.resized,
}
: null;
// 7. build + (live) broadcast
let built;
if (ammEntry) {
const ammBuilt = await buildAmmBuyInstructions({
network: cfg.network, mint: mint.mint, user: keypair.publicKey,
quoteAmount: bn(ctx, perTrade), slippagePct,
});
built = { instructions: ammBuilt.instructions, expectedBaseTokens: ammBuilt.expectedBaseOut };
} else {
built = await ctx.client.buildBuyInstructions({
mint: mintPk, user: keypair.publicKey, quoteAmount: bn(ctx, perTrade), slippagePct,
});
}
const baseAmount = BigInt(built.expectedBaseTokens.toString());
if (baseAmount <= 0n) return await fail(posId, tag, 'zero_tokens');
// The three.ws trade fee rides in the buy transaction for customer agents
// and is part of the position's cost basis, so paper and live P&L both
// net it out. Platform-owned fleets pay nothing.
const buyFee = await buildAgentTradeFee({ network: cfg.network, payer: keypair.publicKey, userId: strat.user_id, side: 'buy', lamports: perTrade });
if (buyFee) built = { ...built, instructions: [...built.instructions, ...buyFee.instructions] };
const entryCost = perTrade + (buyFee ? BigInt(buyFee.disclosure.amount) : 0n);
let sig = 'SIMULATED';
// Execution telemetry — only set on a live broadcast; simulate keeps nulls
// (except a 'simulated' route marker so the UI can label paper fills).
let exec = { route: 'simulated', tipLamports: 0, priorityFeeMicroLamports: null, landedMs: null };
screenPush(`Buying $${(mint.symbol || mint.mint.slice(0, 6)).toUpperCase()} — sending tx`, 'trade');
if (cfg.mode === 'live') {
const tipMode = ['economy', 'turbo'].includes(strat.mev_tip_mode) ? strat.mev_tip_mode : 'off';
// The tip guard needs to know what's already committed today + this trade.
strat._tip_mint = mint.mint;
const onTip = makeTipGuard({
strat, network: cfg.network,
alreadyCommittedLamports: perTrade,
dailySpentLamports: spent,
});
const result = await submitProtectedTrade(ctx, keypair, built.instructions, cfg.confirmTimeoutMs, {
tipMode, onTip, preSimulated: firewallLevel !== 'off',
});
sig = result.signature;
exec = {
route: result.route,
tipLamports: result.tipLamports,
priorityFeeMicroLamports: result.priorityFeeMicroLamports,
landedMs: result.landedMs,
};
log.trade('exec', { ...tag, route: result.route, tip: result.tipLamports, fee: result.priorityFeeMicroLamports, landed_ms: result.landedMs, attempts: result.attempts, fallback: result.fallbackReason || null });
}
const pricePerToken = Number(perTrade) / Number(baseAmount);
// An AMM entry is born graduated: flag it exactly like a curve position
// that graduated mid-hold, so the sweep re-quotes it off the AMM and
// executeSell routes the exit there instead of the dead curve.
await sql`
UPDATE agent_sniper_positions SET
status = 'open', buy_sig = ${sig},
error = ${ammEntry ? 'graduated:amm_entry' : null},
entry_quote_lamports = ${entryCost.toString()},
stake_lamports = ${entryCost.toString()},
base_amount = ${baseAmount.toString()},
entry_price_lamports_per_token = ${pricePerToken},
entry_price_impact_pct = ${Number(quote.priceImpactPct)},
peak_value_lamports = ${perTrade.toString()},
last_value_lamports = ${perTrade.toString()},
exec_route = ${exec.route},
tip_lamports = ${exec.tipLamports != null ? String(exec.tipLamports) : null},
priority_fee_microlamports = ${exec.priorityFeeMicroLamports != null ? String(exec.priorityFeeMicroLamports) : null},
landed_ms = ${exec.landedMs},
last_quoted_at = now()
WHERE id = ${posId}
`;
log.trade('buy', { ...tag, mode: cfg.mode, sig, sol: lamportsToSol(perTrade), base: baseAmount.toString(), impact: Number(quote.priceImpactPct).toFixed(2) });
// Journal the entry WITH its reasoning — the learn-what-works surface.
await journalEntry({
cfg, strat, mint, posId, sig,
score: mint.score ?? null,
rationale: `Entered on ${mint.entry_trigger || 'new_mint'}${mint.market_cap_usd != null ? ` at ~$${Math.round(mint.market_cap_usd).toLocaleString()} mcap` : ''}${firewallSnapshot ? ` (firewall ${firewallSnapshot.verdict}, score ${firewallSnapshot.score})` : ''}; ${lamportsToSol(perTrade).toFixed(4)} SOL, impact ${Number(quote.priceImpactPct).toFixed(2)}%.${mint.llm ? ` LLM ${mint.llm.model} judged buy at ${Math.round(mint.llm.confidence * 100)}%: ${mint.llm.thesis}` : ''}`,
});
screenPush(`Bought $${(mint.symbol || mint.mint.slice(0, 6)).toUpperCase()} at ${lamportsToSol(perTrade).toFixed(4)} SOL — position open`, 'trade');
notifyBuy({ agentName: strat.agent_name || strat.agent_id, symbol: mint.symbol, mint: mint.mint, solSpent: lamportsToSol(perTrade), mode: cfg.mode, sig, chatId: strat.telegram_chat_id || null });
await recordSnipeSpend({ agentId: strat.agent_id, userId: strat.user_id, network: cfg.network, lamports: entryCost, signature: sig, mode: cfg.mode, mint: mint.mint, capabilityId: spendCapabilityId });
await recordSnipeDecision({
strat, network: cfg.network, mint, posId, sig, mode: cfg.mode,
priceImpactPct: Number(quote.priceImpactPct), firewall: firewallSnapshot, perTradeLamports: perTrade,
riskOfficer: officerSnapshot,
});
return { status: 'open', sig };
} catch (err) {
return await fail(posId, tag, errCode(err), err);
}
});
}
/**
* Close `position` for `reason`. Re-quotes fresh for slippage, builds the sell,
* broadcasts (live), records realized P&L.
*/
export async function executeSell({ cfg, position, reason, fraction = 1, recoversInitials = false, keepsMoonbag = false }) {
return withAgentLock(position.agent_id, async () => {
// Laddered exits sell only PART of the bag. Two different partials exist:
// recoversInitials: the take-initials leg; the position stays OPEN and the
// moon bag keeps trading under the exit rules.
// keepsMoonbag: a terminal exit that still refuses to sell the last
// slice; the position CLOSES for accounting (its P&L is
// booked and its concurrency slot is freed) while the
// remaining tokens are retained and ride indefinitely.
// Resolve the sell size in ppm of the current base amount so the remainder is
// exact with no float drift.
const f = Number(fraction);
const fullBase = BigInt(position.base_amount);
const ppm = f > 0 && f < 1 ? BigInt(Math.max(1, Math.min(999_999, Math.round(f * 1_000_000)))) : 1_000_000n;
let sellBaseBig = ppm === 1_000_000n ? fullBase : (fullBase * ppm) / 1_000_000n;
const partial = sellBaseBig > 0n && sellBaseBig < fullBase;
if (sellBaseBig <= 0n) sellBaseBig = fullBase; // degenerate fraction → full exit
// A partial that isn't a take-initials leg is a moon-bag close. If the
// fraction degenerated to a full sell there is no bag left to keep, so the
// flag drops with it rather than recording an empty bag.
const retainsMoonbag = keepsMoonbag && partial && !recoversInitials;
const tag = { agent: position.agent_id, mint: position.mint, symbol: position.symbol, reason, partial };
await sql`UPDATE agent_sniper_positions SET status = 'closing' WHERE id = ${position.id} AND status = 'open'`;
screenPush(`${partial ? (retainsMoonbag ? 'Banking profit, keeping a moon bag on' : 'Taking initials on') : 'Selling'} $${(position.symbol || position.mint.slice(0, 6)).toUpperCase()}: ${reason}`, 'trade');
try {
const loaded = await loadAgentKeypair(position.agent_id, position.user_id, 'sniper_sell');
if (!loaded) return await fail(position.id, tag, 'no_wallet');
const { keypair } = loaded;
const ctx = await getTradeCtx(cfg.network);
// Retry of a previously-failed sell → make the CHAIN the source of truth
// before re-broadcasting. A sell whose confirmation timed out may have
// landed anyway; retrying it then simulates a sell of tokens the wallet no
// longer holds and fails forever (pump 6023 NotEnoughTokensToSell), burning
// RPC every sweep. Balance 0 → find the landed tx and book its real
// proceeds; balance short of the DB amount → sell what's actually there.
if (position.error) {
const realBalance = await getWalletBaseBalance(ctx, keypair.publicKey, position.mint);
if (realBalance != null) {
if (realBalance === 0n) {
const reconciled = await reconcileVanishedBag({ ctx, position, reason });
if (reconciled) return { status: 'closed', reason: 'reconciled_onchain' };
// Emptying tx not found yet (history lag); hold for the next sweep
// rather than re-broadcasting a sell that cannot succeed.
//
// Two guards, both learned from production. The status guard: this
// UPDATE used to write status='open' unconditionally, which
// resurrected positions closed concurrently (by a reconcile in
// another sweep, or by an operator) — they kept sell_sig, closed_at
// and realized P&L while reading 'open', so a settled trade counted
// as live risk and held a concurrency slot. The time bound: the park
// itself had none, so a bag whose emptying tx could never be found
// re-parked every sweep forever and wedged that slot permanently.
if (shouldGiveUpReconcile(reconcileParkAnchor(position), RECONCILE_GIVE_UP_MS)) {
// The bag is provably gone but its proceeds are unknowable from
// chain history. Book it closed so the slot frees, and leave
// realized P&L NULL rather than inventing a number — every P&L
// query filters NULL out, so an unknown exit skews no report.
await sql`
UPDATE agent_sniper_positions SET
status = 'closed', exit_reason = 'error',
error = 'reconcile_unresolved',
reconcile_pending_since = NULL, closed_at = now()
WHERE id = ${position.id} AND status <> 'closed'
`;
log.warn('reconcile gave up; bag gone, proceeds unknown', {
...tag,
pending_since: position.reconcile_pending_since,
// The anchor actually measured, which differs from pending_since
// on a row parked before that column existed.
park_anchor: reconcileParkAnchor(position),
});
return { status: 'closed', reason: 'reconcile_unresolved' };
}
await sql`
UPDATE agent_sniper_positions SET
status = 'open', error = 'reconcile_pending',
reconcile_pending_since = coalesce(reconcile_pending_since, now()),
last_quoted_at = now()
WHERE id = ${position.id} AND status <> 'closed'
`;
return { status: 'retry', reason: 'reconcile_pending' };
}
if (realBalance < sellBaseBig) {
log.warn('sell clamped to real wallet balance', { ...tag, db_base: sellBaseBig.toString(), real_base: realBalance.toString() });
sellBaseBig = realBalance;
}
}
}
const mintPk = new ctx.web3.PublicKey(position.mint);
const baseAmount = bn(ctx, sellBaseBig);
const slippagePct = (position.slippage_bps ?? 500) / 100;
let expectedOut;
let built;
let venue = 'bonding_curve';
// A position already flagged graduated skips the dead curve and goes
// straight to the AMM — no point re-quoting a curve we know is complete.
const preGraduated = typeof position.error === 'string' && position.error.startsWith('graduated');
if (preGraduated) {
built = await buildGraduatedSell({ cfg, position, keypair, baseAmount, slippagePct });
expectedOut = built.expectedQuoteOut;
venue = 'amm';
} else {
try {
const quote = await ctx.client.quoteForSell({ mint: mintPk, baseAmount, slippagePct });
expectedOut = BigInt(quote.expectedQuoteOut.toString());
built = await ctx.client.buildSellInstructions({ mint: mintPk, user: keypair.publicKey, baseAmount, slippagePct });
} catch (err) {
// Graduation is the one "failure" that isn't one: the curve is
// complete, so route the same exit through the AMM pool instead of
// parking the bag. Any other error propagates to the retry handler.
if (err?.name !== 'CoinGraduatedError') throw err;
built = await buildGraduatedSell({ cfg, position, keypair, baseAmount, slippagePct });
expectedOut = built.expectedQuoteOut;
venue = 'amm';
}
}
// The trade fee on a sell is taken on the slippage-floor proceeds, so a fill
// at the floor still covers it, and it comes out of the leg's P&L.
const sellFloor = (BigInt(expectedOut) * BigInt(Math.max(0, Math.round((100 - slippagePct) * 100)))) / 10_000n;
const sellFee = await buildAgentTradeFee({ network: cfg.network, payer: keypair.publicKey, userId: position.user_id, side: 'sell', lamports: sellFloor });
if (sellFee) built = { ...built, instructions: [...built.instructions, ...sellFee.instructions] };
const sellFeeLamports = sellFee ? BigInt(sellFee.disclosure.amount) : 0n;
let sig = 'SIMULATED';
if (cfg.mode === 'live') {
sig = await signAndSend(ctx, keypair, built.instructions, cfg.confirmTimeoutMs);
} else if (venue === 'bonding_curve') {
expectedOut = BigInt(built.expectedQuoteOut.toString());
}
const entryFull = BigInt(position.entry_quote_lamports || '0');
// Cost basis of the tokens sold on THIS leg (scaled by the sold ppm), so a
// partial take-initials books the profit on just the half it sold and the
// remainder keeps its own proportional basis.
const soldCostBasis = partial ? (entryFull * ppm) / 1_000_000n : entryFull;
const legPnl = expectedOut - sellFeeLamports - soldCostBasis;
const priorRealized = BigInt(position.realized_pnl_lamports || '0');
const cumRealized = priorRealized + legPnl;
if (partial && !retainsMoonbag) {
// Take-initials: keep the position OPEN with the moon-bag remainder.
// Scale the cost basis down with the tokens, flag initials recovered so
// the ladder fires once, and RESET the trailing high-water to the
// remaining bag's value — the pre-sale full-position peak would instantly
// trip the trailing stop against the now-smaller moon bag.
const remainingBase = fullBase - sellBaseBig;
const remainingEntry = entryFull - soldCostBasis;
const remainingValueEst = Math.round((Number(expectedOut) * Number(remainingBase)) / Number(sellBaseBig));
await sql`
UPDATE agent_sniper_positions SET
status = 'open',
base_amount = ${remainingBase.toString()},
entry_quote_lamports = ${remainingEntry.toString()},
initials_recovered = ${recoversInitials ? true : position.initials_recovered === true},
peak_value_lamports = ${remainingValueEst},
last_value_lamports = ${remainingValueEst},
realized_pnl_lamports = ${cumRealized.toString()},
error = ${null},
last_quoted_at = now()
WHERE id = ${position.id}
`;
const legSol = lamportsToSol(legPnl);
log.trade('take-initials', { ...tag, venue, mode: cfg.mode, sig, sold_fraction: f, leg_pnl_sol: legSol, kept_moonbag_base: remainingBase.toString() });
await recordJournal({ position, cfg, event: 'take_initials', reason, sig, venue, soldFraction: f, legPnlLamports: legPnl, remainingBase });
screenPush(
`Took initials on $${(position.symbol || position.mint.slice(0, 6)).toUpperCase()} — +${legSol.toFixed(4)} SOL back, moon bag riding`,
'trade',
{ phase: 'take_initials', mint: position.mint, symbol: position.symbol || null, solDelta: legSol, soldFraction: f },
);
return { status: 'partial', sig, sold_fraction: f, leg_pnl: legPnl.toString(), venue };
}
const pnl = legPnl;
// Divide by the ORIGINAL stake. After a take-initials leg entryFull is only
// the moon bag's scaled-down basis, and dividing by it roughly doubled the
// booked % of every laddered trade (fed straight into the optimizer).
const stake = position.stake_lamports != null ? BigInt(position.stake_lamports) : entryFull;
const pnlPct = stake > 0n ? (Number(cumRealized) / Number(stake)) * 100 : 0;
// Tokens kept back on a moon-bag close, and the cost basis still sitting in
// them. Once initials were recovered that basis is ~0, which is the whole
// point: the bag is free, so a bag that goes to zero costs nothing and a
// bag that runs is pure upside. The position still books CLOSED here so its
// realized P&L lands in every existing report and its concurrency slot is
// released; only the tokens stay behind.
const keptBase = retainsMoonbag ? fullBase - sellBaseBig : 0n;
const keptEntry = retainsMoonbag ? entryFull - soldCostBasis : 0n;
const keptValueEst = retainsMoonbag && sellBaseBig > 0n
? Math.round((Number(expectedOut) * Number(keptBase)) / Number(sellBaseBig))
: 0;
await sql`
UPDATE agent_sniper_positions SET
status = 'closed', exit_reason = ${reason}, sell_sig = ${sig},
exit_quote_lamports = ${expectedOut.toString()},
realized_pnl_lamports = ${cumRealized.toString()},
realized_pnl_pct = ${pnlPct},
moonbag_base_amount = ${keptBase.toString()},
moonbag_entry_lamports = ${keptEntry.toString()},
moonbag_last_value_lamports = ${keptValueEst},
moonbag_opened_at = ${retainsMoonbag ? new Date().toISOString() : null},
error = ${null},
reconcile_pending_since = NULL,
closed_at = now()
WHERE id = ${position.id}
`;
await recordJournal({
position, cfg, event: retainsMoonbag ? 'exit_moonbag' : 'exit', reason, sig, venue,
soldFraction: retainsMoonbag ? f : 1, legPnlLamports: legPnl,
...(retainsMoonbag ? { remainingBase: keptBase } : {}),
});
const pnlSol = lamportsToSol(cumRealized);
log.trade(retainsMoonbag ? 'sell-keep-moonbag' : 'sell', {
...tag, venue, mode: cfg.mode, sig, pnl_sol: pnlSol, pnl_pct: pnlPct.toFixed(1),
...(retainsMoonbag ? { kept_moonbag_base: keptBase.toString(), sold_fraction: f } : {}),
});
// Price the realized SOL delta into USD best-effort for the live PnL
// ticker. A pricing hiccup just omits realizedUsd — the viewer's ticker
// falls back to SOL, which is the unit the sell actually returned.
let realizedUsd = null;
try {
const solUsd = await lamportsToUsd(1_000_000_000n);
if (Number.isFinite(solUsd)) realizedUsd = pnlSol * solUsd;
} catch { /* pricing offline — SOL-only ticker */ }
const sym = (position.symbol || position.mint.slice(0, 6)).toUpperCase();
screenPush(
retainsMoonbag
? `Banked ${pnlSol >= 0 ? '+' : ''}${pnlSol.toFixed(4)} SOL on $${sym} and kept a free moon bag riding`
: `Sold $${sym}: ${pnlPct >= 0 ? 'profit' : 'loss'} ${pnlSol >= 0 ? '+' : ''}${pnlSol.toFixed(4)} SOL`,
'trade',
{
phase: retainsMoonbag ? 'exit_moonbag' : 'exit',
mint: position.mint, symbol: position.symbol || null,
solDelta: pnlSol, pct: pnlPct, realizedUsd,
...(retainsMoonbag ? { moonbagBase: keptBase.toString() } : {}),
},
);
notifySell({ agentName: position.agent_name || position.agent_id, symbol: position.symbol, mint: position.mint, pnlSol, pnlPct, exitReason: reason, mode: cfg.mode, sig, chatId: position.telegram_chat_id || null });
// A full exit leaves the coin's token account empty; close it so its rent
// (~0.0015-0.002 SOL, as much as a whole small position) returns to the
// wallet. Separate tx, not awaited: the exit is already booked and a failed
// close must never hold the agent lock or touch the sell.
if (cfg.mode === 'live' && !retainsMoonbag) {
void reclaimMintRent({
ctx, keypair, mint: position.mint, tag,
sendTx: (ixs) => signAndSend(ctx, keypair, ixs, cfg.confirmTimeoutMs),
});
}
return { status: 'closed', sig, pnl: pnl.toString(), venue, moonbagBase: keptBase.toString() };
} catch (err) {
// A failed sell must NOT terminate the position — leave it 'open' so the
// next tick retries the exit rather than stranding the bag as 'failed'.
// Preserve the graduated marker so the retry stays on the AMM path instead
// of bouncing back through the dead curve to rediscover graduation.
const wasGraduated = typeof position.error === 'string' && position.error.startsWith('graduated');
const errState = wasGraduated ? `graduated:amm_exit_retry:${errCode(err)}` : errCode(err);
await sql`UPDATE agent_sniper_positions SET status = 'open', error = ${errState}, last_quoted_at = now() WHERE id = ${position.id}`;
log.warn('sell failed (will retry)', { ...tag, code: errCode(err), graduated: wasGraduated, err: err?.message });
screenPush(`Error: sell $${(position.symbol || position.mint.slice(0, 6)).toUpperCase()} failed (${errCode(err)}) — retrying`, 'activity');
return { status: 'retry', reason: errCode(err) };
}
});
}
// Build the AMM sell for a graduated position. Reuses the platform's pool
// resolution + PumpAmmSdk (api/pump/[action].js parity) so the exit prices off
// the live pool, with the slippage-derived min-out floor embedded on-chain. In
// `simulate` mode the instructions are still built (proving the path works) but
// never broadcast — expectedQuoteOut becomes the paper fill.
async function buildGraduatedSell({ cfg, position, keypair, baseAmount, slippagePct }) {
const { instructions, expectedQuoteOut } = await buildAmmSellInstructions({
network: cfg.network,
mint: position.mint,
user: keypair.publicKey,
baseAmount,
slippagePct,
});
return { instructions, expectedQuoteOut };
}
function skip(tag, reason) {
log.info('skip', { ...tag, reason });
return { status: 'skip', reason };
}
async function fail(posId, tag, reason, err) {
await sql`UPDATE agent_sniper_positions SET status = 'failed', error = ${reason}, closed_at = now() WHERE id = ${posId}`;
log.warn('buy aborted', { ...tag, reason, err: err?.message });
return { status: 'failed', reason };
}
function errCode(err) {
return err?.code || err?.name || 'error';
}
function lamportsToSol(l) {
return Number(BigInt(l)) / 1e9;
}