Skip to content

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.

77.0 KB
Raw Blame
// Perps service: the one path every perps action takes, from the v1 routes, the
// MCP tools and the /agents/:id/perps page alike.
//
// Two modes, chosen per agent by its owner (api/_lib/perps/limits.js):
//
//   paper  the default. Orders are priced by the venue's own quote against the
//          live order book and marks, then filled on the platform's paper ledger
//          (./paper.js). Nothing is built, signed or sent.
//   live   only after the owner turns it on for that agent. Instructions come
//          from the venue module, are simulated against current chain state with
//          the agent's USDC and SOL outflow bounded, signed by the agent's
//          custodial wallet, sent, and confirmed.
//
// Every action that changes anything runs in two calls. The preview prices it,
// runs every guard and stores exactly what it showed (api/_lib/action-previews.js);
// the execute must present that preview's id, an explicit confirm_trade: true
// and an Idempotency-Key. Before an order executes it is re-quoted, and it is
// refused if the entry or liquidation price moved past the owner's tolerance.
// Executes are idempotent per agent and key (perps_executions): a replay returns
// the first result instead of trading twice.
//
// Guards, in the order they apply: the perps mode (live must be enabled), the
// perps kill switch (`halted`), the agent-wide trade kill switch, the wallet
// freeze, the per-agent leverage cap, the per-position margin cap, free
// collateral, slippage, and on deposits the wallet-wide spend policy (per
// transaction and daily USD caps, natural-language rules, anomaly guard). Only
// risk-increasing orders are blocked by the kill switches and caps, so an owner
// can always reduce or close.

import { PublicKey, TransactionMessage, VersionedTransaction, ComputeBudgetProgram } from '@solana/web3.js';
import { getAssociatedTokenAddressSync } from '@solana/spl-token';
import { sql } from '../db.js';
import { logAudit } from '../audit.js';
import { ensureAgentWallet, recoverSolanaAgentKeypair, getSolanaAddressBalances } from '../agent-wallet.js';
import { solanaConnection } from '../agent-pumpfun.js';
import { confirmOrThrow } from '../solana/confirm.js';
import { USDC_MINT_BY_NETWORK } from '../vault-jupiter.js';
import { currentSignatureFor, agreementRequirement } from '../real-funds-agreement.js';
import {
	getSpendLimits, getTradeLimits, reserveSpendUsd, releaseSpendReservation,
	recordCustodyEvent, updateCustodyEvent, SpendLimitError,
} from '../agent-trade-guards.js';
import {
	createActionPreview, loadActionPreview, consumeActionPreview, releaseActionPreview, ActionPreviewError,
} from '../action-previews.js';
import { getVenue, DEFAULT_VENUE, listVenues, ORDER_TYPES, SIDES } from './index.js';
import { PerpsError, perpsError } from './errors.js';
import { Wallet } from 'ethers';
import { decryptSecret, encryptSecret } from '../secret-box.js';
import { postExchange } from './hyperliquid-signing.js';
import { readWithFailover } from './venue-health.js';
import { getPerpsLimits, setPerpsLimits, checkPerpsOrder, quoteMoved } from './limits.js';
import {
	mutatePaper, loadPaperState, buildPaperAccount, applyFill, settleFunding, limitCrossed, triggerHit,
	listPaperFills, PAPER_MAX_COLLATERAL_USD,
} from './paper.js';
import { evaluateAlerts } from './alerts.js';

const PREFIX = 'perp';
const ORDER_PREVIEW_TTL_MS = 2 * 60_000;
const FUNDS_PREVIEW_TTL_MS = 5 * 60_000;
const USDC_DECIMALS = 6;
// SOL a perps transaction may spend: base fee, priority fee and at most one
// account rent. Anything past this fails the simulation bound.
const MAX_LAMPORTS_OUT = 5_000_000;
const MIN_SOL_FOR_FEES = 0.003;
const USDC_ROUNDING_ATOMIC = 10_000n;
const PRIORITY_MICROLAMPORTS = 50_000;
const MAX_COMPUTE_UNITS = 1_400_000;
// Settle paper funding into collateral at most this often unless a fill lands.
const FUNDING_SETTLE_MS = 15 * 60_000;
const MIN_USD = 1;
const MAX_FUNDS_USD = 1_000_000;

const HINT = 'Call the matching perps preview again for a fresh preview_id.';
const round = (n, dp = 6) => (n == null || !Number.isFinite(n) ? null : Math.round(n * 10 ** dp) / 10 ** dp);

/** Map any perps-stack failure to { status, code, message, detail } for a boundary. */
export function describeError(err) {
	if (err instanceof PerpsError || err instanceof ActionPreviewError || err instanceof SpendLimitError) {
		return { status: err.status || 400, code: err.code, message: err.message, detail: err.detail || null };
	}
	if (err && err.code === 'unknown_venue' && err.status) {
		return { status: err.status, code: err.code, message: err.message, detail: err.detail || null };
	}
	return null;
}

// ── agent, wallet, mode ──────────────────────────────────────────────────────

/** Load an agent the user owns. Throws 404 / 403. */
export async function loadOwnedAgent(agentId, userId) {
	const [row] = await sql`
		SELECT id, user_id, name, meta FROM agent_identities
		WHERE id = ${agentId} AND deleted_at IS NULL
	`;
	if (!row) throw perpsError(404, 'not_found', 'No agent with that id.');
	if (row.user_id !== userId) throw perpsError(403, 'forbidden', "That agent isn't on your account.");
	return row;
}

async function walletFor(agent, userId, reason) {
	const { address } = await ensureAgentWallet(agent.id, userId, { reason });
	return address;
}

/**
 * The mode an action runs in. An explicit 'paper' is always allowed; 'live'
 * only once the owner has enabled it. Omitted means the agent's default.
 */
export function resolveMode(limits, requested) {
	const want = requested == null || requested === '' ? null : String(requested).toLowerCase();
	if (want && want !== 'paper' && want !== 'live') {
		throw perpsError(400, 'invalid_mode', 'mode must be "paper" or "live".');
	}
	if (want === 'live' && !limits.live_enabled) {
		throw perpsError(403, 'live_disabled', 'Live perps trading is off for this agent. The owner turns it on under the perps limits; until then use paper mode, which fills at live prices without moving funds.');
	}
	return want || (limits.live_enabled ? 'live' : 'paper');
}

async function requireLiveAgreement(userId) {
	let signed;
	try {
		signed = await currentSignatureFor(userId);
	} catch {
		throw perpsError(503, 'agreement_check_unavailable', 'Could not verify your signed real-funds agreements, so nothing was sent. Try again in a moment.');
	}
	if (!signed) {
		throw perpsError(403, 'risk_ack_required', 'Sign the real-funds agreements (Terms of Service, Risk Disclosure, and Agent Wallet Agreement) before trading live perps. Nothing was sent.', agreementRequirement());
	}
}

function requireConfirm(confirm, what) {
	if (confirm !== true) {
		throw perpsError(400, 'confirmation_required', `This ${what} needs explicit confirmation. Show the preview to the owner and pass confirm_trade: true only after a clear yes.`);
	}
}

function parseUsd(v, name, { min = MIN_USD, max = MAX_FUNDS_USD } = {}) {
	const n = Number(v);
	if (!Number.isFinite(n) || n < min || n > max) {
		throw perpsError(400, `invalid_${name}`, `${name} must be between $${min} and $${max.toLocaleString('en-US')}.`);
	}
	return Math.floor(n * 100) / 100;
}

function parsePositive(v, name) {
	if (v == null || v === '') return null;
	const n = Number(v);
	if (!Number.isFinite(n) || n <= 0) throw perpsError(400, `invalid_${name}`, `${name} must be a positive number.`);
	return n;
}

function idempotencyKeyOf(key) {
	const k = typeof key === 'string' ? key.trim() : '';
	if (!k || k.length > 200) {
		throw perpsError(400, 'idempotency_key_required', 'Every perps execute needs an Idempotency-Key (1 to 200 characters), so a retried request never trades twice.');
	}
	return k;
}

// ── market reads ─────────────────────────────────────────────────────────────

/** Every market on the venue, most traded first. */
export async function markets({ venueId = null, kind = null } = {}) {
	const { venue, failed_over_from, result: list } = await readWithFailover(venueId, (v) => v.listMarkets({ kind }));
	return {
		venue: venue.id,
		venues: listVenues(),
		collateral: venue.collateral,
		failed_over_from,
		markets: list.map(({ params, asset_index: _i, ...m }) => m),
	};
}

/** Book, recent trades and funding history for one market. */
export async function marketData({ venueId = DEFAULT_VENUE, symbol, depth = 20, trades = 30, funding = 48 }) {
	const venue = getVenue(venueId);
	if (!symbol) throw perpsError(400, 'symbol_required', 'Pass a market symbol such as SOL or BTC. perps_markets lists them.');
	const { result: data } = await readWithFailover(venue.id, (v) => v.getMarketData(symbol, { depth, trades, funding }));
	return { venue: venue.id, ...data };
}

async function marketMap(venue) {
	const list = await venue.listMarkets();
	return new Map(list.map((m) => [m.symbol, m]));
}

// ── paper sync: funding, resting limits, triggers, liquidation ───────────────

/**
 * Bring an agent's paper ledger up to the live market: settle funding, fill any
 * resting limit the book has crossed, fire take-profits and stop-losses the
 * mark has reached, and liquidate an account under maintenance margin.
 * Returns the venue-shaped paper account at current marks.
 */
export async function syncPaper(agentId, userId, venue) {
	const mkts = await marketMap(venue);
	const books = new Map();
	const bookFor = async (symbol) => {
		if (!books.has(symbol)) books.set(symbol, venue.getMarketData(symbol, { depth: 5, trades: 0, funding: 0 }).then((d) => d.book));
		return books.get(symbol);
	};
	const result = await mutatePaper(agentId, userId, venue.id, async (prev) => {
		const now = Date.now();
		const open = prev.orders.filter((o) => o.status === 'open');
		const oldestFunding = Math.min(...[...prev.positions.values()].map((p) => p.funding_at), now);
		if (!open.length && now - oldestFunding < FUNDING_SETTLE_MS && !accountLiquidatable(prev, mkts, now)) {
			return { state: prev, result: buildPaperAccount(prev, mkts, now) };
		}
		let state = settleFunding(prev, mkts, now);
		const fills = [];
		const orderUpdates = [];

		for (const o of open.filter((x) => x.type === 'limit')) {
			const m = mkts.get(o.symbol);
			const book = await bookFor(o.symbol).catch(() => null);
			if (!m || !book || !limitCrossed(o, book)) continue;
			const pos = state.positions.get(o.symbol);
			let size = o.size;
			if (o.reduce_only) {
				const held = pos ? Math.abs(pos.signed_size) : 0;
				const closes = pos && Math.sign(pos.signed_size) !== (o.side === 'long' ? 1 : -1);
				if (!closes || held <= 0) {
					orderUpdates.push({ id: o.id, status: 'cancelled' });
					continue;
				}
				size = Math.min(size, held);
			}
			const out = applyFill(state, { symbol: o.symbol, delta: o.side === 'long' ? size : -size, price: o.price, feeUsd: size * o.price * (m.maker_fee_rate || 0), reason: 'limit', orderId: o.id });
			state = out.state;
			fills.push(out.fill);
			orderUpdates.push({ id: o.id, status: 'filled', fill_price: o.price });
		}

		for (const o of open.filter((x) => x.type === 'take_profit' || x.type === 'stop_loss')) {
			const m = mkts.get(o.symbol);
			const pos = state.positions.get(o.symbol);
			if (!pos || Math.abs(pos.signed_size) < 1e-12) {
				orderUpdates.push({ id: o.id, status: 'cancelled' });
				continue;
			}
			if (!m || !triggerHit(o, m.mark_price)) continue;
			const size = Math.abs(pos.signed_size) * ((o.size_percent ?? 100) / 100);
			// The trigger fires a closing order: fill at the mark, but never worse
			// than the execution price the trigger was placed with.
			const isLong = pos.signed_size > 0;
			const price = isLong ? Math.max(m.mark_price, o.price) : Math.min(m.mark_price, o.price);
			const out = applyFill(state, { symbol: o.symbol, delta: isLong ? -size : size, price, feeUsd: size * price * (m.taker_fee_rate || 0), reason: o.type, orderId: o.id });
			state = out.state;
			fills.push(out.fill);
			orderUpdates.push({ id: o.id, status: 'filled', fill_price: price });
		}

		if (accountLiquidatable(state, mkts, now)) {
			for (const [symbol, p] of state.positions) {
				if (Math.abs(p.signed_size) < 1e-12) continue;
				const m = mkts.get(symbol);
				const price = m?.mark_price ?? p.entry_price;
				const size = Math.abs(p.signed_size);
				const out = applyFill(state, { symbol, delta: -p.signed_size, price, feeUsd: size * price * (m?.taker_fee_rate || 0), reason: 'liquidation' });
				state = out.state;
				fills.push(out.fill);
			}
			for (const o of open) if (!orderUpdates.some((u) => u.id === o.id)) orderUpdates.push({ id: o.id, status: 'cancelled' });
		}

		const updatedIds = new Set(orderUpdates.map((u) => u.id));
		state = { ...state, orders: state.orders.filter((o) => !updatedIds.has(o.id)) };
		return { state, fills, orderUpdates, result: buildPaperAccount(state, mkts, now) };
	});
	return result;
}

function accountLiquidatable(state, mkts, now) {
	if (![...state.positions.values()].some((p) => Math.abs(p.signed_size) > 1e-12)) return false;
	const acct = buildPaperAccount(state, mkts, now);
	return acct.equity_usd < acct.maintenance_margin_usd;
}

// ── account ──────────────────────────────────────────────────────────────────

/**
 * The account a venue reads and trades for this agent. Solana venues use the
 * agent's own wallet; Hyperliquid uses the owner address linked on the agent.
 */
async function venueRef(venue, agent, userId, reason) {
	if (venue.chain === 'solana') return venue.accountRef({ agent, wallet: await walletFor(agent, userId, reason) });
	return venue.accountRef({ agent });
}

function requireCapability(venue, key, what) {
	if (venue.capabilities?.[key] === false) {
		throw perpsError(400, 'not_supported_on_venue', `${venue.label} does not support ${what}.`, { venue: venue.id, capability: key });
	}
}

async function accountFor({ agent, userId, venue, mode, reason = 'perps_read' }) {
	if (mode === 'paper') return syncPaper(agent.id, userId, venue);
	return venue.getAccount(await venueRef(venue, agent, userId, reason));
}

function summarize(account) {
	return {
		equity_usd: account.equity_usd,
		collateral_usd: account.collateral_usd,
		withdrawable_usd: account.withdrawable_usd,
		unrealized_pnl_usd: account.unrealized_pnl_usd,
		notional_usd: account.notional_usd,
		account_leverage: account.account_leverage,
		positions: account.positions.length,
		open_orders: account.orders.length + account.conditionals.length,
		risk_state: account.risk_state,
		closest_liquidation_pct: account.positions.reduce((min, p) => (p.liquidation_distance_pct != null && (min == null || p.liquidation_distance_pct < min) ? p.liquidation_distance_pct : min), null),
	};
}

/** The agent's perps account in one mode: collateral, positions, orders, limits. */
export async function account({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const solana = venue.chain === 'solana';
	const owner = solana ? await walletFor(agent, userId, 'perps_read') : (mode === 'live' ? await venueRef(venue, agent, userId, 'perps_read') : null);
	const [acct, balances] = await Promise.all([
		accountFor({ agent, userId, venue, mode }),
		mode === 'live' && solana ? getSolanaAddressBalances(owner, 'mainnet') : Promise.resolve(null),
	]);
	return {
		agent: { id: agent.id, name: agent.name },
		venue: venue.id,
		venue_label: venue.label,
		chain: venue.chain,
		capabilities: venue.capabilities,
		mode,
		wallet: { address: owner, usdc: balances?.usdc ?? null, sol: balances?.sol ?? null },
		limits,
		guards: guardState(agent.meta),
		summary: summarize(acct),
		account: acct,
		alerts: evaluateAlerts(acct, limits),
	};
}

function guardState(meta) {
	return { trade_kill_switch: getTradeLimits(meta).kill_switch === true, wallet_frozen: getSpendLimits(meta).frozen === true };
}

/** Positions, resting orders and recent history (paper fills, or live executions). */
export async function positions({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null, limit = 50 }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const acct = await accountFor({ agent, userId, venue, mode });
	const history = mode === 'paper'
		? await listPaperFills(agent.id, venue.id, { limit })
		: await listExecutions(agent.id, { mode: 'live', limit });
	return {
		venue: venue.id,
		mode,
		summary: summarize(acct),
		positions: acct.positions,
		orders: acct.orders,
		conditionals: acct.conditionals,
		history,
		paper: acct.paper || null,
	};
}

/** Executions this platform ran for an agent, newest first. */
export async function listExecutions(agentId, { mode = null, limit = 50 } = {}) {
	const rows = await sql`
		SELECT id, venue, mode, action, status, signatures, result, error, source, created_at, finished_at
		FROM perps_executions
		WHERE agent_id = ${agentId} AND (${mode}::text IS NULL OR mode = ${mode})
		ORDER BY id DESC LIMIT ${Math.min(200, Math.max(1, limit))}
	`;
	return rows.map((r) => ({
		id: String(r.id),
		venue: r.venue,
		mode: r.mode,
		action: r.action,
		status: r.status,
		signatures: r.signatures || [],
		summary: r.result?.summary || null,
		error: r.error ? { code: r.error.code, message: r.error.message } : null,
		source: r.source,
		created_at: new Date(r.created_at).toISOString(),
		finished_at: r.finished_at ? new Date(r.finished_at).toISOString() : null,
	}));
}

/** The live tracker frame: per-position PnL, funding, liquidation distance, plus alerts. */
export async function trackerFrame({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const acct = await accountFor({ agent, userId, venue, mode });
	return {
		at: new Date().toISOString(),
		venue: venue.id,
		mode,
		halted: limits.halted,
		summary: summarize(acct),
		positions: acct.positions.map((p) => ({
			symbol: p.symbol,
			side: p.side,
			size: p.size,
			entry_price: p.entry_price,
			mark_price: p.mark_price,
			notional_usd: p.notional_usd,
			unrealized_pnl_usd: p.unrealized_pnl_usd,
			funding_paid_usd: p.funding_accrued_usd,
			liquidation_price: p.liquidation_price,
			liquidation_distance_pct: p.liquidation_distance_pct,
			take_profit_price: p.take_profit_price,
			stop_loss_price: p.stop_loss_price,
		})),
		orders: acct.orders.length + acct.conditionals.length,
		alerts: evaluateAlerts(acct, limits),
	};
}

// ── MCP access ───────────────────────────────────────────────────────────────

/** Has the owner opted this agent into MCP perps trading? Default is no. */
export async function mcpAccess({ agentId, userId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	return getPerpsLimits(agent.meta).mcp_enabled === true;
}

/** Does this account have at least one agent opted into MCP perps trading? */
export async function accountHasMcpPerps(userId) {
	if (!userId) return false;
	const [row] = await sql`
		SELECT 1 AS ok FROM agent_identities
		WHERE user_id = ${userId} AND deleted_at IS NULL AND meta->'perps_limits'->>'mcp_enabled' = 'true'
		LIMIT 1
	`;
	return Boolean(row);
}

// ── Hyperliquid API wallet ───────────────────────────────────────────────────

const HL_APPROVE_URL = 'https://app.hyperliquid.xyz/API';

/** Pure: the public status of an agent's Hyperliquid link. Never includes the key. */
export function hyperliquidLinkView(meta, approved = null) {
	const h = meta?.hyperliquid;
	if (!h?.account) return { linked: false, account: null, api_wallet_address: null, approved: false, approve_url: HL_APPROVE_URL };
	return {
		linked: true,
		account: h.account,
		api_wallet_address: h.api_wallet?.address ?? null,
		approved: approved === true,
		approve_url: HL_APPROVE_URL,
		created_at: h.api_wallet?.created_at ?? null,
	};
}

/**
 * Owner-only: link a Hyperliquid account and mint the agent's API wallet. The
 * platform generates the key and stores it sealed, so the owner never pastes a
 * secret. The owner then approves the returned address on Hyperliquid (an API
 * wallet can trade but never withdraw). Re-linking replaces the key.
 */
export async function linkHyperliquid({ agentId, userId, account, req = null }) {
	const agent = await loadOwnedAgent(agentId, userId);
	if (!/^0x[0-9a-fA-F]{40}$/.test(String(account || ''))) {
		throw perpsError(400, 'invalid_venue_account', 'account must be the 0x address of your Hyperliquid account.');
	}
	const apiWallet = Wallet.createRandom();
	const record = {
		account: String(account).toLowerCase(),
		api_wallet: { address: apiWallet.address.toLowerCase(), encrypted: await encryptSecret(apiWallet.privateKey), created_at: new Date().toISOString() },
	};
	await sql`
		UPDATE agent_identities
		SET meta = jsonb_set(coalesce(meta, '{}'::jsonb), '{hyperliquid}', ${JSON.stringify(record)}::jsonb)
		WHERE id = ${agent.id}
	`;
	logAudit({ userId, action: 'custody.perps_hyperliquid_link', resourceId: agent.id, meta: { account: record.account, api_wallet: record.api_wallet.address }, req });
	return hyperliquidLinkView({ hyperliquid: record }, false);
}

/** Link status, with a live check of whether the owner has approved the API wallet. */
export async function hyperliquidStatus({ agentId, userId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const view = hyperliquidLinkView(agent.meta, false);
	if (!view.linked) return view;
	const venue = getVenue('hyperliquid');
	const approvedList = await venue.listApprovedApiWallets(view.account).catch(() => null);
	return { ...view, approved: approvedList ? approvedList.some((w) => w.address === view.api_wallet_address) : null };
}

/** Owner-only: forget the account and destroy the sealed API wallet key. */
export async function unlinkHyperliquid({ agentId, userId, req = null }) {
	const agent = await loadOwnedAgent(agentId, userId);
	await sql`UPDATE agent_identities SET meta = coalesce(meta, '{}'::jsonb) - 'hyperliquid' WHERE id = ${agent.id}`;
	logAudit({ userId, action: 'custody.perps_hyperliquid_unlink', resourceId: agent.id, meta: {}, req });
	return hyperliquidLinkView({}, false);
}

// ── limits ───────────────────────────────────────────────────────────────────

export async function getLimits({ agentId, userId }) {
	const agent = await loadOwnedAgent(agentId, userId);
	return { limits: getPerpsLimits(agent.meta), guards: guardState(agent.meta) };
}

/** Owner-only: patch the perps limits. Turning live on requires the signed agreements. */
export async function updateLimits({ agentId, userId, patch, req = null }) {
	const agent = await loadOwnedAgent(agentId, userId);
	const prev = getPerpsLimits(agent.meta);
	if (patch?.live_enabled === true && !prev.live_enabled) await requireLiveAgreement(userId);
	const reason = patch?.halted === false && prev.halted ? 'perps_resumed' : 'perps_limits_updated';
	const limits = await setPerpsLimits(agentId, userId, patch, { req, reason });
	return { limits, guards: guardState(agent.meta) };
}

// ── live transaction path ────────────────────────────────────────────────────

function usdcAta(owner) {
	return getAssociatedTokenAddressSync(new PublicKey(USDC_MINT_BY_NETWORK.mainnet), new PublicKey(owner), true);
}

function decodeTokenAmount(account) {
	if (!account) return 0n;
	const data = Array.isArray(account.data) ? Buffer.from(account.data[0], 'base64') : null;
	if (!data || data.length < 72) return 0n;
	return data.readBigUInt64LE(64);
}

async function compile(conn, owner, instructions, units) {
	const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash('confirmed');
	const message = new TransactionMessage({
		payerKey: new PublicKey(owner),
		recentBlockhash: blockhash,
		instructions: [
			ComputeBudgetProgram.setComputeUnitLimit({ units }),
			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: PRIORITY_MICROLAMPORTS }),
			...instructions,
		],
	}).compileToV0Message();
	return { vtx: new VersionedTransaction(message), blockhash, lastValidBlockHeight };
}

/**
 * Simulate against current chain state and verify the agent's USDC and SOL
 * move within bounds. Returns the compute units the transaction used.
 */
async function simulateWithinBounds({ conn, vtx, owner, maxUsdcOutAtomic, maxLamportsOut = MAX_LAMPORTS_OUT }) {
	const ownerKey = new PublicKey(owner);
	const ata = usdcAta(owner);
	const [preLamports, preUsdc] = await Promise.all([
		conn.getBalance(ownerKey, 'confirmed'),
		conn.getTokenAccountBalance(ata, 'confirmed').then((b) => BigInt(b?.value?.amount || '0')).catch(() => 0n),
	]);
	let sim;
	try {
		sim = await conn.simulateTransaction(vtx, {
			sigVerify: false,
			replaceRecentBlockhash: true,
			commitment: 'confirmed',
			accounts: { encoding: 'base64', addresses: [ownerKey.toBase58(), ata.toBase58()] },
		});
	} catch (err) {
		throw perpsError(503, 'simulation_unavailable', 'Could not simulate the transaction before signing, so nothing was sent. Try again.', { message: err?.message?.slice(0, 200) || null });
	}
	const v = sim?.value;
	if (v?.err) {
		throw perpsError(422, 'simulation_failed', 'The venue transaction failed simulation, so it was not sent and no funds moved.', { err: v.err, logs: (v.logs || []).slice(-8) });
	}
	const postLamports = v?.accounts?.[0]?.lamports ?? preLamports;
	const postUsdc = v?.accounts?.[1] ? decodeTokenAmount(v.accounts[1]) : preUsdc;
	const usdcOut = preUsdc - postUsdc;
	const lamportsOut = preLamports - postLamports;
	if (usdcOut > maxUsdcOutAtomic + USDC_ROUNDING_ATOMIC) {
		throw perpsError(422, 'simulation_out_of_bounds', 'The venue transaction would move more USDC than you confirmed, so it was not signed.', {
			usdc_out: Number(usdcOut) / 10 ** USDC_DECIMALS,
			allowed_usdc_out: Number(maxUsdcOutAtomic) / 10 ** USDC_DECIMALS,
		});
	}
	if (lamportsOut > maxLamportsOut) {
		throw perpsError(422, 'simulation_out_of_bounds', 'The venue transaction would spend more SOL than network fees and one account rent, so it was not signed.', {
			sol_out: lamportsOut / 1e9,
			allowed_sol_out: maxLamportsOut / 1e9,
		});
	}
	return { usdc_out: Number(usdcOut) / 10 ** USDC_DECIMALS, sol_out: lamportsOut / 1e9, units: v?.unitsConsumed ?? null };
}

async function agentKeypair(agentId, userId, reason, meta) {
	const [row] = await sql`SELECT meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;
	const secret = row?.meta?.encrypted_solana_secret;
	if (!secret) {
		throw perpsError(409, 'wallet_unsignable', 'This agent wallet has no platform-held key (it is self-custodied or not yet provisioned), so the platform cannot sign perps transactions for it.');
	}
	return recoverSolanaAgentKeypair(secret, { agentId, userId, reason, meta });
}

/**
 * Simulate, sign and land one transaction of venue instructions. `sent` on the
 * returned object (and on a thrown error) says whether it reached the network.
 */
async function landInstructions({ agentId, userId, owner, instructions, maxUsdcOutAtomic, reason, meta, submitVia = null }) {
	const conn = solanaConnection('mainnet');
	const draft = await compile(conn, owner, instructions, MAX_COMPUTE_UNITS);
	const sim = await simulateWithinBounds({ conn, vtx: draft.vtx, owner, maxUsdcOutAtomic });
	const units = Math.min(MAX_COMPUTE_UNITS, Math.max(50_000, Math.ceil((sim.units || 400_000) * 1.25)));
	const final = await compile(conn, owner, instructions, units);
	const keypair = await agentKeypair(agentId, userId, reason, meta);
	final.vtx.sign([keypair]);
	let signature;
	try {
		if (submitVia) {
			signature = (await submitVia(Buffer.from(final.vtx.serialize()).toString('base64'))).signature;
		} else {
			signature = await conn.sendRawTransaction(final.vtx.serialize(), { skipPreflight: false, maxRetries: 3 });
		}
	} catch (err) {
		if (err instanceof PerpsError) throw err;
		throw perpsError(502, 'send_failed', 'The network refused the transaction, so nothing moved. Try again.', { message: String(err?.message || err).slice(0, 240) });
	}
	try {
		await confirmOrThrow(conn, { signature, blockhash: final.blockhash, lastValidBlockHeight: final.lastValidBlockHeight });
	} catch (err) {
		throw Object.assign(
			perpsError(502, err?.code === 'tx_reverted' ? 'transaction_reverted' : 'confirmation_timeout',
				err?.code === 'tx_reverted'
					? 'The transaction landed but the venue program rejected it, so nothing changed beyond the network fee.'
					: 'The transaction was sent but not confirmed in time. Check the explorer link before retrying.',
				{ signature, explorer: explorer(signature) }),
			{ sent: true, signature },
		);
	}
	return { signature, explorer: explorer(signature), simulation: sim };
}

/**
 * Land a venue-built Solana transaction (Jupiter): simulate it against current
 * chain state inside the confirmed collateral bounds, sign with the agent
 * wallet, submit through the venue and wait for confirmation.
 */
async function landTransaction({ agentId, userId, venue, owner, quote, reason, meta }) {
	const conn = solanaConnection('mainnet');
	const built = await venue.buildOrder(owner, quote);
	const vtx = VersionedTransaction.deserialize(Buffer.from(built.serializedTxBase64, 'base64'));
	const collateralUsd = quote.risk_increasing ? quote.notional_usd / (quote.quote_leverage || 1) : 0;
	const usdcAllowed = quote.risk_increasing && quote.side === 'short' ? BigInt(Math.ceil((collateralUsd * 1.1 + (quote.fee_usd || 0) + 0.5) * 10 ** USDC_DECIMALS)) : 0n;
	const solAllowed = quote.risk_increasing && quote.side === 'long' && quote.mark_price > 0
		? Math.ceil((collateralUsd / quote.mark_price) * 1.1 * 1e9)
		: 0;
	const sim = await simulateWithinBounds({ conn, vtx, owner, maxUsdcOutAtomic: usdcAllowed, maxLamportsOut: MAX_LAMPORTS_OUT + solAllowed });
	const keypair = await agentKeypair(agentId, userId, reason, meta);
	vtx.sign([keypair]);
	let signature;
	try {
		({ signature } = await venue.submitSigned({ action: built.action, serializedTxBase64: Buffer.from(vtx.serialize()).toString('base64') }));
	} catch (err) {
		if (err instanceof PerpsError) throw err;
		throw perpsError(502, 'send_failed', 'The venue refused the transaction, so nothing moved. Try again.', { message: String(err?.message || err).slice(0, 240) });
	}
	try {
		const lastValidBlockHeight = built.lastValidBlockHeight ?? (await conn.getBlockHeight('confirmed')) + 150;
		await confirmOrThrow(conn, { signature, blockhash: built.blockhash || vtx.message.recentBlockhash, lastValidBlockHeight });
	} catch (err) {
		throw Object.assign(
			perpsError(502, err?.code === 'tx_reverted' ? 'transaction_reverted' : 'confirmation_timeout',
				err?.code === 'tx_reverted'
					? 'The transaction landed but the venue program rejected it, so nothing changed beyond the network fee.'
					: 'The transaction was sent but not confirmed in time. Check the explorer link before retrying.',
				{ signature, explorer: explorer(signature) }),
			{ sent: true, signature },
		);
	}
	return { signature, explorer: explorer(signature), simulation: sim };
}

/**
 * Sign a venue action with the agent's approved API wallet and post it. The API
 * wallet can trade but cannot withdraw, so the worst a leaked key does is trade
 * inside the owner's limits until they revoke it on the venue.
 */
async function landApiWallet({ agent, venue, action }) {
	const sealed = agent.meta?.hyperliquid?.api_wallet?.encrypted;
	if (!sealed) throw perpsError(409, 'api_wallet_missing', 'This agent has no Hyperliquid API wallet registered, so the platform cannot sign for it. Nothing was sent.');
	const privateKey = await decryptSecret(sealed);
	let res;
	try {
		res = await postExchange({ privateKey, action, isMainnet: true });
	} catch (err) {
		throw Object.assign(
			perpsError(502, 'venue_unavailable', 'Hyperliquid did not confirm the request. Check the account before retrying.', { message: String(err?.message || err).slice(0, 240) }),
			{ sent: true },
		);
	}
	return { signature: null, explorer: null, venue_result: venue.parseOrderResponse(res) };
}

/** Land one quoted order on whatever rail the venue uses. */
async function landVenueOrder({ agent, userId, venue, ref, quote, reason, meta }) {
	if (venue.execution === 'api_wallet') return landApiWallet({ agent, venue, action: await venue.buildOrder(ref, quote) });
	if (venue.execution === 'transaction') return landTransaction({ agentId: agent.id, userId, venue, owner: ref, quote, reason, meta });
	const instructions = await venue.buildOrder(ref, quote);
	return landInstructions({ agentId: agent.id, userId, owner: ref, instructions, maxUsdcOutAtomic: 0n, reason, meta });
}

const explorer = (sig) => `https://solscan.io/tx/${sig}`;

// ── idempotent execution ledger ──────────────────────────────────────────────

/**
 * Run `fn` once per (agent, Idempotency-Key). A replay of a finished execution
 * returns its stored result; an execution still running is a 409; a key reused
 * for a different preview is a 422. An execution that failed before anything
 * reached the network frees its key, so the caller can retry with a new preview.
 */
async function onceByKey({ agent, userId, venue, mode, action, previewId, key, source }, fn) {
	const [existing] = await sql`
		SELECT id, preview_id, status, result, error FROM perps_executions
		WHERE agent_id = ${agent.id} AND idempotency_key = ${key}
	`;
	if (existing) return replay(existing, previewId);

	const [row] = await sql`
		INSERT INTO perps_executions (agent_id, user_id, venue, mode, action, idempotency_key, preview_id, source)
		VALUES (${agent.id}, ${userId}, ${venue.id}, ${mode}, ${action}, ${key}, ${previewId}, ${source})
		ON CONFLICT (agent_id, idempotency_key) DO NOTHING
		RETURNING id
	`;
	if (!row) {
		const [raced] = await sql`SELECT id, preview_id, status, result, error FROM perps_executions WHERE agent_id = ${agent.id} AND idempotency_key = ${key}`;
		return replay(raced, previewId);
	}

	try {
		const result = await fn();
		await sql`
			UPDATE perps_executions SET status = 'ok', result = ${JSON.stringify(result)}::jsonb,
				signatures = ${result.signatures || []}, finished_at = now()
			WHERE id = ${row.id}
		`;
		return result;
	} catch (err) {
		const d = describeError(err) || { status: 500, code: 'perps_failed', message: 'The perps action failed.', detail: null };
		if (err?.sent || err?.partial) {
			await sql`
				UPDATE perps_executions SET status = 'failed', error = ${JSON.stringify(d)}::jsonb,
					signatures = ${err.signatures || (err.signature ? [err.signature] : [])}, finished_at = now()
				WHERE id = ${row.id}
			`;
		} else {
			await sql`DELETE FROM perps_executions WHERE id = ${row.id}`;
		}
		throw err;
	}
}

function replay(row, previewId) {
	if (!row) throw perpsError(409, 'execution_in_progress', 'An execution with this Idempotency-Key is already running. Wait for it, then read the account.');
	if (row.preview_id !== previewId) {
		throw perpsError(422, 'idempotency_key_reused', 'This Idempotency-Key was already used for a different preview. Use a new key for a new action.');
	}
	if (row.status === 'pending') {
		throw perpsError(409, 'execution_in_progress', 'An execution with this Idempotency-Key is already running. Wait for it, then read the account.');
	}
	if (row.status === 'failed') {
		const e = row.error || {};
		throw perpsError(e.status || 502, e.code || 'perps_failed', e.message || 'This execution failed.', { ...(e.detail || {}), replayed: true });
	}
	return { ...row.result, replayed: true };
}

async function begin({ agentId, userId, previewId, action, confirm, idempotencyKey, what }) {
	requireConfirm(confirm, what);
	const key = idempotencyKeyOf(idempotencyKey);
	const agent = await loadOwnedAgent(agentId, userId);
	return { agent, key, previewId: String(previewId || ''), action };
}

/** Load the preview, resolve its venue and mode, and refuse if live was turned off since. */
async function previewContext({ agent, userId, previewId, action }) {
	const preview = await loadActionPreview(previewId, { userId, agentId: agent.id, action, hint: HINT });
	const venue = getVenue(preview.params.venue);
	const limits = getPerpsLimits(agent.meta);
	const mode = preview.params.mode;
	if (mode === 'live') {
		if (!limits.live_enabled) throw perpsError(403, 'live_disabled', 'Live perps trading was turned off for this agent after the preview, so nothing was sent.');
		await requireLiveAgreement(userId);
	}
	return { preview, venue, limits, mode };
}

// ── collateral: deposit ──────────────────────────────────────────────────────

export async function previewDeposit({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null, amountUsd }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const amount = parseUsd(amountUsd, 'amount_usd');
	if (mode === 'live') requireCapability(venue, 'deposit_withdraw', 'deposits from the agent wallet');
	const owner = await walletFor(agent, userId, 'perps_preview');
	const acct = await accountFor({ agent, userId, venue, mode });
	const spend = getSpendLimits(agent.meta);
	const checks = [];
	let quote;

	if (mode === 'paper') {
		const after = acct.collateral_usd + amount;
		checks.push({ id: 'paper_cap', ok: after <= PAPER_MAX_COLLATERAL_USD, label: `Paper collateral after the deposit: $${after.toFixed(2)} of $${PAPER_MAX_COLLATERAL_USD.toLocaleString('en-US')} allowed` });
		quote = {
			from: 'Paper balance (simulated, no funds move)',
			to: 'Paper perps collateral',
			amount_usd: amount,
			asset: venue.collateral.asset,
			chain: 'solana',
			collateral_before_usd: acct.collateral_usd,
			collateral_after_usd: round(after, 6),
		};
	} else {
		const balances = await getSolanaAddressBalances(owner, 'mainnet');
		checks.push(
			{ id: 'wallet_usdc', ok: balances.usdc != null && balances.usdc + 1e-9 >= amount, label: balances.usdc == null ? 'Could not read the wallet USDC balance' : `Wallet holds $${balances.usdc.toFixed(2)} USDC for a $${amount.toFixed(2)} deposit` },
			{ id: 'wallet_sol', ok: balances.sol != null && balances.sol >= MIN_SOL_FOR_FEES, label: balances.sol == null ? 'Could not read the wallet SOL balance' : `Wallet holds ${balances.sol.toFixed(4)} SOL for network fees${acct.registered ? '' : ' and the one-time trader account rent'}` },
			{ id: 'wallet_frozen', ok: !spend.frozen, label: spend.frozen ? 'The wallet is frozen' : 'The wallet is not frozen' },
		);
		if (spend.per_tx_usd != null) checks.push({ id: 'per_tx', ok: amount <= spend.per_tx_usd + 1e-9, label: `Wallet per-transaction limit: $${spend.per_tx_usd.toFixed(2)}` });
		quote = {
			from: owner,
			to: acct.trader_account,
			to_label: `${venue.label} trader account`,
			amount_usd: amount,
			asset: venue.collateral.asset,
			chain: 'solana',
			registers_account: !acct.registered,
			collateral_before_usd: acct.collateral_usd,
			collateral_after_usd: round(acct.collateral_usd + amount, 6),
			wallet: { address: owner, usdc: balances.usdc, sol: balances.sol },
		};
	}
	return storePreview({ agent, userId, venue, mode, kind: 'deposit', action: 'perps.deposit', ttlMs: FUNDS_PREVIEW_TTL_MS, params: { amount_usd: amount }, quote, checks });
}

export async function executeDeposit({ agentId, userId, previewId, confirm, idempotencyKey, req = null, source = 'owner' }) {
	const { agent, key } = await begin({ agentId, userId, previewId, confirm, idempotencyKey, what: 'deposit' });
	const { preview, venue, mode } = await previewContext({ agent, userId, previewId, action: 'perps.deposit' });
	const amount = preview.params.amount_usd;
	return onceByKey({ agent, userId, venue, mode, action: 'deposit', previewId: preview.id, key, source }, async () => {
		await consumeActionPreview(preview.id, { hint: HINT });
		try {
			if (mode === 'paper') {
				const after = await mutatePaper(agent.id, userId, venue.id, (s) => {
					if (s.collateral_usd + amount > PAPER_MAX_COLLATERAL_USD + 1e-6) {
						throw perpsError(409, 'paper_cap', `Paper collateral is capped at $${PAPER_MAX_COLLATERAL_USD.toLocaleString('en-US')}.`);
					}
					const state = { ...s, collateral_usd: s.collateral_usd + amount, deposited_usd: s.deposited_usd + amount };
					return { state, result: state.collateral_usd };
				});
				logAudit({ userId, action: 'perps.paper_deposit', resourceId: agent.id, meta: { amount_usd: amount, source }, req });
				return { ok: true, mode, action: 'deposit', amount_usd: amount, collateral_usd: round(after, 6), signatures: [], summary: `Paper deposit of $${amount.toFixed(2)}` };
			}
			return await liveDeposit({ agent, userId, venue, amount, preview, req, source });
		} catch (err) {
			if (!err?.sent) await releaseActionPreview(preview.id).catch(() => {});
			throw err;
		}
	});
}

async function liveDeposit({ agent, userId, venue, amount, preview, req, source }) {
	const owner = await walletFor(agent, userId, 'perps_deposit');
	const reservation = await reserveSpendUsd({
		agentId: agent.id,
		userId,
		meta: agent.meta,
		category: 'perps',
		usdValue: amount,
		destination: `perps-venue:${venue.id}`,
		asset: venue.collateral.asset,
		rowMeta: { perps_action: 'deposit', venue: venue.id, preview_id: preview.id, source },
	});
	const custodyId = reservation.reservationId;
	const signatures = [];
	try {
		const acct = await venue.getAccount(owner);
		if (!acct.registered) {
			const prep = await venue.prepareAccount(owner);
			if (prep.instructions.length) {
				const landed = await landInstructions({
					agentId: agent.id, userId, owner, instructions: prep.instructions, maxUsdcOutAtomic: 0n,
					reason: 'perps_register', meta: { venue: venue.id, custody_event_id: custodyId },
					submitVia: prep.cosigned_by_venue ? (tx) => venue.submitPrepare({ authority: owner, transactionBase64: tx }) : null,
				});
				signatures.push(landed.signature);
			}
		}
		const ixs = await venue.buildDeposit(owner, amount);
		const landed = await landInstructions({
			agentId: agent.id, userId, owner, instructions: ixs,
			maxUsdcOutAtomic: BigInt(Math.round(amount * 10 ** USDC_DECIMALS)),
			reason: 'perps_deposit', meta: { venue: venue.id, custody_event_id: custodyId },
		});
		signatures.push(landed.signature);
		await updateCustodyEvent(custodyId, { status: 'confirmed', signature: landed.signature, meta: { simulation: landed.simulation, signatures } }).catch(() => {});
		logAudit({ userId, action: 'custody.perps_deposit', resourceId: agent.id, meta: { amount_usd: amount, venue: venue.id, signatures, source }, req });
		return { ok: true, mode: 'live', action: 'deposit', amount_usd: amount, signature: landed.signature, explorer: landed.explorer, signatures, summary: `Deposited $${amount.toFixed(2)} ${venue.collateral.asset}` };
	} catch (err) {
		if (err?.sent) {
			await updateCustodyEvent(custodyId, { status: 'failed', signature: err.signature }).catch(() => {});
		} else {
			await releaseSpendReservation(custodyId, err?.code || 'perps_deposit_failed').catch(() => {});
		}
		logAudit({ userId, action: 'custody.perps_deposit_failed', resourceId: agent.id, meta: { amount_usd: amount, code: err?.code || null, signatures, source }, req });
		if (signatures.length) Object.assign(err, { partial: true, signatures: [...signatures, ...(err.signature ? [err.signature] : [])] });
		throw err;
	}
}

// ── collateral: withdraw ─────────────────────────────────────────────────────

export async function previewWithdraw({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null, amountUsd }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	if (mode === 'live') requireCapability(venue, 'deposit_withdraw', 'withdrawals to the agent wallet');
	const owner = await walletFor(agent, userId, 'perps_preview');
	const acct = await accountFor({ agent, userId, venue, mode });
	const all = amountUsd === 'max' || amountUsd === 'all';
	const amount = all ? Math.floor((acct.withdrawable_usd || 0) * 100) / 100 : parseUsd(amountUsd, 'amount_usd');
	const checks = [
		{ id: 'withdrawable', ok: amount > 0 && amount <= (acct.withdrawable_usd || 0) + 1e-6, label: `Withdrawable now: $${Number(acct.withdrawable_usd || 0).toFixed(2)} (collateral not backing open positions)` },
	];
	if (mode === 'live') checks.push({ id: 'registered', ok: acct.registered, label: acct.registered ? 'Trader account exists' : 'No trader account yet: there is nothing to withdraw' });
	const quote = {
		from: mode === 'paper' ? 'Paper perps collateral' : acct.trader_account,
		from_label: mode === 'paper' ? null : `${venue.label} trader account`,
		to: mode === 'paper' ? 'Paper balance (simulated, no funds move)' : owner,
		amount_usd: amount,
		asset: venue.collateral.asset,
		chain: 'solana',
		collateral_before_usd: acct.collateral_usd,
		collateral_after_usd: round(acct.collateral_usd - amount, 6),
		withdrawable_usd: acct.withdrawable_usd,
	};
	return storePreview({ agent, userId, venue, mode, kind: 'withdraw', action: 'perps.withdraw', ttlMs: FUNDS_PREVIEW_TTL_MS, params: { amount_usd: amount }, quote, checks });
}

export async function executeWithdraw({ agentId, userId, previewId, confirm, idempotencyKey, req = null, source = 'owner' }) {
	const { agent, key } = await begin({ agentId, userId, previewId, confirm, idempotencyKey, what: 'withdrawal' });
	const { preview, venue, mode } = await previewContext({ agent, userId, previewId, action: 'perps.withdraw' });
	const amount = preview.params.amount_usd;
	return onceByKey({ agent, userId, venue, mode, action: 'withdraw', previewId: preview.id, key, source }, async () => {
		const acct = await accountFor({ agent, userId, venue, mode });
		if (amount > (acct.withdrawable_usd || 0) + 1e-6) {
			throw perpsError(409, 'insufficient_withdrawable', `Only $${Number(acct.withdrawable_usd || 0).toFixed(2)} is withdrawable now; the rest backs open positions.`, { withdrawable_usd: acct.withdrawable_usd });
		}
		await consumeActionPreview(preview.id, { hint: HINT });
		try {
			if (mode === 'paper') {
				const after = await mutatePaper(agent.id, userId, venue.id, (s) => {
					const state = { ...s, collateral_usd: s.collateral_usd - amount, withdrawn_usd: s.withdrawn_usd + amount };
					return { state, result: state.collateral_usd };
				});
				logAudit({ userId, action: 'perps.paper_withdraw', resourceId: agent.id, meta: { amount_usd: amount, source }, req });
				return { ok: true, mode, action: 'withdraw', amount_usd: amount, collateral_usd: round(after, 6), signatures: [], summary: `Paper withdrawal of $${amount.toFixed(2)}` };
			}
			const owner = await walletFor(agent, userId, 'perps_withdraw');
			const custodyId = await recordCustodyEvent({
				agentId: agent.id, userId, eventType: 'perps_withdraw', category: 'perps', asset: venue.collateral.asset,
				usd: amount, status: 'pending', reason: 'perps_withdraw', destination: owner, meta: { venue: venue.id, preview_id: preview.id, source },
			});
			try {
				const ixs = await venue.buildWithdraw(owner, amount);
				const landed = await landInstructions({ agentId: agent.id, userId, owner, instructions: ixs, maxUsdcOutAtomic: 0n, reason: 'perps_withdraw', meta: { venue: venue.id, custody_event_id: custodyId } });
				await updateCustodyEvent(custodyId, { status: 'confirmed', signature: landed.signature }).catch(() => {});
				logAudit({ userId, action: 'custody.perps_withdraw', resourceId: agent.id, meta: { amount_usd: amount, venue: venue.id, signature: landed.signature, source }, req });
				return { ok: true, mode, action: 'withdraw', amount_usd: amount, signature: landed.signature, explorer: landed.explorer, signatures: [landed.signature], summary: `Withdrew $${amount.toFixed(2)} ${venue.collateral.asset} to the agent wallet` };
			} catch (err) {
				await updateCustodyEvent(custodyId, { status: 'failed', signature: err?.signature ?? null }).catch(() => {});
				throw err;
			}
		} catch (err) {
			if (!err?.sent) await releaseActionPreview(preview.id).catch(() => {});
			throw err;
		}
	});
}

// ── orders ───────────────────────────────────────────────────────────────────

function parseOrderInput(input) {
	const side = String(input.side || '').toLowerCase();
	if (!SIDES.includes(side)) throw perpsError(400, 'invalid_side', 'side must be "long" or "short".');
	const type = String(input.type || 'market').toLowerCase();
	if (!ORDER_TYPES.includes(type)) throw perpsError(400, 'invalid_type', `type must be one of ${ORDER_TYPES.join(', ')}.`);
	if (!input.symbol) throw perpsError(400, 'symbol_required', 'Pass a market symbol such as SOL or BTC. perps_markets lists them.');
	return {
		symbol: String(input.symbol),
		side,
		type,
		size: parsePositive(input.size, 'size'),
		marginUsd: parsePositive(input.marginUsd, 'margin_usd'),
		leverage: parsePositive(input.leverage, 'leverage'),
		price: parsePositive(input.price, 'price'),
		triggerPrice: parsePositive(input.triggerPrice, 'trigger_price'),
		sizePercent: input.sizePercent == null ? 100 : Math.max(1, Math.min(100, Math.round(Number(input.sizePercent) || 100))),
		reduceOnly: input.reduceOnly === true,
		slippageBps: input.slippageBps == null ? null : Math.round(Number(input.slippageBps)),
	};
}

const BLOCK_CODES = {
	mode: ['live_disabled', 403],
	halted: ['perps_halted', 403],
	trade_kill_switch: ['trade_kill_switch', 403],
	wallet_frozen: ['wallet_frozen', 403],
	leverage: ['leverage_cap_exceeded', 403],
	position_margin: ['position_margin_exceeded', 403],
	max_notional: ['max_notional_exceeded', 403],
	liquidation_distance: ['liquidation_too_close', 403],
	free_collateral: ['insufficient_collateral', 409],
	slippage: ['slippage_too_high', 400],
	no_trader_account: ['no_trader_account', 409],
	wallet_sol: ['insufficient_sol', 409],
	api_wallet: ['api_wallet_missing', 409],
};

function throwBlocked(check, detail = {}) {
	const [code, status] = BLOCK_CODES[check.id] || ['perps_guard', 403];
	throw perpsError(status, code, `${check.label}. Nothing was sent.`, { check: check.id, ...detail });
}

/** Resolve the order's size from `size`, or from margin and leverage at the reference price. */
async function resolveSize(venue, o, limits) {
	if (o.size) return o.size;
	if (o.marginUsd) {
		const lev = Math.min(o.leverage || 1, limits.max_leverage);
		const market = await venue.getMarket(o.symbol);
		const ref = o.type === 'limit' && o.price ? o.price : market.mark_price;
		if (!(ref > 0)) throw perpsError(409, 'no_price', `${market.symbol} has no mark price right now; pass size instead.`);
		return (o.marginUsd * lev) / ref;
	}
	throw perpsError(400, 'size_required', 'Pass size in base units (0.5 means half a SOL on the SOL market), or margin_usd with leverage.');
}

async function quoteFor({ venue, o, acct, limits }) {
	if (o.type === 'take_profit' || o.type === 'stop_loss') return quoteTrigger({ venue, o, acct });
	const slippageBps = o.slippageBps ?? limits.max_slippage_bps;
	return venue.quoteOrder({
		symbol: o.symbol, side: o.side, size: o.size, type: o.type, price: o.price,
		reduceOnly: o.reduceOnly, slippageBps, account: acct,
		leverage: Math.min(o.leverage || 2, limits.max_leverage),
	});
}

/** Quote a take-profit or stop-loss on the open position (never risk-increasing). */
async function quoteTrigger({ venue, o, acct }) {
	const market = await venue.getMarket(o.symbol);
	const pos = acct.positions.find((p) => p.symbol === market.symbol);
	if (!pos) throw perpsError(409, 'no_position', `There is no open ${market.symbol} position to attach a ${o.type.replace('_', '-')} to.`);
	if (!o.triggerPrice) throw perpsError(400, 'trigger_price_required', `A ${o.type.replace('_', '-')} needs trigger_price.`);
	const isLong = pos.side === 'long';
	const mark = market.mark_price;
	const above = o.triggerPrice > mark;
	const wantAbove = (o.type === 'take_profit') === isLong;
	if (above !== wantAbove) {
		throw perpsError(400, 'trigger_wrong_side', `A ${o.type.replace('_', '-')} on a ${pos.side} must trigger ${wantAbove ? 'above' : 'below'} the mark ($${mark}).`, { mark_price: mark, side: pos.side });
	}
	const size = pos.size * (o.sizePercent / 100);
	const pnl = (isLong ? 1 : -1) * size * (o.triggerPrice - pos.entry_price);
	return {
		symbol: market.symbol,
		side: isLong ? 'short' : 'long',
		type: o.type,
		reduce_only: true,
		size: round(size, 10),
		size_percent: o.sizePercent,
		trigger_price: o.triggerPrice,
		mark_price: mark,
		entry_price: pos.entry_price,
		position: { side: pos.side, size: pos.size, entry_price: pos.entry_price, liquidation_price: pos.liquidation_price },
		direction: wantAbove ? 'greater_than' : 'less_than',
		expected_pnl_at_trigger_usd: round(pnl, 4),
		fee_usd: round(size * o.triggerPrice * (market.taker_fee_rate || 0), 6),
		market_max_leverage: market.max_leverage,
		risk_increasing: false,
		liquidation_price: pos.liquidation_price,
	};
}

export async function previewOrder({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null, ...input }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const o = parseOrderInput(input);
	if (!(venue.capabilities?.order_types || []).includes(o.type)) {
		throw perpsError(400, 'order_type_unsupported', `${venue.label} takes ${(venue.capabilities?.order_types || []).join(', ')} orders, not ${o.type}.`, { venue: venue.id, supported: venue.capabilities?.order_types || [] });
	}
	if (o.type === 'market' || o.type === 'limit') o.size = await resolveSize(venue, o, limits);
	if (o.type === 'limit' && !o.price) throw perpsError(400, 'price_required', 'A limit order needs price.');
	const acct = await accountFor({ agent, userId, venue, mode, reason: 'perps_preview' });
	const quote = await quoteFor({ venue, o, acct, limits });
	const g = guardState(agent.meta);
	const guard = checkPerpsOrder({ limits, quote, tradeKill: g.trade_kill_switch, walletFrozen: g.wallet_frozen, mode });
	const checks = [...guard.checks];
	let wallet = null;
	if (mode === 'live' && venue.execution === 'api_wallet') {
		const hasKey = Boolean(agent.meta?.hyperliquid?.api_wallet?.encrypted);
		wallet = { address: acct.authority, usdc: acct.equity_usd, sol: null };
		checks.push(
			{ id: 'no_trader_account', ok: acct.equity_usd > 0, label: acct.equity_usd > 0 ? `${venue.label} account holds $${acct.equity_usd.toFixed(2)}` : 'The linked account holds no collateral: fund it on the venue first' },
			{ id: 'api_wallet', ok: hasKey, label: hasKey ? 'Agent API wallet is registered' : 'No agent API wallet registered: link and approve one first' },
		);
	} else if (mode === 'live') {
		const owner = await walletFor(agent, userId, 'perps_preview');
		const balances = await getSolanaAddressBalances(owner, 'mainnet');
		wallet = { address: owner, usdc: balances.usdc, sol: balances.sol };
		checks.push(
			{ id: 'no_trader_account', ok: acct.registered, label: acct.registered ? 'Trader account exists' : 'No trader account yet: deposit collateral first, which opens it' },
			{ id: 'wallet_sol', ok: balances.sol != null && balances.sol >= MIN_SOL_FOR_FEES, label: balances.sol == null ? 'Could not read the wallet SOL balance' : `Wallet holds ${balances.sol.toFixed(4)} SOL for network fees` },
		);
	}
	const params = {
		symbol: quote.symbol, side: o.side, type: o.type, size: quote.size, price: o.price, trigger_price: o.triggerPrice,
		size_percent: o.sizePercent, reduce_only: o.type === 'take_profit' || o.type === 'stop_loss' ? true : o.reduceOnly,
		slippage_bps: o.type === 'market' ? (o.slippageBps ?? limits.max_slippage_bps) : null,
		leverage: o.leverage,
	};
	return storePreview({
		agent, userId, venue, mode, kind: 'order', action: 'perps.order', ttlMs: ORDER_PREVIEW_TTL_MS, params,
		quote: { ...quote, leverage_cap: guard.leverage_cap, max_margin_per_position_usd: limits.max_margin_per_position_usd, max_quote_move_bps: limits.max_quote_move_bps, wallet },
		checks,
	});
}

export async function executeOrder({ agentId, userId, previewId, confirm, idempotencyKey, req = null, source = 'owner' }) {
	const { agent, key } = await begin({ agentId, userId, previewId, confirm, idempotencyKey, what: 'order' });
	const { preview, venue, limits, mode } = await previewContext({ agent, userId, previewId, action: 'perps.order' });
	const p = preview.params;
	return onceByKey({ agent, userId, venue, mode, action: 'order', previewId: preview.id, key, source }, async () => {
		const acct = await accountFor({ agent, userId, venue, mode, reason: 'perps_order' });
		const o = {
			symbol: p.symbol, side: p.side, type: p.type, size: p.size, price: p.price, triggerPrice: p.trigger_price,
			sizePercent: p.size_percent, reduceOnly: p.reduce_only, slippageBps: p.slippage_bps, leverage: p.leverage ?? null,
		};
		const fresh = await quoteFor({ venue, o, acct, limits });
		const moved = o.type === 'take_profit' || o.type === 'stop_loss'
			? (Math.abs((fresh.position?.size || 0) - (preview.quote.position?.size || 0)) > 1e-12
				? { reason: 'quote_moved', detail: { field: 'position_size', preview: preview.quote.position?.size, now: fresh.position?.size } }
				: null)
			: quoteMoved(preview.quote, fresh, limits.max_quote_move_bps);
		if (moved) {
			throw perpsError(409, 'quote_moved', `The market moved past your ${limits.max_quote_move_bps} bps tolerance since the preview (${moved.detail.field}), so nothing was sent. Preview again to see the new numbers.`, moved.detail);
		}
		const g = guardState(agent.meta);
		const guard = checkPerpsOrder({ limits, quote: fresh, tradeKill: g.trade_kill_switch, walletFrozen: g.wallet_frozen, mode });
		if (guard.blocked) throwBlocked(guard.blocked, { leverage_cap: guard.leverage_cap });
		if (mode === 'live' && venue.execution === 'api_wallet' && !agent.meta?.hyperliquid?.api_wallet?.encrypted) throwBlocked({ id: 'api_wallet', label: 'No agent API wallet registered' });
		if (mode === 'live' && venue.execution !== 'api_wallet' && !acct.registered) throwBlocked({ id: 'no_trader_account', label: 'No trader account yet: deposit collateral first' });

		await consumeActionPreview(preview.id, { hint: HINT });
		try {
			const result = mode === 'paper'
				? await paperOrder({ agent, userId, venue, o, quote: fresh, previewId: preview.id })
				: await liveOrder({ agent, userId, venue, o, quote: fresh, previewId: preview.id, source });
			logAudit({ userId, action: mode === 'paper' ? 'perps.paper_order' : 'custody.perps_order', resourceId: agent.id, meta: { ...p, mode, signatures: result.signatures, source }, req });
			return result;
		} catch (err) {
			if (!err?.sent) await releaseActionPreview(preview.id).catch(() => {});
			logAudit({ userId, action: 'perps.order_failed', resourceId: agent.id, meta: { ...p, mode, code: err?.code || null, source }, req });
			throw err;
		}
	});
}

function orderSummary(o, quote) {
	if (o.type === 'take_profit' || o.type === 'stop_loss') {
		return `${o.type === 'take_profit' ? 'Take-profit' : 'Stop-loss'} on ${quote.symbol} at $${quote.trigger_price} (${o.sizePercent}% of the position)`;
	}
	const verb = o.reduceOnly ? 'Reduce' : o.side === 'long' ? 'Long' : 'Short';
	return `${verb} ${quote.size} ${quote.symbol} ${o.type === 'limit' ? `limit at $${quote.limit_price}` : `at about $${quote.entry_price}`}`;
}

async function paperOrder({ agent, userId, venue, o, quote, previewId }) {
	const now = Date.now();
	const mkts = await marketMap(venue);
	return mutatePaper(agent.id, userId, venue.id, (prev) => {
		let state = settleFunding(prev, mkts, now);
		const fills = [];
		const newOrders = [];
		const orderUpdates = [];
		let fill = null;
		let resting = false;
		if (o.type === 'take_profit' || o.type === 'stop_loss') {
			for (const existing of prev.orders) {
				if (existing.symbol === quote.symbol && existing.type === o.type && existing.status === 'open') orderUpdates.push({ id: existing.id, status: 'cancelled' });
			}
			const isLong = quote.position.side === 'long';
			const slip = o.type === 'stop_loss' ? 0.03 : 0;
			const execution = isLong ? quote.trigger_price * (1 - slip) : quote.trigger_price * (1 + slip);
			newOrders.push({ symbol: quote.symbol, type: o.type, side: quote.side, price: round(execution, 8), trigger_price: quote.trigger_price, direction: quote.direction, size_percent: o.sizePercent, reduce_only: true, preview_id: previewId });
			resting = true;
		} else {
			if (o.type === 'market' || quote.crosses_book) {
				const delta = o.side === 'long' ? quote.size : -quote.size;
				const out = applyFill(state, { symbol: quote.symbol, delta, price: quote.entry_price, feeUsd: quote.fee_usd, reason: 'order', previewId });
				state = out.state;
				fill = out.fill;
				fills.push(fill);
			} else {
				newOrders.push({ symbol: quote.symbol, type: 'limit', side: o.side, size: quote.size, price: quote.limit_price, reduce_only: o.reduceOnly, preview_id: previewId });
				resting = true;
			}
		}
		const acct = buildPaperAccount(state, mkts, now);
		const position = acct.positions.find((x) => x.symbol === quote.symbol) || null;
		return {
			state,
			fills,
			newOrders,
			orderUpdates,
			result: {
				ok: true,
				mode: 'paper',
				action: 'order',
				status: resting ? 'resting' : 'filled',
				symbol: quote.symbol,
				side: o.side,
				type: o.type,
				size: quote.size,
				fill,
				position,
				account: summarize(acct),
				signatures: [],
				summary: orderSummary(o, quote),
			},
		};
	});
}

async function liveOrder({ agent, userId, venue, o, quote, previewId, source }) {
	const owner = await venueRef(venue, agent, userId, 'perps_order');
	let instructions = null;
	let trigger = null;
	if (o.type === 'take_profit' || o.type === 'stop_loss') {
		trigger = await venue.buildConditional(owner, { symbol: quote.symbol, kind: o.type, triggerPrice: quote.trigger_price, position: quote.position, sizePercent: o.sizePercent });
		instructions = trigger.instructions;
	}
	const custodyId = await recordCustodyEvent({
		agentId: agent.id, userId, eventType: 'perps_order', category: 'perps', asset: venue.collateral.asset,
		usd: quote.notional_usd ?? null, status: 'pending', reason: `perps_${o.type}`, destination: `perps-venue:${venue.id}`,
		meta: { venue: venue.id, symbol: quote.symbol, side: o.side, type: o.type, size: quote.size, preview_id: previewId, source },
	});
	try {
		const landed = instructions
			? await landInstructions({ agentId: agent.id, userId, owner, instructions, maxUsdcOutAtomic: 0n, reason: 'perps_order', meta: { venue: venue.id, custody_event_id: custodyId } })
			: await landVenueOrder({ agent, userId, venue, ref: owner, quote, reason: 'perps_order', meta: { venue: venue.id, custody_event_id: custodyId } });
		await updateCustodyEvent(custodyId, { status: 'confirmed', signature: landed.signature, meta: { simulation: landed.simulation ?? null, venue_result: landed.venue_result ?? null } }).catch(() => {});
		const acct = await venue.getAccount(owner).catch(() => null);
		return {
			ok: true,
			mode: 'live',
			action: 'order',
			status: landed.venue_result ? landed.venue_result.state : o.type === 'market' ? 'submitted' : 'resting',
			venue_result: landed.venue_result ?? null,
			symbol: quote.symbol,
			side: o.side,
			type: o.type,
			size: quote.size,
			trigger: trigger ? { trigger_price: trigger.trigger_price, execution_price: trigger.execution_price } : null,
			signature: landed.signature,
			explorer: landed.explorer,
			signatures: landed.signature ? [landed.signature] : [],
			position: acct?.positions.find((x) => x.symbol === quote.symbol) || null,
			account: acct ? summarize(acct) : null,
			summary: orderSummary(o, quote),
		};
	} catch (err) {
		await updateCustodyEvent(custodyId, { status: 'failed', signature: err?.signature ?? null }).catch(() => {});
		throw err;
	}
}

// ── cancel ───────────────────────────────────────────────────────────────────

function findCancellable(acct, orderId, kind) {
	const id = String(orderId || '');
	if (!id) throw perpsError(400, 'order_id_required', 'Pass order_id. perps_positions lists open orders and triggers with their ids.');
	const orders = (!kind || kind === 'limit') ? acct.orders.filter((x) => x.id === id).map((x) => ({ ...x, kind: 'limit' })) : [];
	const triggers = (!kind || kind === 'take_profit' || kind === 'stop_loss')
		? acct.conditionals.filter((x) => x.id === id && (!kind || x.kind === kind) && x.cancellable !== false)
		: [];
	const found = [...orders, ...triggers];
	if (!found.length) throw perpsError(404, 'order_not_found', 'No open order or trigger with that id on this agent.');
	if (found.length > 1) throw perpsError(400, 'order_ambiguous', 'That id matches more than one open order; pass kind (limit, take_profit or stop_loss) too.');
	return found[0];
}

export async function previewCancel({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null, orderId, kind = null }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	if (mode === 'live') requireCapability(venue, 'cancel', 'cancelling orders');
	const acct = await accountFor({ agent, userId, venue, mode });
	const target = findCancellable(acct, orderId, kind);
	return storePreview({
		agent, userId, venue, mode, kind: 'cancel', action: 'perps.cancel', ttlMs: FUNDS_PREVIEW_TTL_MS,
		params: { order_id: target.id, kind: target.kind, symbol: target.symbol },
		quote: { order: target },
		checks: [{ id: 'open', ok: true, label: 'The order is still open' }],
	});
}

export async function executeCancel({ agentId, userId, previewId, confirm, idempotencyKey, req = null, source = 'owner' }) {
	const { agent, key } = await begin({ agentId, userId, previewId, confirm, idempotencyKey, what: 'cancel' });
	const { preview, venue, mode } = await previewContext({ agent, userId, previewId, action: 'perps.cancel' });
	const p = preview.params;
	return onceByKey({ agent, userId, venue, mode, action: 'cancel', previewId: preview.id, key, source }, async () => {
		const acct = await accountFor({ agent, userId, venue, mode });
		const target = findCancellable(acct, p.order_id, p.kind);
		await consumeActionPreview(preview.id, { hint: HINT });
		try {
			let signatures = [];
			if (mode === 'paper') {
				await mutatePaper(agent.id, userId, venue.id, (s) => ({
					state: { ...s, orders: s.orders.filter((x) => String(x.id) !== target.id) },
					orderUpdates: [{ id: Number(target.id), status: 'cancelled' }],
					result: true,
				}));
			} else {
				const owner = await venueRef(venue, agent, userId, 'perps_cancel');
				const landed = await landCancel({ agent, userId, venue, owner, targets: [target], reason: 'perps_cancel' });
				signatures = landed.signature ? [landed.signature] : [];
			}
			logAudit({ userId, action: mode === 'paper' ? 'perps.paper_cancel' : 'custody.perps_cancel', resourceId: agent.id, meta: { ...p, signatures, source }, req });
			return { ok: true, mode, action: 'cancel', order: target, signatures, signature: signatures[0] || null, explorer: signatures[0] ? explorer(signatures[0]) : null, summary: `Cancelled ${target.kind.replace('_', '-')} ${target.id} on ${target.symbol}` };
		} catch (err) {
			if (!err?.sent) await releaseActionPreview(preview.id).catch(() => {});
			throw err;
		}
	});
}

/** Cancel one or more resting orders on whatever rail the venue uses. */
async function landCancel({ agent, userId, venue, owner, targets, reason }) {
	requireCapability(venue, 'cancel', 'cancelling orders');
	if (venue.execution === 'api_wallet') {
		const action = { type: 'cancel', cancels: [] };
		for (const t of targets) action.cancels.push(...(await venue.buildCancel(owner, { symbol: t.symbol, orderId: t.id })).cancels);
		return landApiWallet({ agent, venue, action });
	}
	const ixs = (await Promise.all(targets.map((t) => cancelInstructions(venue, owner, t)))).flat();
	return landInstructions({ agentId: agent.id, userId, owner, instructions: ixs, maxUsdcOutAtomic: 0n, reason, meta: { venue: venue.id } });
}

async function cancelInstructions(venue, owner, target) {
	if (target.kind === 'limit') return venue.buildCancel(owner, { symbol: target.symbol, orderId: target.id, priceTicks: target.price_ticks });
	// A trigger that closes a long sells; its direction follows from kind and side.
	const closesLong = target.side === 'sell' || target.side === 'short';
	const greater = (target.kind === 'take_profit') === closesLong;
	return venue.buildCancelConditional(owner, { symbol: target.symbol, conditionalId: target.id, direction: target.direction || (greater ? 'greater_than' : 'less_than') });
}

// ── kill switch: flatten everything ──────────────────────────────────────────

export async function previewFlatten({ agentId, userId, venueId = DEFAULT_VENUE, mode: requested = null }) {
	const venue = getVenue(venueId);
	const agent = await loadOwnedAgent(agentId, userId);
	const limits = getPerpsLimits(agent.meta);
	const mode = resolveMode(limits, requested);
	const acct = await accountFor({ agent, userId, venue, mode });
	const slippageBps = Math.max(limits.max_slippage_bps, 300);
	const closes = [];
	for (const pos of acct.positions) {
		try {
			const q = await venue.quoteOrder({ symbol: pos.symbol, side: pos.side === 'long' ? 'short' : 'long', size: pos.size, type: 'market', reduceOnly: true, slippageBps, account: acct });
			closes.push({ symbol: pos.symbol, side: pos.side, size: pos.size, expected_exit_price: q.entry_price, expected_pnl_usd: round((pos.side === 'long' ? 1 : -1) * pos.size * (q.entry_price - pos.entry_price) - q.fee_usd, 4), fee_usd: q.fee_usd });
		} catch (err) {
			closes.push({ symbol: pos.symbol, side: pos.side, size: pos.size, error: describeError(err)?.message || 'Could not quote this close right now.' });
		}
	}
	const quote = {
		halts_trading: true,
		positions_to_close: closes,
		orders_to_cancel: acct.orders.length,
		triggers_to_cancel: acct.conditionals.filter((c) => c.cancellable !== false).length,
		slippage_bps: slippageBps,
		expected_total_pnl_usd: round(closes.reduce((s, c) => s + (c.expected_pnl_usd || 0), 0), 4),
	};
	return storePreview({
		agent, userId, venue, mode, kind: 'flatten', action: 'perps.flatten', ttlMs: ORDER_PREVIEW_TTL_MS,
		params: { slippage_bps: slippageBps },
		quote,
		checks: [{ id: 'kill_switch', ok: true, label: 'Turns the perps kill switch on: only reduce-only orders run until you resume' }],
	});
}

export async function executeFlatten({ agentId, userId, previewId, confirm, idempotencyKey, req = null, source = 'owner' }) {
	const { agent, key } = await begin({ agentId, userId, previewId, confirm, idempotencyKey, what: 'flatten' });
	const preview = await loadActionPreview(previewId, { userId, agentId: agent.id, action: 'perps.flatten', hint: HINT });
	const venue = getVenue(preview.params.venue);
	const mode = preview.params.mode;
	if (mode === 'live') await requireLiveAgreement(userId);
	return onceByKey({ agent, userId, venue, mode, action: 'flatten', previewId: preview.id, key, source }, async () => {
		await consumeActionPreview(preview.id, { hint: HINT });
		// The halt lands first and stays on whatever happens next.
		await setPerpsLimits(agent.id, userId, { halted: true }, { req, reason: 'perps_kill_switch' });
		const slippageBps = preview.params.slippage_bps;
		const result = mode === 'paper'
			? await paperFlatten({ agent, userId, venue, slippageBps })
			: await liveFlatten({ agent, userId, venue, slippageBps });
		logAudit({ userId, action: mode === 'paper' ? 'perps.paper_flatten' : 'custody.perps_flatten', resourceId: agent.id, meta: { steps: result.steps.map((s) => ({ step: s.step, ok: s.ok })), source }, req });
		return result;
	});
}

async function paperFlatten({ agent, userId, venue, slippageBps }) {
	const acct = await syncPaper(agent.id, userId, venue);
	const quotes = new Map();
	for (const pos of acct.positions) {
		quotes.set(pos.symbol, await venue.quoteOrder({ symbol: pos.symbol, side: pos.side === 'long' ? 'short' : 'long', size: pos.size, type: 'market', reduceOnly: true, slippageBps, account: acct }));
	}
	const mkts = await marketMap(venue);
	return mutatePaper(agent.id, userId, venue.id, (prev) => {
		const now = Date.now();
		let state = settleFunding(prev, mkts, now);
		const fills = [];
		const steps = [];
		const orderUpdates = prev.orders.filter((x) => x.status === 'open').map((x) => ({ id: x.id, status: 'cancelled' }));
		steps.push({ step: 'cancel_orders', ok: true, count: orderUpdates.length });
		for (const [symbol, p] of prev.positions) {
			if (Math.abs(p.signed_size) < 1e-12) continue;
			const q = quotes.get(symbol);
			const m = mkts.get(symbol);
			const price = q?.entry_price ?? m?.mark_price ?? p.entry_price;
			const size = Math.abs(p.signed_size);
			const out = applyFill(state, { symbol, delta: -p.signed_size, price, feeUsd: q?.fee_usd ?? size * price * (m?.taker_fee_rate || 0), reason: 'flatten' });
			state = out.state;
			fills.push(out.fill);
			steps.push({ step: `close_${symbol}`, ok: true, symbol, fill: out.fill });
		}
		state = { ...state, orders: [] };
		const after = buildPaperAccount(state, mkts, now);
		return { state, fills, orderUpdates, result: { ok: true, mode: 'paper', action: 'flatten', halted: true, steps, account: summarize(after), signatures: [], summary: `Flattened ${fills.length} paper position(s) and halted perps trading` } };
	});
}

async function liveFlatten({ agent, userId, venue, slippageBps }) {
	const owner = await venueRef(venue, agent, userId, 'perps_flatten');
	const steps = [];
	const signatures = [];
	let acct = await venue.getAccount(owner);
	const cancellable = [
		...acct.orders.map((x) => ({ ...x, kind: 'limit' })),
		...acct.conditionals.filter((c) => c.cancellable !== false),
	];
	// Cancels go in small batches so each transaction stays well under size limits.
	for (let i = 0; i < cancellable.length; i += 4) {
		const batch = cancellable.slice(i, i + 4);
		try {
			const landed = await landCancel({ agent, userId, venue, owner, targets: batch, reason: 'perps_flatten' });
			if (landed.signature) signatures.push(landed.signature);
			steps.push({ step: 'cancel_orders', ok: true, count: batch.length, signature: landed.signature, explorer: landed.explorer });
		} catch (err) {
			if (err?.signature) signatures.push(err.signature);
			steps.push({ step: 'cancel_orders', ok: false, count: batch.length, error: describeError(err)?.message || String(err?.message || err) });
		}
	}
	if (cancellable.length) acct = await venue.getAccount(owner);
	for (const pos of acct.positions) {
		try {
			const q = await venue.quoteOrder({ symbol: pos.symbol, side: pos.side === 'long' ? 'short' : 'long', size: pos.size, type: 'market', reduceOnly: true, slippageBps, account: acct });
			const landed = await landVenueOrder({ agent, userId, venue, ref: owner, quote: q, reason: 'perps_flatten', meta: { venue: venue.id, symbol: pos.symbol } });
			if (landed.signature) signatures.push(landed.signature);
			steps.push({ step: `close_${pos.symbol}`, ok: true, symbol: pos.symbol, size: pos.size, signature: landed.signature, explorer: landed.explorer });
		} catch (err) {
			if (err?.signature) signatures.push(err.signature);
			steps.push({ step: `close_${pos.symbol}`, ok: false, symbol: pos.symbol, error: describeError(err)?.message || String(err?.message || err) });
		}
	}
	await recordCustodyEvent({ agentId: agent.id, userId, eventType: 'perps_flatten', category: 'perps', status: steps.every((s) => s.ok) ? 'confirmed' : 'failed', reason: 'perps_kill_switch', meta: { venue: venue.id, steps, signatures } }).catch(() => {});
	const after = await venue.getAccount(owner).catch(() => null);
	const failed = steps.filter((s) => !s.ok);
	return {
		ok: failed.length === 0,
		mode: 'live',
		action: 'flatten',
		halted: true,
		steps,
		signatures,
		account: after ? summarize(after) : null,
		summary: failed.length ? `Halted perps trading; ${failed.length} step(s) failed and need a retry` : `Flattened ${acct.positions.length} position(s) and halted perps trading`,
	};
}

// ── preview storage ──────────────────────────────────────────────────────────

async function storePreview({ agent, userId, venue, mode, kind, action, ttlMs, params, quote, checks }) {
	const blocked = checks.filter((c) => !c.ok).map((c) => c.id);
	const fullParams = { ...params, venue: venue.id, mode };
	const { preview_id, expires_at } = await createActionPreview({ userId, agentId: agent.id, action, prefix: PREFIX, params: fullParams, quote, ttlMs });
	return {
		preview_id,
		expires_at,
		kind,
		mode,
		venue: venue.id,
		chain: 'solana',
		agent: { id: agent.id, name: agent.name },
		...quote,
		checks,
		blocked_by: blocked,
		executable: blocked.length === 0,
		confirm_with: { confirm_trade: true, preview_id },
	};
}

export { loadPaperState };