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.

feat(perps): give every agent a paper perps ledger and a per-agent risk policy so live collateral stays off until the owner turns it on

nirholasb3f40fda661b
diff --git a/api/_lib/perps/limits.js b/api/_lib/perps/limits.js
new file mode 100644
index 000000000..87f3d2022
--- /dev/null
+++ b/api/_lib/perps/limits.js
@@ -0,0 +1,227 @@
+// 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
+// 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,
+ 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,
+});
+
+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)),
+ 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);
+
+/**
+ * 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: '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;
+}
diff --git a/api/_lib/perps/paper.js b/api/_lib/perps/paper.js
new file mode 100644
index 000000000..7ef6dd18d
--- /dev/null
+++ b/api/_lib/perps/paper.js
@@ -0,0 +1,420 @@
+// Paper perps: the agent trades against the venue's live order book and marks,
+// but positions, collateral, fills and funding live in this platform's own
+// ledger (perps_paper_* tables) and no transaction is ever built or signed.
+//
+// Paper mode exists so an owner can run the whole flow (deposit, preview,
+// execute, take-profit, stop-loss, flatten) on a fresh agent before turning
+// live mode on, and so tests never open a real position.
+//
+// Fidelity rules, so a paper result means something:
+// - market orders fill at the price the venue's own quote walks off the live
+// book (the same quoteOrder the live path uses), taker fee included
+// - resting limit orders fill at their limit once the live book crosses them
+// - take-profit and stop-loss triggers fire on the live mark price; a stop
+// fills at its execution price (trigger plus the stop slippage)
+// - funding accrues continuously at the market's live hourly rate: a long
+// pays a positive rate, a short receives it
+// - an account whose equity falls under maintenance margin is liquidated at
+// the mark, exactly where the venue would close it
+//
+// Concurrency: every mutation commits under an optimistic version on the
+// paper account row, with each statement in the batch guarded by a one-time
+// op token, so two concurrent fills can never interleave. A losing writer
+// re-reads and recomputes.
+
+import { randomUUID } from 'node:crypto';
+import { sql } from '../db.js';
+import { perpsError } from './errors.js';
+
+export const PAPER_MAX_COLLATERAL_USD = 1_000_000;
+const EPS = 1e-12;
+
+const round = (n, dp = 6) => (n == null || !Number.isFinite(n) ? null : Math.round(n * 10 ** dp) / 10 ** dp);
+const num = (v) => (v == null ? null : Number(v));
+
+// ── pure math ────────────────────────────────────────────────────────────────
+
+/**
+ * Liquidation price for one position in a cross-margin account, holding every
+ * other position's PnL and maintenance margin constant. The closed form the
+ * venue SDK uses: equity(p) = maintenance(p) solved for p.
+ *
+ * @returns {number|null} null when the position cannot be liquidated by price alone
+ */
+export function paperLiquidationPrice({ signedSize, entry, collateralUsd, mmr, otherPnlUsd = 0, otherMaintenanceUsd = 0 }) {
+ if (Math.abs(signedSize) < EPS || !(mmr > 0)) return null;
+ const numerator = collateralUsd + otherPnlUsd - otherMaintenanceUsd - entry * signedSize;
+ const denominator = Math.abs(signedSize) * mmr - signedSize;
+ if (Math.abs(denominator) < EPS) return null;
+ const price = numerator / denominator;
+ return Number.isFinite(price) && price > 0 ? price : null;
+}
+
+/**
+ * Funding a position owes for the time since `fromMs`, in USD. Positive means
+ * the position pays. `hourlyPct` is the market's live hourly rate in percent.
+ */
+export function fundingOwed({ signedSize, mark, hourlyPct, fromMs, toMs }) {
+ if (!signedSize || !mark || !Number.isFinite(hourlyPct) || !(toMs > fromMs)) return 0;
+ const hours = (toMs - fromMs) / 3_600_000;
+ return signedSize * mark * (hourlyPct / 100) * hours;
+}
+
+/** Has the live book crossed a resting limit? A buy fills when the ask comes down to it. */
+export function limitCrossed(order, book) {
+ if (order.side === 'long') return book.best_ask != null && book.best_ask <= order.price + EPS;
+ return book.best_bid != null && book.best_bid >= order.price - EPS;
+}
+
+/** Has the mark reached a trigger? Direction comes from the position the trigger protects. */
+export function triggerHit(order, mark) {
+ if (mark == null) return false;
+ return order.direction === 'greater_than' ? mark >= order.trigger_price - EPS : mark <= order.trigger_price + EPS;
+}
+
+/**
+ * Pure: the venue-shaped account for a paper state at the given marks. Same
+ * fields as a venue's getAccount, so quoteOrder, the guards, the tracker and
+ * the page treat both modes identically.
+ *
+ * @param {object} state loadPaperState output
+ * @param {Map<string, object>} markets symbol -> normalized market (mark, funding, margin rates)
+ * @param {number} nowMs
+ */
+export function buildPaperAccount(state, markets, nowMs = Date.now()) {
+ const rows = [...state.positions.values()].filter((p) => Math.abs(p.signed_size) > EPS);
+ const legs = rows.map((p) => {
+ const m = markets.get(p.symbol) || {};
+ const mark = m.mark_price ?? p.entry_price;
+ const size = Math.abs(p.signed_size);
+ const notional = size * mark;
+ const pending = fundingOwed({ signedSize: p.signed_size, mark, hourlyPct: m.funding_rate_hourly_pct, fromMs: p.funding_at, toMs: nowMs });
+ return {
+ p,
+ m,
+ mark,
+ size,
+ notional,
+ upnl: p.signed_size * (mark - p.entry_price),
+ im: notional * (m.initial_margin_rate ?? 1),
+ mm: notional * (m.maintenance_margin_rate ?? 0.5),
+ pending,
+ };
+ });
+ const totalPnl = legs.reduce((s, l) => s + l.upnl, 0);
+ const totalMm = legs.reduce((s, l) => s + l.mm, 0);
+ const totalIm = legs.reduce((s, l) => s + l.im, 0);
+ const totalPending = legs.reduce((s, l) => s + l.pending, 0);
+ const collateral = state.collateral_usd - totalPending;
+ const equity = collateral + totalPnl;
+ const notional = legs.reduce((s, l) => s + l.notional, 0);
+
+ const positions = legs
+ .map((l) => {
+ const liq = paperLiquidationPrice({
+ signedSize: l.p.signed_size,
+ entry: l.p.entry_price,
+ collateralUsd: collateral,
+ mmr: l.m.maintenance_margin_rate,
+ otherPnlUsd: totalPnl - l.upnl,
+ otherMaintenanceUsd: totalMm - l.mm,
+ });
+ const tp = state.orders.find((o) => o.symbol === l.p.symbol && o.type === 'take_profit' && o.status === 'open');
+ const sl = state.orders.find((o) => o.symbol === l.p.symbol && o.type === 'stop_loss' && o.status === 'open');
+ return {
+ symbol: l.p.symbol,
+ side: l.p.signed_size > 0 ? 'long' : 'short',
+ size: round(l.size, 10),
+ signed_size: l.p.signed_size,
+ entry_price: round(l.p.entry_price, 8),
+ mark_price: l.mark,
+ notional_usd: round(l.notional, 2),
+ unrealized_pnl_usd: round(l.upnl, 4),
+ liquidation_price: liq ? round(liq, 6) : null,
+ liquidation_distance_pct: liq && l.mark ? round((Math.abs(l.mark - liq) / l.mark) * 100, 2) : null,
+ initial_margin_usd: round(l.im, 4),
+ maintenance_margin_usd: round(l.mm, 4),
+ funding_accrued_usd: round(l.p.funding_paid_usd + l.pending, 4),
+ unsettled_funding_usd: round(l.pending, 4),
+ take_profit_price: tp?.trigger_price ?? null,
+ stop_loss_price: sl?.trigger_price ?? null,
+ opened_at: l.p.opened_at,
+ };
+ })
+ .sort((a, b) => b.notional_usd - a.notional_usd);
+
+ const open = state.orders.filter((o) => o.status === 'open');
+ return {
+ registered: true,
+ authority: null,
+ trader_account: null,
+ collateral_usd: round(collateral, 6),
+ equity_usd: round(equity, 6),
+ withdrawable_usd: round(Math.max(0, Math.min(collateral, equity - totalIm)), 6),
+ unrealized_pnl_usd: round(totalPnl, 6),
+ initial_margin_usd: round(totalIm, 6),
+ maintenance_margin_usd: round(totalMm, 6),
+ funding_owed_usd: round(totalPending, 6),
+ notional_usd: round(notional, 2),
+ account_leverage: equity > 0 ? round(notional / equity, 3) : 0,
+ risk_state: legs.length === 0 ? (collateral > 0 ? 'healthy' : 'zeroCollateralNoPositions') : equity < totalMm ? 'liquidatable' : equity < totalIm ? 'cancellable' : 'healthy',
+ risk_tier: null,
+ positions,
+ orders: open
+ .filter((o) => o.type === 'limit')
+ .map((o) => ({ id: String(o.id), symbol: o.symbol, side: o.side, price: o.price, price_ticks: null, size_remaining: o.size, reduce_only: o.reduce_only, type: 'limit', status: 'open' })),
+ conditionals: open
+ .filter((o) => o.type === 'take_profit' || o.type === 'stop_loss')
+ .map((o) => ({ id: String(o.id), symbol: o.symbol, kind: o.type, trigger_price: o.trigger_price, execution_price: o.price, side: o.side, status: 'open', cancellable: true, direction: o.direction })),
+ paper: {
+ realized_pnl_usd: round(state.realized_pnl_usd, 6),
+ fees_paid_usd: round(state.fees_paid_usd, 6),
+ funding_paid_usd: round(state.funding_paid_usd + totalPending, 6),
+ deposited_usd: round(state.deposited_usd, 6),
+ withdrawn_usd: round(state.withdrawn_usd, 6),
+ },
+ };
+}
+
+/**
+ * Pure: apply one fill to a paper state. Returns the new state and the fill
+ * record. `delta` is signed base units (positive buys).
+ */
+export function applyFill(state, { symbol, delta, price, feeUsd, reason, orderId = null, previewId = null }) {
+ const positions = new Map(state.positions);
+ const prev = positions.get(symbol) || { symbol, signed_size: 0, entry_price: 0, funding_paid_usd: 0, funding_at: Date.now(), opened_at: new Date().toISOString() };
+ const size = prev.signed_size;
+ const next = size + delta;
+ let entry;
+ let realized = 0;
+ if (size === 0 || Math.sign(size) === Math.sign(delta)) {
+ const total = Math.abs(size) + Math.abs(delta);
+ entry = total ? (Math.abs(size) * prev.entry_price + Math.abs(delta) * price) / total : 0;
+ } else {
+ const closing = Math.min(Math.abs(size), Math.abs(delta));
+ realized = closing * (price - prev.entry_price) * Math.sign(size);
+ entry = Math.abs(delta) <= Math.abs(size) + EPS ? prev.entry_price : price;
+ }
+ const flat = Math.abs(next) < EPS;
+ const flipped = !flat && size !== 0 && Math.sign(next) !== Math.sign(size);
+ positions.set(symbol, {
+ ...prev,
+ signed_size: flat ? 0 : round(next, 10),
+ entry_price: flat ? 0 : entry,
+ opened_at: size === 0 || flipped ? new Date().toISOString() : prev.opened_at,
+ funding_paid_usd: size === 0 || flipped ? 0 : prev.funding_paid_usd,
+ });
+ return {
+ state: {
+ ...state,
+ positions,
+ collateral_usd: state.collateral_usd + realized - feeUsd,
+ realized_pnl_usd: state.realized_pnl_usd + realized,
+ fees_paid_usd: state.fees_paid_usd + feeUsd,
+ },
+ fill: {
+ symbol,
+ side: delta > 0 ? 'long' : 'short',
+ size: round(Math.abs(delta), 10),
+ price,
+ fee_usd: round(feeUsd, 6),
+ realized_pnl_usd: round(realized, 6),
+ reason,
+ order_id: orderId,
+ preview_id: previewId,
+ },
+ };
+}
+
+/** Pure: settle accrued funding into collateral at the given marks. */
+export function settleFunding(state, markets, nowMs) {
+ const positions = new Map(state.positions);
+ let paid = 0;
+ for (const [symbol, p] of positions) {
+ const m = markets.get(symbol);
+ if (!m || Math.abs(p.signed_size) < EPS) {
+ positions.set(symbol, { ...p, funding_at: nowMs });
+ continue;
+ }
+ const owed = fundingOwed({ signedSize: p.signed_size, mark: m.mark_price, hourlyPct: m.funding_rate_hourly_pct, fromMs: p.funding_at, toMs: nowMs });
+ paid += owed;
+ positions.set(symbol, { ...p, funding_paid_usd: p.funding_paid_usd + owed, funding_at: nowMs });
+ }
+ return { ...state, positions, collateral_usd: state.collateral_usd - paid, funding_paid_usd: state.funding_paid_usd + paid };
+}
+
+// ── storage ──────────────────────────────────────────────────────────────────
+
+function rowToPosition(r) {
+ return {
+ symbol: r.symbol,
+ signed_size: Number(r.signed_size),
+ entry_price: Number(r.entry_price),
+ funding_paid_usd: Number(r.funding_paid_usd),
+ funding_at: new Date(r.funding_at).getTime(),
+ opened_at: new Date(r.opened_at).toISOString(),
+ };
+}
+
+function rowToOrder(r) {
+ return {
+ id: Number(r.id),
+ symbol: r.symbol,
+ type: r.type,
+ side: r.side,
+ size: num(r.size),
+ price: num(r.price),
+ trigger_price: num(r.trigger_price),
+ direction: r.direction,
+ size_percent: num(r.size_percent),
+ reduce_only: r.reduce_only === true,
+ status: r.status,
+ created_at: new Date(r.created_at).toISOString(),
+ };
+}
+
+/** Load (creating on first touch) the paper state for one agent and venue. */
+export async function loadPaperState(agentId, userId, venueId) {
+ await sql`
+ INSERT INTO perps_paper_accounts (agent_id, venue, user_id)
+ VALUES (${agentId}, ${venueId}, ${userId})
+ ON CONFLICT (agent_id, venue) DO NOTHING
+ `;
+ const [[acct], positions, orders] = await Promise.all([
+ sql`SELECT * FROM perps_paper_accounts WHERE agent_id = ${agentId} AND venue = ${venueId}`,
+ sql`SELECT * FROM perps_paper_positions WHERE agent_id = ${agentId} AND venue = ${venueId}`,
+ sql`SELECT * FROM perps_paper_orders WHERE agent_id = ${agentId} AND venue = ${venueId} AND status = 'open' ORDER BY id`,
+ ]);
+ return {
+ agent_id: agentId,
+ venue: venueId,
+ version: Number(acct.version),
+ collateral_usd: Number(acct.collateral_usd),
+ realized_pnl_usd: Number(acct.realized_pnl_usd),
+ fees_paid_usd: Number(acct.fees_paid_usd),
+ funding_paid_usd: Number(acct.funding_paid_usd),
+ deposited_usd: Number(acct.deposited_usd),
+ withdrawn_usd: Number(acct.withdrawn_usd),
+ positions: new Map(positions.map((r) => [r.symbol, rowToPosition(r)])),
+ orders: orders.map(rowToOrder),
+ };
+}
+
+/**
+ * Commit a new paper state. `changes` lists what moved: fills to record, new
+ * orders to insert, and order status changes. Returns false when another
+ * writer won the version race (nothing was written).
+ */
+async function commitPaperState(prev, next, { fills = [], newOrders = [], orderUpdates = [] }) {
+ const token = randomUUID();
+ const a = prev.agent_id;
+ const v = prev.venue;
+ const guard = sql`EXISTS (SELECT 1 FROM perps_paper_accounts WHERE agent_id = ${a} AND venue = ${v} AND op_token = ${token})`;
+ const stmts = [
+ sql`
+ UPDATE perps_paper_accounts SET
+ version = version + 1, op_token = ${token},
+ collateral_usd = ${next.collateral_usd}, realized_pnl_usd = ${next.realized_pnl_usd},
+ fees_paid_usd = ${next.fees_paid_usd}, funding_paid_usd = ${next.funding_paid_usd},
+ deposited_usd = ${next.deposited_usd}, withdrawn_usd = ${next.withdrawn_usd},
+ updated_at = now()
+ WHERE agent_id = ${a} AND venue = ${v} AND version = ${prev.version}
+ `,
+ ];
+ const symbols = new Set([...prev.positions.keys(), ...next.positions.keys()]);
+ for (const symbol of symbols) {
+ const before = prev.positions.get(symbol);
+ const after = next.positions.get(symbol);
+ const same = before && after && before.signed_size === after.signed_size && before.entry_price === after.entry_price
+ && before.funding_paid_usd === after.funding_paid_usd && before.funding_at === after.funding_at;
+ if (same) continue;
+ if (!after || Math.abs(after.signed_size) < EPS) {
+ if (before) stmts.push(sql`DELETE FROM perps_paper_positions WHERE agent_id = ${a} AND venue = ${v} AND symbol = ${symbol} AND ${guard}`);
+ continue;
+ }
+ stmts.push(sql`
+ INSERT INTO perps_paper_positions (agent_id, venue, symbol, signed_size, entry_price, funding_paid_usd, funding_at, opened_at)
+ SELECT ${a}, ${v}, ${symbol}, ${after.signed_size}, ${after.entry_price}, ${after.funding_paid_usd},
+ ${new Date(after.funding_at).toISOString()}, ${after.opened_at}
+ WHERE ${guard}
+ ON CONFLICT (agent_id, venue, symbol) DO UPDATE SET
+ signed_size = excluded.signed_size, entry_price = excluded.entry_price,
+ funding_paid_usd = excluded.funding_paid_usd, funding_at = excluded.funding_at,
+ opened_at = excluded.opened_at, updated_at = now()
+ `);
+ }
+ for (const u of orderUpdates) {
+ stmts.push(sql`
+ UPDATE perps_paper_orders SET status = ${u.status}, fill_price = ${u.fill_price ?? null}, closed_at = now()
+ WHERE id = ${u.id} AND agent_id = ${a} AND status = 'open' AND ${guard}
+ `);
+ }
+ for (const o of newOrders) {
+ stmts.push(sql`
+ INSERT INTO perps_paper_orders (agent_id, venue, symbol, type, side, size, price, trigger_price, direction, size_percent, reduce_only, preview_id)
+ SELECT ${a}, ${v}, ${o.symbol}, ${o.type}, ${o.side}, ${o.size ?? null}, ${o.price ?? null}, ${o.trigger_price ?? null},
+ ${o.direction ?? null}, ${o.size_percent ?? null}, ${o.reduce_only === true}, ${o.preview_id ?? null}
+ WHERE ${guard}
+ `);
+ }
+ for (const f of fills) {
+ stmts.push(sql`
+ INSERT INTO perps_paper_fills (agent_id, venue, symbol, side, size, price, fee_usd, realized_pnl_usd, reason, order_id, preview_id)
+ SELECT ${a}, ${v}, ${f.symbol}, ${f.side}, ${f.size}, ${f.price}, ${f.fee_usd}, ${f.realized_pnl_usd}, ${f.reason}, ${f.order_id}, ${f.preview_id}
+ WHERE ${guard}
+ `);
+ }
+ const results = await sql.transaction(stmts);
+ const first = results[0];
+ const updated = Array.isArray(first) ? first.length : (first?.count ?? first?.rowCount ?? 0);
+ if (updated > 0) return true;
+ // The UPDATE returns no rows without RETURNING; read the token back to know who won.
+ const [row] = await sql`SELECT op_token FROM perps_paper_accounts WHERE agent_id = ${a} AND venue = ${v}`;
+ return row?.op_token === token;
+}
+
+/**
+ * Run `fn(state)` against fresh paper state and commit its result, retrying on
+ * a lost version race. `fn` returns { state, fills?, newOrders?, orderUpdates?, result }.
+ */
+export async function mutatePaper(agentId, userId, venueId, fn) {
+ for (let attempt = 0; attempt < 4; attempt += 1) {
+ const prev = await loadPaperState(agentId, userId, venueId);
+ const out = await fn(prev);
+ if (!out || out.state === prev) return out?.result ?? null;
+ const ok = await commitPaperState(prev, out.state, out);
+ if (ok) return out.result ?? null;
+ }
+ throw perpsError(409, 'paper_busy', 'Another paper order on this agent landed at the same moment. Nothing was applied; try again.');
+}
+
+/** Recent paper fills, newest first. */
+export async function listPaperFills(agentId, venueId, { limit = 50 } = {}) {
+ const rows = await sql`
+ SELECT id, symbol, side, size, price, fee_usd, realized_pnl_usd, reason, order_id, created_at
+ FROM perps_paper_fills WHERE agent_id = ${agentId} AND venue = ${venueId}
+ ORDER BY id DESC LIMIT ${Math.min(200, Math.max(1, limit))}
+ `;
+ return rows.map((r) => ({
+ id: String(r.id),
+ symbol: r.symbol,
+ side: r.side,
+ size: Number(r.size),
+ price: Number(r.price),
+ fee_usd: Number(r.fee_usd),
+ realized_pnl_usd: Number(r.realized_pnl_usd),
+ reason: r.reason,
+ order_id: r.order_id != null ? String(r.order_id) : null,
+ created_at: new Date(r.created_at).toISOString(),
+ }));
+}
+
+/** Every agent holding a paper position or a resting paper order, for the alert sweep. */
+export async function agentsWithPaperExposure() {
+ return sql`
+ SELECT DISTINCT a.agent_id, a.user_id, a.venue
+ FROM perps_paper_accounts a
+ WHERE EXISTS (SELECT 1 FROM perps_paper_positions p WHERE p.agent_id = a.agent_id AND p.venue = a.venue)
+ OR EXISTS (SELECT 1 FROM perps_paper_orders o WHERE o.agent_id = a.agent_id AND o.venue = a.venue AND o.status = 'open')
+ `;
+}
diff --git a/api/_lib/perps/phoenix.js b/api/_lib/perps/phoenix.js
index 3630e95b9..47b488ca0 100644
--- a/api/_lib/perps/phoenix.js
+++ b/api/_lib/perps/phoenix.js
@@ -188,6 +188,10 @@ export function normalizeMarket(config, stats) {
open_interest_usd: oi != null && mark != null ? round(oi * mark, 2) : null,
volume_24h_usd: num(stats?.day_volume_usd),
max_leverage: p.maxLeverage,
+ // Margin as a fraction of notional: initial is one over max leverage,
+ // maintenance is the venue's maintenance share of that initial margin.
+ initial_margin_rate: p.maxLeverage > 0 ? round(1 / p.maxLeverage, 8) : null,
+ maintenance_margin_rate: p.maxLeverage > 0 ? round(p.maintenanceBps / 10_000 / p.maxLeverage, 8) : null,
taker_fee_rate: p.takerFee,
maker_fee_rate: p.makerFee,
min_size: p.sizeStep,