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
// POST /api/agents/:id/trade — discretionary, owner-authenticated pump.fun trade
// from the agent's OWN custodial wallet (server-signed).
//
// This is the discretionary sibling of the sniper: same instruction builders
// (PumpTradeClient buy/sell, AMM sell on graduation), same custodial key path
// (recoverSolanaAgentKeypair, audit-logged), and — critically — the SAME shared
// guardrail module (api/_lib/agent-trade-guards.js). The owner funds the agent
// wallet, then drives buys/sells through this endpoint; every trade is capped,
// budgeted, price-impact-broken, idempotent, and recorded into the custody
// ledger that backs the spend ceilings and the owner-facing audit feed.
//
// Routes (dispatched from api/agents/[id].js, sub === 'trade'):
// POST /api/agents/:id/trade execute a buy/sell
// POST /api/agents/:id/trade/quote preview: expected out, impact, fees, guards
// GET /api/agents/:id/trade/quote same preview via query params
// GET /api/agents/:id/trade/limits read the per-agent trade limits
// PUT /api/agents/:id/trade/limits update the per-agent trade limits (owner)
//
// SNIPER_MODE=simulate or { simulate: true } runs the full real-quote path but
// skips the broadcast (paper mode) — an ops/test toggle, never the default.
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { requireRealFundsAgreement } from '../_lib/real-funds-agreement.js';
import { sql } from '../_lib/db.js';
import { cors, json, method, error, readJson, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { ensureAgentWallet, recoverSolanaAgentKeypair } from '../_lib/agent-wallet.js';
import { getPumpTradeClient } from '../_lib/pump.js';
import { buildAmmSellInstructions, quoteAmmSell, buildAmmBuyInstructions, quoteAmmBuy } from '../../workers/agent-sniper/amm-exit.js';
import { logAudit } from '../_lib/audit.js';
import { explorerTxUrl } from '../_lib/avatar-wallet.js';
import { PublicKey, TransactionMessage, VersionedTransaction } from '@solana/web3.js';
import {
getAssociatedTokenAddressSync, getMint,
TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { randomUUID } from 'node:crypto';
import {
validateSolanaAddress, enforceSpendLimit, SpendLimitError, lamportsToUsd,
getTradeLimits, setTradeLimits, getDailySpendLamports,
updateCustodyEvent,
checkKillSwitch, checkConcurrency, checkPerTradeCap, checkDailyBudgetLamports,
checkSolHeadroom, checkPriceImpact, guardDueDiligence, tradeGuardResponse,
SOL_FEE_HEADROOM_LAMPORTS, TRADE_LIMIT_DEFAULTS,
} from '../_lib/agent-trade-guards.js';
import { createApprovalRequest, approvalPath, publicApproval } from '../_lib/approvals.js';
import { currentSignatureFor, agreementRequirement } from '../_lib/real-funds-agreement.js';
import { assessTradeSafety, recordFirewallDecision, firewallGuardResponse } from '../_lib/trade-firewall.js';
import { submitProtected } from '../_lib/execution-engine.js';
import { buildAgentTradeFee } from '../_lib/pump-platform-fee.js';
const WSOL_MINT = 'So11111111111111111111111111111111111111112';
const CONFIRM_TIMEOUT_MS = 45_000;
function normNetwork(n) {
return n === 'devnet' ? 'devnet' : 'mainnet';
}
// A bearer must hold wallet:trade (or wallet:write, which implies it) to trade; the read-only quote passes
// `spendCheck: false` because a preview moves nothing.
async function resolveAuth(req, { spendCheck = true } = {}) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, owner: true };
const bearer = await authenticateBearer(extractBearer(req));
if (!bearer) return null;
if (spendCheck) assertBearerMaySpend(bearer, req, { kind: 'trade' });
return { userId: bearer.userId, owner: false };
}
// Owner gate shared by every route here. On any failure it writes the response
// and returns { error: true }; on success returns the owner + agent row + meta.
async function loadOwnedAgent(req, res, id, authOpts) {
const auth = await resolveAuth(req, authOpts);
if (!auth) { error(res, 401, 'unauthorized', 'sign in required'); return { error: true }; }
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) { error(res, 404, 'not_found', 'agent not found'); return { error: true }; }
if (row.user_id !== auth.userId) { error(res, 403, 'forbidden', 'not your agent'); return { error: true }; }
return { auth, row, meta: { ...(row.meta || {}) } };
}
// Whole-token → base units, and SOL → lamports, without float drift on the
// integer part. amount is already validated finite + positive.
function toBaseUnits(amount, decimals) {
const [whole, frac = ''] = String(amount).split('.');
const fracPadded = (frac + '0'.repeat(decimals)).slice(0, decimals);
return BigInt(whole || '0') * 10n ** BigInt(decimals) + BigInt(fracPadded || '0');
}
function solToLamports(sol) {
return toBaseUnits(sol, 9);
}
function lamportsToSol(l) {
return Number(BigInt(l)) / 1e9;
}
// Resolve the agent's SPL holding for a mint: token program, decimals, ATA, and
// current base-unit balance. Throws a structured boundary error on any miss.
async function resolveHolding(conn, mintPk, ownerPk) {
let mintAcc;
try {
mintAcc = await conn.getAccountInfo(mintPk);
} catch {
mintAcc = null;
}
if (!mintAcc) throw boundary(400, 'invalid_mint', 'token mint not found on this network');
const tokenProgramId = mintAcc.owner.equals(TOKEN_2022_PROGRAM_ID) ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
let decimals;
try {
decimals = (await getMint(conn, mintPk, 'confirmed', tokenProgramId)).decimals;
} catch {
throw boundary(400, 'invalid_mint', 'could not read the token mint');
}
const ata = getAssociatedTokenAddressSync(mintPk, ownerPk, false, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID);
let balanceRaw = 0n;
try {
balanceRaw = BigInt((await conn.getTokenAccountBalance(ata)).value.amount);
} catch {
balanceRaw = 0n; // no ATA → holds none
}
return { tokenProgramId, decimals, ata, balanceRaw };
}
function boundary(status, code, message, detail = {}) {
return Object.assign(new Error(message), { status, code, detail, isBoundary: true });
}
function isGraduatedErr(err) {
return err?.name === 'CoinGraduatedError' || err?.code === 'CoinGraduated';
}
// Price a buy or sell against live state. Returns everything the guards and the
// builder need. Throws boundary() errors for bad input / unpriceable / RPC.
async function quoteTrade({ ctx, side, mintPk, amount, isMax, slippagePct, network, ownerPk }) {
const slippageBps = Math.round(slippagePct * 100);
if (side === 'buy') {
const lamports = solToLamports(amount);
if (lamports <= 0n) throw boundary(400, 'invalid_amount', 'amount rounds to zero lamports');
let q;
try {
q = await ctx.client.quoteForBuy({ mint: mintPk, quoteAmount: new ctx.BN(lamports.toString()), slippagePct });
} catch (err) {
if (isGraduatedErr(err)) {
// Graduated → route the buy through the canonical AMM pool (mirrors the
// graduated sell path below). Exact-SOL-in: expected tokens out, with the
// SOL ceiling enforced on-chain via maxQuote inside the builder.
const a = await quoteAmmBuy({ network, mint: mintPk.toBase58(), quoteAmount: new ctx.BN(lamports.toString()), slippagePct });
const expectedBase = a.expectedBaseOut;
if (expectedBase <= 0n) throw boundary(422, 'zero_out', 'this amount buys zero tokens — raise it');
return {
venue: 'amm',
lamports, baseAmount: null, decimals: null,
expectedOutRaw: expectedBase, minOutRaw: a.minBaseOut,
priceImpactPct: Number(a.priceImpactPct ?? 0),
usdValue: null, slippageBps,
};
}
console.error('[agents/agent-trade] buy quote failed', err?.message);
throw boundary(502, 'quote_failed', 'could not price the buy — try again');
}
requireSolQuote(ctx, q.quoteMint);
const expectedBase = BigInt(q.expectedBaseTokens.toString());
if (expectedBase <= 0n) throw boundary(422, 'zero_out', 'this amount buys zero tokens — raise it');
const minOut = (expectedBase * BigInt(10000 - slippageBps)) / 10000n;
return {
venue: 'bonding_curve',
lamports, baseAmount: null, decimals: null,
expectedOutRaw: expectedBase, minOutRaw: minOut,
priceImpactPct: Number(q.priceImpactPct ?? 0),
usdValue: null, slippageBps,
};
}
// sell
const conn = ctx.connection;
const { decimals, balanceRaw } = await resolveHolding(conn, mintPk, ownerPk);
if (balanceRaw <= 0n) throw boundary(400, 'insufficient_token_balance', 'the agent holds none of this token');
const baseAmount = isMax ? balanceRaw : toBaseUnits(amount, decimals);
if (baseAmount <= 0n) throw boundary(400, 'invalid_amount', 'amount rounds to zero token units');
if (baseAmount > balanceRaw) {
throw boundary(400, 'insufficient_token_balance', 'amount exceeds the agent token balance', {
balance_raw: balanceRaw.toString(), decimals,
});
}
const baseBn = new ctx.BN(baseAmount.toString());
let expectedSolOut;
let priceImpactPct;
let venue = 'bonding_curve';
try {
const q = await ctx.client.quoteForSell({ mint: mintPk, baseAmount: baseBn, slippagePct });
requireSolQuote(ctx, q.quoteMint);
expectedSolOut = BigInt(q.expectedQuoteOut.toString());
priceImpactPct = Number(q.priceImpactPct ?? 0);
} catch (err) {
if (!isGraduatedErr(err)) {
if (err?.isBoundary) throw err;
console.error('[agents/agent-trade] sell quote failed', err?.message);
throw boundary(502, 'quote_failed', 'could not price the sell — try again');
}
// Graduated: route the quote through the canonical AMM pool.
const a = await quoteAmmSell({ network, mint: mintPk.toBase58(), baseAmount: baseBn, slippagePct });
expectedSolOut = a.expectedQuoteOut;
priceImpactPct = Number(a.priceImpactPct ?? 0);
venue = 'amm';
}
const minOut = (expectedSolOut * BigInt(10000 - slippageBps)) / 10000n;
return {
venue,
lamports: null, baseAmount, decimals,
expectedOutRaw: expectedSolOut, minOutRaw: minOut,
priceImpactPct, usdValue: null, slippageBps,
};
}
function requireSolQuote(ctx, quoteMint) {
if (!quoteMint) return;
const isDefault = quoteMint.equals?.(ctx.web3.PublicKey.default);
const b58 = quoteMint.toBase58?.();
if (isDefault || b58 === WSOL_MINT) return;
throw boundary(422, 'quote_not_sol', 'this coin is not SOL-quoted — the agent wallet trades in SOL on this path');
}
// Build the on-chain instructions for a prepared trade.
async function buildTradeInstructions({ ctx, side, venue, mintPk, ownerPk, lamports, baseAmount, slippagePct, network }) {
if (side === 'buy') {
if (venue === 'amm') {
const built = await buildAmmBuyInstructions({ network, mint: mintPk.toBase58(), user: ownerPk, quoteAmount: new ctx.BN(lamports.toString()), slippagePct });
return { instructions: built.instructions, expectedOutRaw: built.expectedBaseOut };
}
const built = await ctx.client.buildBuyInstructions({
mint: mintPk, user: ownerPk, quoteAmount: new ctx.BN(lamports.toString()), slippagePct,
});
return { instructions: built.instructions, expectedOutRaw: BigInt(built.expectedBaseTokens.toString()) };
}
const baseBn = new ctx.BN(baseAmount.toString());
if (venue === 'amm') {
const built = await buildAmmSellInstructions({ network, mint: mintPk.toBase58(), user: ownerPk, baseAmount: baseBn, slippagePct });
return { instructions: built.instructions, expectedOutRaw: built.expectedQuoteOut };
}
const built = await ctx.client.buildSellInstructions({ mint: mintPk, user: ownerPk, baseAmount: baseBn, slippagePct });
return { instructions: built.instructions, expectedOutRaw: BigInt(built.expectedQuoteOut.toString()) };
}
// Run every guard for a prepared trade. Returns null if clear, or a 4xx response
// shape. Buys are gated on the lamport caps + USD ceiling + balance; sells only
// move SOL inward, so they skip the spend caps but still honor the kill switch,
// the price-impact breaker, and a fee-headroom floor.
async function runGuards({ id, side, tradeLimits, prep, walletLamports, network, meta, mintPk, ownerPk, userId, feeLamports = 0n, burnerExempt = false, stepUpApproved = false }) {
const killed = checkKillSwitch(tradeLimits.kill_switch);
if (killed) return tradeGuardResponse(killed);
const impact = checkPriceImpact(prep.priceImpactPct, tradeLimits.max_price_impact_pct);
if (impact) return tradeGuardResponse(impact);
if (side === 'buy') {
if (mintPk && network === 'mainnet') {
const dd = await guardDueDiligence(mintPk.toBase58(), tradeLimits);
if (dd) return tradeGuardResponse(dd);
}
const lamports = prep.lamports;
const capLamports = tradeLimits.per_trade_sol == null ? null : solToLamports(tradeLimits.per_trade_sol);
const cap = checkPerTradeCap(lamports, capLamports);
if (cap) return tradeGuardResponse(cap);
if (tradeLimits.max_concurrent != null) {
const open = await countOpenTrades(id, network);
const conc = checkConcurrency(open, tradeLimits.max_concurrent);
if (conc) return tradeGuardResponse(conc);
}
const budgetLamports = tradeLimits.daily_budget_sol == null ? null : solToLamports(tradeLimits.daily_budget_sol);
if (budgetLamports != null) {
const spent = await getDailySpendLamports(id, network);
const budget = checkDailyBudgetLamports(spent, lamports, budgetLamports);
if (budget) return tradeGuardResponse(budget);
}
// Cross-path USD ceiling (shared with withdraw / x402 / snipe).
try {
await enforceSpendLimit({ agentId: id, meta, category: 'trade', usdValue: prep.usdValue, network, burnerExempt, stepUpApproved });
} catch (e) {
if (e instanceof SpendLimitError) return { status: e.status, code: e.code, message: e.message, detail: e.detail };
throw e;
}
const headroom = checkSolHeadroom(walletLamports, BigInt(lamports) + BigInt(feeLamports), SOL_FEE_HEADROOM_LAMPORTS);
if (headroom) return tradeGuardResponse(headroom);
// Rug/honeypot firewall — a REAL on-chain simulated buy→sell round-trip +
// authority audit. A 'block' verdict refuses the buy (server-signed funds
// never move on a coin you can't sell). Never throws; degrades to 'warn'.
if (mintPk) {
const assessment = await assessTradeSafety({
network, mint: mintPk, side: 'buy', payer: ownerPk,
quoteAmount: lamports, priceImpactPct: prep.priceImpactPct,
}).catch(() => null);
if (assessment) {
recordFirewallDecision({
mint: mintPk.toBase58?.() || String(mintPk), network, side: 'buy',
verdict: assessment.verdict, score: assessment.score, simulated: assessment.simulated,
checks: assessment.checks, reasons: assessment.reasons,
source: 'discretionary', agentId: id, userId: userId ?? null,
quoteLamports: lamports, enforced: assessment.verdict === 'block',
}).catch(() => {});
if (assessment.verdict === 'block') return firewallGuardResponse(assessment);
}
}
} else {
// Sell: only needs enough SOL on hand to pay the network fee (and maybe
// open a wSOL/quote ATA). Reuse the same headroom floor with zero spend.
const headroom = checkSolHeadroom(walletLamports, 0n, SOL_FEE_HEADROOM_LAMPORTS);
if (headroom) {
return tradeGuardResponse({
reason: 'insufficient_sol',
detail: { wallet_lamports: BigInt(walletLamports).toString(), required_lamports: SOL_FEE_HEADROOM_LAMPORTS.toString() },
});
}
}
return null;
}
// Count the agent's open discretionary trades in the trailing window — buys that
// haven't been closed by a matching sell. A lightweight concurrency signal drawn
// from the unified custody ledger (only enforced when max_concurrent is set).
async function countOpenTrades(agentId, network) {
const [r] = await sql`
SELECT count(*)::int AS n FROM agent_custody_events
WHERE agent_id = ${agentId} AND network = ${network}
AND event_type = 'spend' AND category = 'trade'
AND status IN ('pending', 'confirmed', 'ok')
AND (meta->>'side') = 'buy'
AND created_at > now() - interval '24 hours'
`;
return r?.n ?? 0;
}
// Parse + validate the trade request body into a normalized shape, or throw a
// boundary() error. Shared by execute + preview + the strategy runtime (which
// builds a synthetic body { side, mint, amount, slippageBps, network }).
export function parseTradeInput(body, tradeLimits) {
const side = body.side === 'sell' ? 'sell' : body.side === 'buy' ? 'buy' : null;
if (!side) throw boundary(400, 'invalid_side', 'side must be "buy" or "sell"');
const mintCheck = validateSolanaAddress(body.mint);
if (!mintCheck.valid) throw boundary(400, 'invalid_mint', `mint is not a valid Solana address (${mintCheck.reason})`);
const denom = side === 'buy' ? 'sol' : 'token';
const isMax = side === 'sell' && (body.amount === 'max' || body.amount === 'MAX' || body.amount === 'all');
let amount = null;
if (!isMax) {
amount = Number(body.amount);
if (!Number.isFinite(amount) || amount <= 0) {
throw boundary(400, 'invalid_amount', side === 'buy' ? 'amount (SOL to spend) must be a positive number' : 'amount (tokens to sell) must be a positive number or "max"');
}
}
const requestedBps = Number.isFinite(Number(body.slippageBps)) ? Math.round(Number(body.slippageBps)) : tradeLimits.max_slippage_bps;
const slippageBps = Math.max(0, Math.min(tradeLimits.max_slippage_bps, requestedBps));
return {
side, denom, isMax, amount,
mintPk: mintCheck.pubkey,
mint: mintCheck.base58,
slippageBps,
slippagePct: slippageBps / 100,
network: normNetwork(body.network),
simulate: body.simulate === true || process.env.SNIPER_MODE === 'simulate',
idempotencyKey: typeof body.idempotency_key === 'string' && body.idempotency_key.trim()
? body.idempotency_key.trim().slice(0, 128)
: null,
};
}
// ── execute ─────────────────────────────────────────────────────────────────
async function handleExecute(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const owned = await loadOwnedAgent(req, res, id);
if (owned.error) return;
const { auth, meta } = owned;
const rlUser = await limits.tradePerUser(auth.userId);
if (!rlUser.success) return rateLimited(res, rlUser);
const rlIp = await limits.authIp(clientIp(req));
if (!rlIp.success) return rateLimited(res, rlIp);
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const tradeLimits = getTradeLimits(meta);
let input;
try {
input = parseTradeInput(body, tradeLimits);
} catch (e) {
return boundaryError(res, e);
}
// CSRF on the real, fund-moving path only — `simulate` is a dry run that never
// signs or records. Bearer/API-key callers (the primary consumers of this flat
// trade endpoint) are exempt inside requireCsrf.
if (!input.simulate && !(await requireRealFundsAgreement(req, res, { userId: auth.userId, network: input.network, context: 'trade' }))) return;
if (!input.simulate && !(await requireCsrf(req, res, auth.userId))) return;
let result;
try {
result = await executeAgentTrade({ id, userId: auth.userId, meta, input, req, source: 'discretionary', burnerExempt: auth.owner === true });
} catch (e) {
console.error('[agents/agent-trade] execute crashed', e?.message);
return error(res, 500, 'internal_error', 'unexpected error executing the trade');
}
if (!result.ok) {
return error(res, result.status || 500, result.code || 'error', result.message || 'trade failed', result.detail ? { detail: result.detail } : {});
}
return json(res, result.status || 200, { data: result.data });
}
/**
* Programmatic trade execution core — the shared engine behind BOTH the HTTP
* trade endpoint and the autonomous strategy runtime (task 10). The caller has
* already loaded the owned agent (`meta`), parsed + bounded the request into
* `input`, and — for the HTTP path — verified CSRF. This runs the SAME
* quote → guard → build → custody-claim → sign → confirm pipeline for every
* caller, so an autonomous strategy is held to the exact same spend policy,
* rug/honeypot firewall, daily budget, kill switch, and custody audit trail as a
* manual trade. A strategy can NEVER exceed the spend leash — the guards below do
* not know or care who called them.
*
* `source` labels the custody ledger: 'discretionary' for the HTTP endpoint, or
* 'strategy:<slug>' for a strategy-initiated trade (with `sourceMeta` carrying
* { strategy, strategy_id, equip_id } stamped into the ledger row's meta).
*
* @returns {Promise<{ ok:true, status:number, data:object }
* | { ok:false, status:number, code:string, message:string, detail?:object }>}
*/
export async function executeAgentTrade({ id, userId, meta, input, req = null, source = 'discretionary', sourceMeta = null, burnerExempt = false, approvalId = null }) {
const { side, network, simulate, slippagePct } = input;
const idempotencyKey = input.idempotencyKey || randomUUID();
const tradeLimits = getTradeLimits(meta);
const isStrategy = typeof source === 'string' && source.startsWith('strategy:');
const custodyReason = isStrategy ? source.slice(0, 80) : `trade_${side}`;
const fail = (status, code, message, detail = null) => ({ ok: false, status, code, message, detail });
// Guarantee the wallet exists (lazy provision) so a funded-but-unprovisioned
// agent can trade. ensureAgentWallet audits the provision and never returns
// the secret.
let address;
try {
address = (await ensureAgentWallet(id, userId, { reason: custodyReason })).address;
} catch (e) {
console.error('[agents/agent-trade] wallet prepare failed', e?.message);
return fail(500, 'wallet_unavailable', 'could not prepare the agent wallet — try again');
}
const ownerPk = new PublicKey(address);
// Fast-path idempotency: a retry of a finished/in-flight trade with the same key.
{
const [existing] = await sql`
SELECT id, status, signature, meta FROM agent_custody_events
WHERE agent_id = ${id} AND idempotency_key = ${idempotencyKey}
`;
if (existing) {
if (existing.status === 'confirmed') {
return { ok: true, status: 200, data: { replayed: true, signature: existing.signature, explorer: explorerTxUrl(existing.signature, network), network, ...(existing.meta || {}) } };
}
if (existing.status === 'pending') {
return fail(409, 'trade_in_progress', 'a trade with this id is already in flight — check the audit log before retrying', { signature: existing.signature || null });
}
return fail(409, 'trade_failed', 'this trade id already failed — retry with a fresh idempotency key', { signature: existing.signature || null });
}
}
let ctx;
try {
ctx = await getPumpTradeClient({ network });
} catch (e) {
console.error('[agents/agent-trade] trade RPC unavailable', e?.message);
return fail(502, 'rpc_error', 'could not connect to the trade RPC — try again');
}
const conn = ctx.connection;
let walletLamports;
try {
walletLamports = BigInt(await conn.getBalance(ownerPk, 'confirmed'));
} catch {
return fail(502, 'rpc_error', 'could not read the wallet balance — try again');
}
// Price the trade.
let prep;
try {
prep = await quoteTrade({ ctx, side, mintPk: input.mintPk, amount: input.amount, isMax: input.isMax, slippagePct, network, ownerPk });
} catch (e) {
if (e?.isBoundary) return fail(e.status, e.code, e.message, e.detail && Object.keys(e.detail).length ? e.detail : null);
return fail(500, 'internal_error', 'unexpected error preparing the trade');
}
if (side === 'buy' && prep.lamports != null) {
try { prep.usdValue = await lamportsToUsd(prep.lamports); } catch { prep.usdValue = null; }
}
// The three.ws trade fee rides in the trade transaction: on the SOL spent for a
// buy, on the guaranteed minimum SOL out for a sell. Priced before the guards
// so the SOL headroom check covers it. Platform-owned agents pay nothing.
let tradeFee;
try {
tradeFee = await buildAgentTradeFee({ network, payer: ownerPk, userId, side, lamports: side === 'buy' ? prep.lamports : prep.minOutRaw });
} catch (e) {
console.error('[agents/agent-trade] fee build failed', e?.message);
return fail(502, 'fee_build_failed', 'could not price the trade fee, try again');
}
const feeLamports = tradeFee ? BigInt(tradeFee.disclosure.amount) : 0n;
// Run the shared guardrails — identical for manual + strategy trades.
let blocked;
try {
blocked = await runGuards({
id, side, tradeLimits, prep, walletLamports, network, meta, mintPk: input.mintPk, ownerPk, userId, feeLamports,
burnerExempt,
// A dry run moves nothing, and an approved trade is the owner's own answer.
stepUpApproved: simulate || Boolean(approvalId),
});
} catch (e) {
console.error('[agents/agent-trade] guard check failed', e?.message);
return fail(502, 'guard_check_failed', 'could not verify the trade guardrails — try again');
}
// Above the agent's burner cap a buy is not refused: it waits in the owner's inbox.
if (blocked?.code === 'policy_step_up' && blocked.detail?.burner) {
return parkTradeForApproval({ id, userId, input, prep, network, blocked, idempotencyKey });
}
if (blocked) return fail(blocked.status, blocked.code, blocked.message, blocked.detail);
// Build the on-chain instructions (also the real graduation check for buys).
let built;
try {
built = await buildTradeInstructions({ ctx, side, venue: prep.venue, mintPk: input.mintPk, ownerPk, lamports: prep.lamports, baseAmount: prep.baseAmount, slippagePct, network });
} catch (e) {
if (isGraduatedErr(e)) {
return fail(409, 'graduated', 'This coin graduated mid-trade — refresh the quote and retry.');
}
console.error('[agents/agent-trade] build failed', e?.message);
return fail(502, 'build_failed', 'could not build the trade — try again');
}
if (tradeFee) built.instructions = [...built.instructions, ...tradeFee.instructions];
const ledgerMeta = {
side, mint: input.mint, venue: prep.venue, slippage_bps: input.slippageBps,
price_impact_pct: prep.priceImpactPct,
expected_out: prep.expectedOutRaw.toString(),
min_out: prep.minOutRaw.toString(),
...(side === 'sell' ? { base_amount: prep.baseAmount.toString(), token_decimals: prep.decimals } : {}),
...(tradeFee ? { platform_fee: tradeFee.disclosure } : {}),
...(approvalId ? { approval_id: approvalId } : {}),
...(isStrategy ? { source: 'strategy', strategy: sourceMeta?.strategy ?? null, strategy_id: sourceMeta?.strategy_id ?? null, equip_id: sourceMeta?.equip_id ?? null } : {}),
};
// Paper mode: simulate the real instructions, never sign, never record.
if (simulate) {
const message = new TransactionMessage({ payerKey: ownerPk, recentBlockhash: (await safeBlockhash(conn))?.blockhash || '11111111111111111111111111111111', instructions: built.instructions }).compileToV0Message();
const vtx = new VersionedTransaction(message);
let sim = null;
try {
sim = await conn.simulateTransaction(vtx, { sigVerify: false, replaceRecentBlockhash: true });
} catch (e) {
console.error('[agents/agent-trade] simulation failed', e?.message);
return fail(502, 'simulation_failed', e?.message || 'simulation failed');
}
return {
ok: true,
status: 200,
data: {
simulated: true, side, mint: input.mint, network, venue: prep.venue,
expected_out: prep.expectedOutRaw.toString(),
min_out: prep.minOutRaw.toString(),
price_impact_pct: prep.priceImpactPct,
err: sim.value?.err ?? null,
units_consumed: sim.value?.unitsConsumed ?? null,
},
};
}
// Claim the idempotency slot — this row is also the ledger/audit entry. Buys
// count toward the SOL + USD budgets (amount_lamports + usd set); sells move
// SOL inward, so they record for audit with null amounts (don't consume budget).
// `reason` is the human-facing custody-trail label: 'strategy:<slug>' for a
// strategy fill, 'trade_buy'/'trade_sell' for a manual one. Budget queries key
// on event_type/amount/usd (never reason), so relabeling is safe.
const claim = await sql`
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset,
amount_lamports, amount_raw, usd, status, idempotency_key, reason, meta)
VALUES (
${id}, ${userId}, 'spend', 'trade', ${network},
${side === 'buy' ? 'SOL' : input.mint},
${side === 'buy' ? String(prep.lamports) : null},
${side === 'sell' ? String(prep.baseAmount) : null},
${side === 'buy' ? (prep.usdValue ?? null) : null},
'pending', ${idempotencyKey}, ${custodyReason},
${JSON.stringify(ledgerMeta)}::jsonb
)
ON CONFLICT (agent_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
RETURNING id
`;
if (!claim.length) {
return fail(409, 'trade_in_progress', 'a trade with this id is already in flight — check the audit log before retrying');
}
const claimId = claim[0].id;
// Recover the custodial key (audit-logged) and sign.
let keypair;
try {
keypair = await recoverSolanaAgentKeypair(meta.encrypted_solana_secret, {
agentId: id, userId, reason: custodyReason,
meta: { mint: input.mint, network, venue: prep.venue, custody_event_id: claimId, ...(isStrategy ? { strategy_id: sourceMeta?.strategy_id ?? null, equip_id: sourceMeta?.equip_id ?? null } : {}) },
});
} catch (e) {
console.error('[agents/agent-trade] key recover failed', e?.message);
await updateCustodyEvent(claimId, { status: 'failed', meta: { error: 'key_recover_failed' } }).catch(() => {});
return fail(500, 'key_recover_failed', 'could not access the agent wallet key — no funds were moved');
}
// Submit + confirm through the protected execution engine.
let result;
try {
result = await signSendConfirm(conn, keypair, built.instructions, network);
} catch (e) {
await updateCustodyEvent(claimId, { status: 'failed', meta: { error: e?.code || 'send_failed', message: e?.message?.slice(0, 200) } }).catch(() => {});
logAudit({ userId, action: isStrategy ? 'custody.trade_strategy_failed' : 'custody.trade_failed', resourceId: id, meta: { side, mint: input.mint, reason: e?.code || 'send_failed', network, source }, req });
return fail(502, 'send_failed', 'the trade could not be submitted and no funds were moved — try again');
}
if (!result.confirmed) {
await updateCustodyEvent(claimId, { signature: result.signature, meta: { confirm: 'unconfirmed' } }).catch(() => {});
logAudit({ userId, action: 'custody.trade_unconfirmed', resourceId: id, meta: { side, mint: input.mint, signature: result.signature, network, source }, req });
return fail(202, 'trade_unconfirmed', 'the trade was submitted but not yet confirmed — check the explorer link before retrying', { signature: result.signature, explorer: explorerTxUrl(result.signature, network) });
}
await updateCustodyEvent(claimId, { status: 'confirmed', signature: result.signature, meta: result.exec ? { exec: result.exec } : undefined }).catch(() => {});
logAudit({ userId, action: isStrategy ? 'custody.trade_strategy' : 'custody.trade', resourceId: id, meta: { side, mint: input.mint, venue: prep.venue, network, signature: result.signature, usd: prep.usdValue, exec_route: result.exec?.route, source }, req });
// Re-read the SOL balance for the response.
let newSol = null;
try { newSol = (await conn.getBalance(ownerPk, 'confirmed')) / 1e9; } catch { /* best-effort */ }
return {
ok: true,
status: 200,
data: {
replayed: false,
custody_event_id: claimId,
signature: result.signature,
explorer: explorerTxUrl(result.signature, network),
side, mint: input.mint, network, venue: prep.venue,
slippage_bps: input.slippageBps,
price_impact_pct: prep.priceImpactPct,
...(side === 'buy'
? { sol_spent: lamportsToSol(prep.lamports), tokens_received: prep.expectedOutRaw.toString(), expected_out_raw: prep.expectedOutRaw.toString() }
: { tokens_sold: prep.baseAmount.toString(), sol_received: lamportsToSol(prep.expectedOutRaw), expected_out_raw: prep.expectedOutRaw.toString() }),
min_out: prep.minOutRaw.toString(),
new_balance_sol: newSol,
execution: result.exec || null,
},
};
}
async function safeBlockhash(conn) {
try { return await conn.getLatestBlockhash('confirmed'); } catch { return null; }
}
/**
* Live SOL value (lamports) of selling `baseAmountRaw` base units of `mint` right
* now — a zero-slippage quote used by the strategy runtime to mark open positions
* to market for take-profit / stop-loss / trailing-stop decisions. Reuses the
* exact bonding-curve + AMM quote path the real sell uses, so the valuation and
* the eventual fill are priced the same way. Returns null if it can't be priced
* (caller treats that as "skip this position this sweep", never as a loss).
*/
export async function quoteSellValueLamports({ network, mint, baseAmountRaw }) {
const base = BigInt(baseAmountRaw || 0n);
if (base <= 0n) return null;
const net = normNetwork(network);
let ctx;
try { ctx = await getPumpTradeClient({ network: net }); } catch { return null; }
const mintPk = new PublicKey(mint);
const baseBn = new ctx.BN(base.toString());
try {
const q = await ctx.client.quoteForSell({ mint: mintPk, baseAmount: baseBn, slippagePct: 0 });
return BigInt(q.expectedQuoteOut.toString());
} catch (err) {
if (!isGraduatedErr(err)) return null;
try {
const a = await quoteAmmSell({ network: net, mint, baseAmount: baseBn, slippagePct: 0 });
return BigInt(a.expectedQuoteOut);
} catch {
return null;
}
}
}
// Broadcast + confirm through the MEV-aware execution engine: dynamic compute
// budget (real simulate + real priority-fee estimate) and bounded adaptive retry
// with an ambiguous-confirm re-check so a landed tx is never marked failed. The
// discretionary path has no per-strategy tip policy, so it uses the protected
// single-tx route (tipMode 'off' — no Jito tip) while still getting the data-driven
// fee + retry. Returns the execution telemetry for the response.
async function signSendConfirm(conn, payer, instructions, network) {
let result;
try {
result = await submitProtected({
network, connection: conn, payer, instructions,
opts: { tipMode: 'off', confirmTimeoutMs: CONFIRM_TIMEOUT_MS },
});
} catch (e) {
if (e?.code === 'TX_ERR') {
// Landed but reverted on-chain — surfaced as confirmed:false so the caller
// records the (failed) signature rather than retrying.
return { signature: e.signature || null, confirmed: false, exec: null };
}
throw Object.assign(new Error(e?.message || 'send failed'), { code: 'send_failed' });
}
return {
signature: result.signature,
confirmed: true,
exec: { route: result.route, priority_fee_microlamports: result.priorityFeeMicroLamports, landed_ms: result.landedMs, attempts: result.attempts },
};
}
// ── preview / quote ───────────────────────────────────────────────────────────
async function handleQuote(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const owned = await loadOwnedAgent(req, res, id, { spendCheck: false });
if (owned.error) return;
const { auth, meta } = owned;
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
let body = {};
if (req.method === 'POST') {
try { body = await readJson(req); } catch (e) { return error(res, 400, 'bad_request', e?.message || 'invalid request body'); }
} else {
const url = new URL(req.url, 'http://x');
body = {
side: url.searchParams.get('side'),
mint: url.searchParams.get('mint'),
amount: url.searchParams.get('amount'),
slippageBps: url.searchParams.get('slippageBps'),
network: url.searchParams.get('network'),
};
}
const tradeLimits = getTradeLimits(meta);
let input;
try {
input = parseTradeInput(body, tradeLimits);
} catch (e) {
return boundaryError(res, e);
}
try {
return json(res, 200, { data: await previewAgentTrade({ id, userId: auth.userId, meta, input, burnerExempt: auth.owner === true }) });
} catch (e) {
return boundaryError(res, e);
}
}
/**
* Read-only preview of a custodial trade: the same quote, platform fee and
* guard chain executeAgentTrade runs, with nothing signed or recorded. Shared by
* the HTTP quote route and the MCP trading tools, so a preview a model shows the
* owner is computed exactly the way the execute path will judge it.
*
* Throws a boundary error ({ status, code, message, detail }) on bad input or an
* unreachable RPC. A guard refusal is not thrown: it comes back as
* `allowed: false` with `blocked_reason`, so the preview can always be shown.
*/
export async function previewAgentTrade({ id, userId, meta, input, burnerExempt = false }) {
const { side, network, slippagePct } = input;
const tradeLimits = getTradeLimits(meta);
const address = meta.solana_address || null;
if (!address) throw boundary(404, 'no_wallet', 'agent has no solana wallet yet: fund it to start trading');
const ownerPk = new PublicKey(address);
let ctx;
try { ctx = await getPumpTradeClient({ network }); } catch { throw boundary(502, 'rpc_error', 'could not connect to the trade RPC, try again'); }
const conn = ctx.connection;
let walletLamports = 0n;
try { walletLamports = BigInt(await conn.getBalance(ownerPk, 'confirmed')); } catch { /* preview tolerates */ }
const prep = await quoteTrade({ ctx, side, mintPk: input.mintPk, amount: input.amount, isMax: input.isMax, slippagePct, network, ownerPk });
if (side === 'buy' && prep.lamports != null) {
try { prep.usdValue = await lamportsToUsd(prep.lamports); } catch { prep.usdValue = null; }
}
let tradeFee = null;
try { tradeFee = await buildAgentTradeFee({ network, payer: ownerPk, userId, side, lamports: side === 'buy' ? prep.lamports : prep.minOutRaw }); } catch { tradeFee = null; }
const feeLamports = tradeFee ? BigInt(tradeFee.disclosure.amount) : 0n;
let blocked = null;
try { blocked = await runGuards({ id, side, tradeLimits, prep, walletLamports, network, meta, mintPk: input.mintPk, ownerPk, userId, feeLamports, burnerExempt }); } catch { blocked = null; }
return {
side, mint: input.mint, network, venue: prep.venue,
slippage_bps: input.slippageBps,
price_impact_pct: prep.priceImpactPct,
...(side === 'buy'
? { sol_in: lamportsToSol(prep.lamports), expected_tokens_out: prep.expectedOutRaw.toString() }
: { tokens_in: prep.baseAmount.toString(), token_decimals: prep.decimals, expected_sol_out: lamportsToSol(prep.expectedOutRaw) }),
min_out: prep.minOutRaw.toString(),
usd_value: prep.usdValue ?? null,
platform_fee: tradeFee ? tradeFee.disclosure : null,
wallet_address: address,
wallet_balance_sol: Number(walletLamports) / 1e9,
allowed: !blocked,
blocked_reason: blocked ? { code: blocked.code, message: blocked.message, detail: blocked.detail } : null,
};
}
// ── burner cap: park a trade for the owner, run it once they answer ─────────
function shortMint(mint) {
return `${mint.slice(0, 4)}...${mint.slice(-4)}`;
}
async function parkTradeForApproval({ id, userId, input, prep, network, blocked, idempotencyKey }) {
const sol = lamportsToSol(prep.lamports);
const usd = prep.usdValue ?? null;
const payload = {
kind: 'agent_trade',
side: input.side,
mint: input.mint,
sol_amount: sol,
slippage_bps: input.slippageBps,
network,
};
const [agent] = await sql`SELECT name FROM agent_identities WHERE id = ${id}`;
let created;
try {
created = await createApprovalRequest({
userId,
agentId: id,
source: 'agent_trade',
sourceRef: `trade:${id}:${network}:${input.side}:${input.mint}:${sol}`,
actionType: 'trade_buy',
venue: 'agent_trade',
payload,
summary: `${agent?.name || 'Your agent'} wants to buy ${sol} SOL of ${shortMint(input.mint)}`,
amount: sol,
amountUsd: usd,
asset: 'SOL',
chain: 'solana',
network,
recipient: input.mint,
recipientLabel: 'Token',
riskNotes: [blocked.detail.reason, 'Memecoin trades can lose their full value. The price you approve is not locked: the trade runs at the market price when you confirm.'],
gateReason: blocked.message,
idempotencyKey: `burner-trade:${id}:${idempotencyKey}`,
autoApprovable: false,
burnerGated: true,
});
} catch (e) {
console.error('[agents/agent-trade] could not queue the approval', e?.message);
return { ok: false, status: 502, code: 'approval_unavailable', message: 'This trade is above the agent\'s burner cap and needs your approval, but the request could not be queued. Nothing was sent. Try again.', detail: null };
}
const view = publicApproval(created.request);
return {
ok: true,
status: 202,
data: {
pending_approval: true,
approval_id: created.request.id,
tier: blocked.detail.tier,
requires_wallet_signature: view.requires_wallet_signature,
expires_at: created.request.expires_at,
summary: created.request.summary,
confirmation: view.confirmation,
reason: blocked.detail.reason,
link: approvalPath(created.request),
side: input.side, mint: input.mint, network,
},
};
}
/**
* Approval inbox executor for a parked trade. Re-enters the normal trade engine
* with the approval id, which lifts only the burner step-up: the kill switch,
* per-trade cap, daily budget, spend policy, firewall and ledger all still run.
*/
export async function executeApprovedAgentTrade(row) {
const p = row.payload || {};
const [agent] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${row.agent_id} AND deleted_at IS NULL`;
if (!agent) return { status: 'error', note: 'That agent no longer exists, so nothing was sent.' };
if (agent.user_id !== row.user_id) return { status: 'error', note: 'That agent is no longer owned by this account, so nothing was sent.' };
if (p.network !== 'devnet') {
let signed;
try { signed = await currentSignatureFor(agent.user_id); } catch {
return { status: 'error', note: 'Could not verify your signed real-funds agreements, so nothing was sent. Approve again in a moment.' };
}
if (!signed) return { status: 'error', note: `Sign the real-funds agreements before trading real funds. Nothing was sent. Sign here: ${agreementRequirement().sign_url}` };
}
let input;
try {
input = parseTradeInput({ side: p.side, mint: p.mint, amount: p.sol_amount, slippageBps: p.slippage_bps, network: p.network, idempotency_key: `approval:${row.id}` }, getTradeLimits(agent.meta));
} catch (e) {
return { status: 'error', note: e?.message || 'That trade is not valid any more, so nothing was sent.' };
}
const r = await executeAgentTrade({ id: agent.id, userId: agent.user_id, meta: agent.meta || {}, input, source: 'discretionary', burnerExempt: true, approvalId: row.id });
if (!r.ok) return { status: 'error', note: r.message, data: r.detail || undefined };
return { status: 'ok', signature: r.data.signature, usd: r.data.usd_value ?? null, data: r.data };
}
// ── limits (read / update) ──────────────────────────────────────────────────
async function handleLimits(req, res, id) {
if (cors(req, res, { methods: 'GET,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT'])) return;
const owned = await loadOwnedAgent(req, res, id);
if (owned.error) return;
const { auth, meta } = owned;
if (req.method === 'GET') {
// Surface the live daily spend alongside the limits so the owner can see how
// much of the daily budget the agent has already burned (mainnet — the
// budget guard keys on the same window/network). Best-effort: a spend-query
// hiccup must never block reading the limits themselves.
const network = normNetwork(new URL(req.url, 'http://x').searchParams.get('network'));
let spentLamports = 0n;
try { spentLamports = await getDailySpendLamports(id, network); } catch { spentLamports = 0n; }
let spentUsd = null;
if (spentLamports > 0n) { try { spentUsd = await lamportsToUsd(spentLamports); } catch { spentUsd = null; } }
return json(res, 200, {
data: {
limits: getTradeLimits(meta),
defaults: TRADE_LIMIT_DEFAULTS,
spent_today_sol: Number(spentLamports) / 1e9,
spent_today_usd: spentUsd,
network,
},
});
}
// Relaxing the trade guard rails (per-trade cap, daily budget, kill-switch)
// is a state-changing owner action — match the same CSRF gate the withdraw
// and spend-limit writes use. Bearer (machine) callers are exempt inside
// requireCsrf, like every other write path.
if (!(await requireCsrf(req, res, auth.userId))) return;
const rl = await limits.tradePerUser(auth.userId);
if (!rl.success) return rateLimited(res, rl);
let body;
try { body = await readJson(req); } catch (e) { return error(res, 400, 'bad_request', e?.message || 'invalid request body'); }
const invalid = validateLimitsPatch(body);
if (invalid) return error(res, 400, 'validation_error', invalid);
try {
const next = await setTradeLimits(id, auth.userId, body, { req });
return json(res, 200, { data: { limits: next } });
} catch (e) {
if (e?.status) return error(res, e.status, e.code || 'error', e.message);
return error(res, 500, 'limit_update_failed', 'could not update the trade limits — try again');
}
}
// Reject a bad limits patch instead of letting it through. normalizeTradeLimits
// coerces anything it cannot read into "no cap" / the default, so an unvalidated
// `{"per_trade_sol": -1}` (or a typo, or a string) SILENTLY DELETES the owner's
// existing per-trade ceiling and answers 200 as if it had tightened it. A spend
// guardrail must never be relaxed by an input the server could not parse: the
// only way to clear a cap is to send it as an explicit null.
const LIMIT_RANGES = {
per_trade_sol: { min: 0, max: 1e6, label: 'per_trade_sol must be a positive number of SOL, or null to clear the cap' },
daily_budget_sol: { min: 0, max: 1e6, label: 'daily_budget_sol must be a positive number of SOL, or null to clear the budget' },
max_price_impact_pct: { min: 0, max: 100, label: 'max_price_impact_pct must be a number between 0 and 100' },
max_slippage_bps: { min: 0, max: 10000, label: 'max_slippage_bps must be a number between 0 and 10000' },
max_concurrent: { min: 1, max: 10000, label: 'max_concurrent must be a whole number of at least 1, or null for no ceiling' },
max_insider_pct: { min: 0, max: 100, label: 'max_insider_pct must be a number between 0 and 100, or null to clear the limit' },
max_sniper_pct: { min: 0, max: 100, label: 'max_sniper_pct must be a number between 0 and 100, or null to clear the limit' },
max_bundler_pct: { min: 0, max: 100, label: 'max_bundler_pct must be a number between 0 and 100, or null to clear the limit' },
max_fresh_wallet_pct: { min: 0, max: 100, label: 'max_fresh_wallet_pct must be a number between 0 and 100, or null to clear the limit' },
};
function validateLimitsPatch(patch) {
if (!patch || typeof patch !== 'object' || Array.isArray(patch)) return 'body must be a JSON object of limit fields';
for (const [key, range] of Object.entries(LIMIT_RANGES)) {
if (!(key in patch)) continue;
const v = patch[key];
if (v === null) continue; // explicit clear
const n = typeof v === 'number' ? v : typeof v === 'string' && v.trim() !== '' ? Number(v) : NaN;
if (!Number.isFinite(n) || n < range.min || n > range.max) return range.label;
}
if ('kill_switch' in patch && typeof patch.kill_switch !== 'boolean') {
return 'kill_switch must be true or false';
}
return null;
}
function boundaryError(res, e) {
if (e?.isBoundary) return error(res, e.status, e.code, e.message, e.detail && Object.keys(e.detail).length ? { detail: e.detail } : {});
return error(res, 500, 'internal_error', 'unexpected error preparing the trade');
}
export default async function handler(req, res, id, action) {
if (action === 'limits') return handleLimits(req, res, id);
if (action === 'quote') return handleQuote(req, res, id);
if (action) return error(res, 404, 'not_found', 'unknown trade sub-resource');
return handleExecute(req, res, id);
}