Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsindex 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,