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.

17.8 KB
Raw Blame
// 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}
			RETURNING 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 [won] = await sql.transaction(stmts);
	return Array.isArray(won) && won.length > 0;
}

/**
 * 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')
	`;
}