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.

12.0 KB
Raw Blame
// Per-agent perps risk policy, stored at agent_identities.meta.perps_limits.
//
// Every agent gets a mandatory leverage cap and a per-position margin cap with
// conservative defaults, so a fresh agent can paper trade at once but cannot
// put real collateral to work until its owner turns live mode on:
//
//   live_enabled                 false: orders run on the paper ledger at live prices
//   max_leverage                 account leverage (notional over equity) after any order
//   max_margin_per_position_usd  initial margin any one position may hold
//   max_slippage_bps             ceiling on the slippage a market order may accept
//   max_quote_move_bps           how far entry or liquidation may drift between
//                                preview and execute before the execute refuses
//   max_notional_usd             notional any one position may hold after an order
//   min_liquidation_distance_pct how far the venue's liquidation price must stay
//                                from the mark after an order that adds risk
//   mcp_enabled                  false: MCP callers cannot see or call the perps
//                                tools for this agent until the owner opts in
//   halted                       set by the kill switch: risk-increasing orders
//                                are refused until the owner resumes trading
//   alert_*                      owner thresholds the tracker and the alert cron
//                                check; null turns that alert off
//
// These sit on top of the wallet-wide spend policy (freeze, per-transaction and
// daily USD caps, allowlist), which still applies in full to every deposit.

import { sql } from '../db.js';
import { logAudit } from '../audit.js';
import { recordCustodyEvent } from '../agent-trade-guards.js';
import { perpsError } from './errors.js';

export const PERPS_LIMIT_DEFAULTS = Object.freeze({
	live_enabled: false,
	max_leverage: 2,
	max_margin_per_position_usd: 25,
	max_slippage_bps: 100,
	max_quote_move_bps: 50,
	max_notional_usd: 500,
	min_liquidation_distance_pct: 10,
	mcp_enabled: false,
	halted: false,
	alert_liquidation_distance_pct: 15,
	alert_loss_usd: null,
	alert_gain_usd: null,
	alert_funding_usd: null,
});

// Hard ceilings no owner setting can exceed.
export const PERPS_LIMIT_CEILINGS = Object.freeze({
	max_leverage: 20,
	max_margin_per_position_usd: 100_000,
	max_slippage_bps: 1_000,
	max_quote_move_bps: 500,
	max_notional_usd: 10_000_000,
});

function clamp(v, def, min, max) {
	if (v === undefined || v === '') return def;
	const n = Number(v);
	if (!Number.isFinite(n) || n < min) return def;
	return Math.min(max, n);
}

function optional(v, min, max) {
	if (v === null || v === undefined || v === '') return null;
	const n = Number(v);
	if (!Number.isFinite(n) || n < min) return null;
	return Math.min(max, n);
}

/** Coerce arbitrary input into clean, bounded perps limits. */
export function normalizePerpsLimits(raw) {
	const r = raw && typeof raw === 'object' ? raw : {};
	const d = PERPS_LIMIT_DEFAULTS;
	const c = PERPS_LIMIT_CEILINGS;
	return {
		live_enabled: r.live_enabled === true,
		max_leverage: clamp(r.max_leverage, d.max_leverage, 1, c.max_leverage),
		max_margin_per_position_usd: clamp(r.max_margin_per_position_usd, d.max_margin_per_position_usd, 1, c.max_margin_per_position_usd),
		max_slippage_bps: Math.round(clamp(r.max_slippage_bps, d.max_slippage_bps, 1, c.max_slippage_bps)),
		max_quote_move_bps: Math.round(clamp(r.max_quote_move_bps, d.max_quote_move_bps, 1, c.max_quote_move_bps)),
		max_notional_usd: clamp(r.max_notional_usd, d.max_notional_usd, 1, c.max_notional_usd),
		min_liquidation_distance_pct: clamp(r.min_liquidation_distance_pct, d.min_liquidation_distance_pct, 0, 90),
		mcp_enabled: r.mcp_enabled === true,
		halted: r.halted === true,
		alert_liquidation_distance_pct: 'alert_liquidation_distance_pct' in r
			? optional(r.alert_liquidation_distance_pct, 0.5, 90)
			: d.alert_liquidation_distance_pct,
		alert_loss_usd: optional(r.alert_loss_usd, 0.01, 10_000_000),
		alert_gain_usd: optional(r.alert_gain_usd, 0.01, 10_000_000),
		alert_funding_usd: optional(r.alert_funding_usd, 0.01, 10_000_000),
		updated_at: typeof r.updated_at === 'string' ? r.updated_at : null,
	};
}

/** Read the effective perps limits off an agent's meta blob. */
export function getPerpsLimits(meta) {
	return normalizePerpsLimits(meta?.perps_limits);
}

const PATCHABLE = Object.keys(PERPS_LIMIT_DEFAULTS);

/**
 * Pure: the keys a patch would loosen. Turning live on, resuming after the kill
 * switch and raising a cap are the owner's to do from a signed-in session; an
 * API key, an OAuth client or an MCP caller may only tighten. Alert thresholds
 * are not risk limits, so any caller may set them.
 */
export function loosenedPerpsKeys(prev, patch) {
	const before = normalizePerpsLimits(prev);
	const next = normalizePerpsLimits({ ...before, ...(patch && typeof patch === 'object' ? patch : {}) });
	const out = [];
	if (next.live_enabled && !before.live_enabled) out.push('live_enabled');
	if (next.mcp_enabled && !before.mcp_enabled) out.push('mcp_enabled');
	if (!next.halted && before.halted) out.push('halted');
	for (const k of ['max_leverage', 'max_margin_per_position_usd', 'max_slippage_bps', 'max_quote_move_bps', 'max_notional_usd']) {
		if (next[k] > before[k]) out.push(k);
	}
	if (next.min_liquidation_distance_pct < before.min_liquidation_distance_pct) out.push('min_liquidation_distance_pct');
	return out;
}

/**
 * Persist a perps-limit patch (owner-only). Keys absent from `patch` keep their
 * value. Audited in the custody trail and the platform audit log.
 */
export async function setPerpsLimits(agentId, userId, patch, { req = null, reason = 'perps_limits_updated' } = {}) {
	const [row] = await sql`
		SELECT id, user_id, 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.");

	const prev = getPerpsLimits(row.meta);
	const p = patch && typeof patch === 'object' ? patch : {};
	const merged = { ...prev };
	for (const k of PATCHABLE) if (k in p) merged[k] = p[k];
	const next = normalizePerpsLimits(merged);
	next.updated_at = new Date().toISOString();

	await sql`
		UPDATE agent_identities
		SET meta = jsonb_set(coalesce(meta, '{}'::jsonb), '{perps_limits}', ${JSON.stringify(next)}::jsonb)
		WHERE id = ${agentId}
	`;

	await recordCustodyEvent({
		agentId,
		userId,
		eventType: 'limit_change',
		reason,
		meta: { prev, next },
	}).catch((e) => console.warn('[perps] limit_change record failed', e?.message));
	logAudit({ userId, action: 'custody.perps_limit_change', resourceId: agentId, meta: { prev, next }, req });

	return next;
}

/**
 * Pure: is this order allowed under the agent's perps limits? `quote` is the
 * venue quote (or the paper equivalent). Returns the checks the preview shows
 * and the first blocking one.
 *
 * @param {object} o
 * @param {object} o.limits          normalized perps limits
 * @param {object} o.quote           quoteOrder output
 * @param {boolean} o.tradeKill      the agent-wide trade kill switch
 * @param {boolean} o.walletFrozen   the wallet-wide spend freeze
 * @param {'paper'|'live'} o.mode
 */
export function checkPerpsOrder({ limits, quote, tradeKill = false, walletFrozen = false, mode }) {
	const lim = normalizePerpsLimits(limits);
	const increasing = quote.risk_increasing === true;
	const leverage = quote.account_leverage_after;
	const marketMax = Number(quote.market_max_leverage) || lim.max_leverage;
	const leverageCap = Math.min(lim.max_leverage, marketMax);
	const positionMargin = quote.position_after?.notional_usd != null && marketMax > 0
		? quote.position_after.notional_usd / marketMax
		: 0;
	// The leverage the owner allows means each position may tie up at most its
	// notional over that leverage in margin, so measure the cap the same way.
	const marginAtCap = quote.position_after?.notional_usd != null ? quote.position_after.notional_usd / leverageCap : 0;

	const checks = [
		{
			id: 'mode',
			ok: mode === 'paper' || lim.live_enabled,
			label: mode === 'paper' ? 'Paper mode: fills at live prices, no funds move' : lim.live_enabled ? 'Live trading is on for this agent' : 'Live trading is off for this agent',
		},
		{
			id: 'halted',
			ok: !increasing || !lim.halted,
			label: lim.halted ? (increasing ? 'The perps kill switch is on: only reduce-only orders are allowed' : 'Kill switch on, but this order only reduces risk') : 'The perps kill switch is off',
		},
		{
			id: 'trade_kill_switch',
			ok: !increasing || !tradeKill,
			label: tradeKill ? 'The agent-wide trade kill switch is on' : 'The agent-wide trade kill switch is off',
		},
		{
			id: 'wallet_frozen',
			ok: !increasing || !walletFrozen,
			label: walletFrozen ? 'The wallet is frozen' : 'The wallet is not frozen',
		},
		{
			id: 'leverage',
			ok: !increasing || (leverage != null && leverage <= leverageCap + 1e-9),
			label: leverage == null
				? 'No equity to back the position: deposit collateral first'
				: `Account leverage after the order: ${leverage.toFixed(2)}x of ${leverageCap.toFixed(2)}x allowed`,
		},
		{
			id: 'position_margin',
			ok: !increasing || marginAtCap <= lim.max_margin_per_position_usd + 1e-9,
			label: `Margin this position needs at your leverage cap: $${marginAtCap.toFixed(2)} of $${lim.max_margin_per_position_usd.toFixed(2)} allowed`,
		},
		{
			id: 'max_notional',
			ok: !increasing || (quote.position_after?.notional_usd ?? 0) <= lim.max_notional_usd + 1e-9,
			label: `Position notional after the order: $${Number(quote.position_after?.notional_usd || 0).toFixed(2)} of $${lim.max_notional_usd.toFixed(2)} allowed`,
		},
		{
			id: 'liquidation_distance',
			ok: !increasing || quote.liquidation_distance_pct == null || quote.liquidation_distance_pct >= lim.min_liquidation_distance_pct - 1e-9,
			label: quote.liquidation_distance_pct == null
				? 'No liquidation price on this position'
				: `Liquidation sits ${Number(quote.liquidation_distance_pct).toFixed(1)}% from the mark, at least ${lim.min_liquidation_distance_pct}% required`,
		},
		{
			id: 'free_collateral',
			ok: !increasing || (quote.free_collateral_after_usd != null && quote.free_collateral_after_usd >= 0),
			label: `Free collateral after the order: $${Number(quote.free_collateral_after_usd || 0).toFixed(2)}`,
		},
	];
	if (quote.slippage_bps != null) {
		checks.push({
			id: 'slippage',
			ok: quote.slippage_bps <= lim.max_slippage_bps,
			label: `Slippage allowed: ${quote.slippage_bps} bps of ${lim.max_slippage_bps} bps`,
		});
	}
	const blocked = checks.find((c) => !c.ok) || null;
	return { checks, blocked, leverage_cap: leverageCap, position_margin_usd: positionMargin };
}

/**
 * Pure: did the market move between preview and execute by more than the owner
 * tolerates? Compares entry and liquidation in basis points of the preview.
 * @returns {null | { reason: string, detail: object }}
 */
export function quoteMoved(previewQuote, freshQuote, toleranceBps) {
	const bps = (a, b) => (a && b ? (Math.abs(b - a) / a) * 10_000 : 0);
	const entryMove = bps(previewQuote.entry_price, freshQuote.entry_price);
	if (entryMove > toleranceBps) {
		return { reason: 'quote_moved', detail: { field: 'entry_price', preview: previewQuote.entry_price, now: freshQuote.entry_price, moved_bps: Math.round(entryMove), tolerance_bps: toleranceBps } };
	}
	const pl = previewQuote.liquidation_price;
	const fl = freshQuote.liquidation_price;
	if ((pl == null) !== (fl == null)) {
		return { reason: 'quote_moved', detail: { field: 'liquidation_price', preview: pl, now: fl, tolerance_bps: toleranceBps } };
	}
	const liqMove = bps(pl, fl);
	if (liqMove > toleranceBps) {
		return { reason: 'quote_moved', detail: { field: 'liquidation_price', preview: pl, now: fl, moved_bps: Math.round(liqMove), tolerance_bps: toleranceBps } };
	}
	const sizeMove = Math.abs((freshQuote.size || 0) - (previewQuote.size || 0));
	if (sizeMove > 1e-12) {
		return { reason: 'quote_moved', detail: { field: 'size', preview: previewQuote.size, now: freshQuote.size } };
	}
	return null;
}