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.

11.3 KB
Raw Blame
// Arbitrage honesty (size cap, simulated worst case, verdict), the ecosystem
// anomaly rules, and the shared tool registry both the REST routes and the
// MCP server are built from. The arbitrage figures replay a live quote
// recorded in tests/fixtures/trading-tools/sol-usdc-arbitrage.json.

import { describe, it, expect } from 'vitest';

import recorded from './fixtures/trading-tools/sol-usdc-arbitrage.json' with { type: 'json' };
import {
	ARB_SIZE_CAP_USD,
	ARB_HARD_CAP_USD,
	ARB_LEG_SLIPPAGE_BPS,
	checkArbSize,
	worstCase,
	arbVerdict,
	slippageFloor,
	rankRoutes,
	twoLegFeeInQuote,
	LEG_FEE_LAMPORTS,
} from '../api/_lib/trading-tools/arbitrage.js';
import { hourlyAnomalies, coinAnomalies, zScore } from '../api/_lib/trading-tools/ecosystem.js';
import { TRADING_TOOLS, validateToolArgs } from '../api/_lib/trading-tools/registry.js';
import { queryArgs, tradingRoutes } from '../api/_lib/trading-tools/routes.js';
import { tradingToolDefs } from '../api/_mcpagent/trading-tools.js';
import { CATALOG } from '../api/v1/_catalog.js';
import { WSOL_MINT, USDC_MINT } from '../api/_lib/trading-tools/market.js';

const r = recorded.result;

describe('arbitrage size gate', () => {
	it('quotes inside the default cap', () => {
		expect(checkArbSize({ sizeUsd: 50 })).toMatchObject({ ok: true, size_usd: 50, above_default_cap: false, cap_usd: ARB_SIZE_CAP_USD });
	});

	it('refuses above the default cap unless the caller accepts the risk', () => {
		const refused = checkArbSize({ sizeUsd: ARB_SIZE_CAP_USD + 1 });
		expect(refused).toMatchObject({ ok: false, code: 'size_above_cap' });
		expect(refused.message).toMatch(/accept_size_risk: true/);
		expect(checkArbSize({ sizeUsd: ARB_SIZE_CAP_USD + 1, accept: true })).toMatchObject({ ok: true, above_default_cap: true });
	});

	it('refuses above the hard ceiling even with consent', () => {
		expect(checkArbSize({ sizeUsd: ARB_HARD_CAP_USD + 1, accept: true })).toMatchObject({ ok: false, code: 'size_above_hard_cap' });
	});

	it('refuses a size it cannot price', () => {
		expect(checkArbSize({ sizeUsd: null })).toMatchObject({ ok: false, code: 'size_unpriced' });
		expect(checkArbSize({ sizeUsd: Number.NaN })).toMatchObject({ ok: false, code: 'size_unpriced' });
	});

	it('kept the recorded live quote inside the cap', () => {
		expect(r.size).toMatchObject({ ok: true, size_usd: recorded.args.amount, above_default_cap: false });
	});
});

describe('simulated worst case on the recorded live quote', () => {
	const bps = r.worst_case.inputs.slippage_bps_per_leg;
	const floorBack = (x) => x / (1 - bps / 10_000);
	const scenario = (id) => r.worst_case.scenarios.find((s) => s.id === id);
	const inputs = {
		amount: recorded.args.amount,
		feeInQuote: r.expected.network_fees,
		expectedOut: r.expected.quote_out,
		slippedOut: floorBack(scenario('both_legs_slip').quote_out),
		closedOut: floorBack(scenario('spread_closes').quote_out),
		slippageBps: bps,
	};

	it('reproduces the recorded scenarios and maximum loss', () => {
		const w = worstCase(inputs);
		expect(w.scenarios.map((s) => s.id)).toEqual(['expected', 'both_legs_slip', 'spread_closes']);
		w.scenarios.forEach((s, i) => {
			expect(s.quote_out).toBeCloseTo(r.worst_case.scenarios[i].quote_out, 9);
			expect(s.net_profit).toBeCloseTo(r.worst_case.scenarios[i].net_profit, 9);
		});
		expect(w.max_loss).toBeCloseTo(r.worst_case.max_loss, 9);
		expect(w.max_loss_pct).toBeCloseTo(r.worst_case.max_loss_pct, 6);
		expect(w.fees_counted).toBe(true);
	});

	it('takes the lower of the two adverse scenarios', () => {
		const w = worstCase(inputs);
		expect(w.worst_quote_out).toBe(Math.min(...w.scenarios.slice(1).map((s) => s.quote_out)));
		expect(w.worst_net_profit).toBeLessThan(w.scenarios[0].net_profit);
	});

	it('still prices the slip scenario when no weaker venue quoted', () => {
		const w = worstCase({ ...inputs, closedOut: null });
		expect(w.scenarios.map((s) => s.id)).toEqual(['expected', 'both_legs_slip']);
	});

	it('says the recorded route is unprofitable and treats the legs as non-atomic', () => {
		expect(arbVerdict({ expectedNet: r.expected.net_profit, worst: r.worst_case }).verdict).toBe(r.verdict);
		expect(r.risk.atomic).toBe(false);
		expect(r.risk.factors.map((f) => f.id)).toEqual(['leg_gap', 'slippage', 'stranded_inventory', 'guards']);
		expect(r.legs.map((l) => l.swap_quote.slippage_bps)).toEqual([ARB_LEG_SLIPPAGE_BPS, ARB_LEG_SLIPPAGE_BPS]);
		expect(r.legs[0].swap_quote.dex).toBe(r.legs[0].venue);
	});
});

describe('arbitrage verdict', () => {
	const worst = (maxLoss) => ({ max_loss: maxLoss });
	it('calls a positive edge with a smaller worst case viable', () => {
		expect(arbVerdict({ expectedNet: 0.5, worst: worst(0.2) }).verdict).toBe('viable');
	});
	it('calls an edge the worst case can wipe out risk_exceeds_edge', () => {
		expect(arbVerdict({ expectedNet: 0.5, worst: worst(0.5) }).verdict).toBe('risk_exceeds_edge');
	});
	it('calls a non-positive edge unprofitable', () => {
		expect(arbVerdict({ expectedNet: 0, worst: worst(0) }).verdict).toBe('unprofitable');
		expect(arbVerdict({ expectedNet: null, worst: worst(0) }).verdict).toBe('unprofitable');
	});
});

describe('arbitrage helpers', () => {
	it('applies the slippage floor in base units', () => {
		expect(slippageFloor('45528323', 100)).toBe(45073039n);
		expect(slippageFloor(10_000n, 0)).toBe(10_000n);
	});

	it('prices both legs of network fees in the quote token', () => {
		expect(twoLegFeeInQuote(WSOL_MINT, null)).toBe((2 * LEG_FEE_LAMPORTS) / 1e9);
		expect(twoLegFeeInQuote(USDC_MINT, 100)).toBeCloseTo(((2 * LEG_FEE_LAMPORTS) / 1e9) * 100, 12);
		expect(twoLegFeeInQuote('THREEsynthetic1111111111111111111111111111', 100)).toBeNull();
	});

	it('ranks candidates by net profit', () => {
		const ranked = rankRoutes([{ sell: { out: 5.01 } }, { sell: { out: 5.03 } }, { sell: { out: 4.9 } }], 5, 0.02);
		expect(ranked.map((c) => c.sell.out)).toEqual([5.03, 5.01, 4.9]);
		expect(ranked[0].net).toBeCloseTo(0.01, 12);
	});
});

describe('ecosystem anomaly rules', () => {
	const asOf = '2026-10-10T06:00:00.000Z';
	const hours = (values) => values.map((v, i) => ({ hour: new Date(Date.UTC(2026, 9, 9, i)).toISOString(), launches: v }));
	const metrics = [{ id: 'launches_per_hour', label: 'Launches per hour', source: 'pump_coin_intel', value: (b) => b.launches }];

	it('flags a latest hour two deviations off its baseline and returns its inputs', () => {
		const out = hourlyAnomalies(hours([100, 104, 98, 101, 97, 103, 99, 100, 160]), metrics, asOf);
		expect(out).toHaveLength(1);
		expect(out[0]).toMatchObject({ kind: 'metric_spike', id: 'launches_per_hour_high', direction: 'above_normal', value: 160, as_of: asOf });
		expect(out[0].inputs).toMatchObject({ source: 'pump_coin_intel', baseline_hours: 8 });
		expect(out[0].inputs.hour).toBe(new Date(Date.UTC(2026, 9, 9, 8)).toISOString());
	});

	it('stays quiet inside normal variation and with too little history', () => {
		expect(hourlyAnomalies(hours([100, 104, 98, 101, 97, 103, 99, 100, 102]), metrics, asOf)).toEqual([]);
		expect(hourlyAnomalies(hours([1, 1, 1, 50]), metrics, asOf)).toEqual([]);
	});

	it('refuses a z-score on a flat baseline', () => {
		expect(zScore(5, [1, 1, 1, 1, 1, 1]).z).toBeNull();
	});

	it('ranks a dev dump into inflow above a smart-money cluster above a plain outlier', () => {
		const row = (mint, buySol, extra = {}) => ({ mint, symbol: null, name: null, first_seen_at: asOf, buy_volume_lamports: buySol * 1e9, sell_volume_lamports: 0, unique_buyers: 10, smart_money_count: 0, dev_sold: false, risk_flags: [], ...extra });
		const out = coinAnomalies({
			sample: 400,
			cut: 30e9,
			rows: [
				row('THREEsynthetic1111111111111111111111111111a', 40),
				row('THREEsynthetic1111111111111111111111111111b', 35, { dev_sold: true }),
				row('THREEsynthetic1111111111111111111111111111c', 5, { smart_money_count: 3 }),
				row('THREEsynthetic1111111111111111111111111111d', 10),
			],
		}, asOf, { window: '1h', minutes: 60 });
		expect(out.map((a) => a.kind)).toEqual(['dev_dump_into_inflow', 'smart_money_cluster', 'volume_outlier']);
		expect(out[0].inputs).toMatchObject({ source: 'pump_coin_intel', window: '1h', threshold_sol: 30, coins_in_window: 400 });
		for (const a of out) expect(a.as_of).toBe(asOf);
	});

	it('holds the outlier floor when the window cut is low, and skips outliers on a thin sample', () => {
		const rows = [{ mint: 'THREEsynthetic1111111111111111111111111111e', buy_volume_lamports: 20e9, smart_money_count: 0 }];
		expect(coinAnomalies({ sample: 400, cut: 1e9, rows }, asOf, {})).toEqual([]);
		expect(coinAnomalies({ sample: 10, cut: 1e9, rows: [{ ...rows[0], buy_volume_lamports: 900e9 }] }, asOf, {})).toEqual([]);
	});
});

describe('one registry behind REST and MCP', () => {
	const names = ['token_search', 'get_price', 'get_indicators', 'get_market_signals', 'get_news_feed', 'arbitrage_prices', 'arbitrage_quote', 'swap_quote', 'swap_simulate', 'swap_execute'];

	it('defines every brief tool exactly once', () => {
		expect(TRADING_TOOLS.map((t) => t.name).sort()).toEqual([...names].sort());
	});

	it('exposes each tool as a REST route and an MCP tool with the same schema', () => {
		for (const t of TRADING_TOOLS) {
			const route = tradingRoutes.find((x) => x.name === `v1.trading.${t.name}`);
			expect(route).toMatchObject({ method: t.method, path: `/trading${t.path}`, auth: t.auth });
			const mcp = tradingToolDefs.find((x) => x.name === t.name);
			expect(mcp.inputSchema).toBe(t.inputSchema);
			expect(mcp.group).toBe('trading');
		}
		expect(tradingRoutes[0]).toMatchObject({ method: 'GET', path: '/trading', auth: 'public' });
	});

	it('lists every trading route in the /api/v1 discovery catalog with the same method, path and auth', () => {
		for (const route of tradingRoutes) {
			const entry = CATALOG.find((e) => e.id === route.name);
			expect(entry, route.name).toMatchObject({ method: route.method, path: `/api/v1${route.path}`, auth: route.auth });
			const tool = TRADING_TOOLS.find((t) => `v1.trading.${t.name}` === route.name);
			if (tool) expect(Object.keys(entry.params).sort()).toEqual(Object.keys(tool.inputSchema.properties).sort());
		}
	});

	it('makes swap_execute the only financial tool and gates it on confirm_swap after swap_quote', () => {
		const financial = tradingToolDefs.filter((t) => t.tier === 'financial');
		expect(financial.map((t) => t.name)).toEqual(['swap_execute']);
		expect(financial[0]).toMatchObject({ confirmFlag: 'confirm_swap', previewTool: 'swap_quote' });
		expect(financial[0].annotations.destructiveHint).toBe(true);
		expect(tradingToolDefs.find((t) => t.name === 'swap_simulate').tier).not.toBe('financial');
	});

	it('validates, coerces and defaults arguments', () => {
		const args = { mint: 'SOL', indicators: 'rsi', period: '21' };
		expect(validateToolArgs('get_indicators', args)).toBeNull();
		expect(args).toEqual({ mint: 'SOL', indicators: ['rsi'], period: 21, interval: '1h' });
		expect(validateToolArgs('get_indicators', { mint: 'SOL', limit: 5 })).toMatchObject({ field: 'limit' });
		expect(validateToolArgs('swap_execute', {})).toMatchObject({ field: 'quote_id' });
		expect(validateToolArgs('swap_quote', { input_mint: 'SOL' })).toMatchObject({ field: 'output_mint' });
	});

	it('splits comma lists in a query string only for array arguments', () => {
		const schema = TRADING_TOOLS.find((t) => t.name === 'get_market_signals').inputSchema;
		expect(queryArgs({ sections: 'macro, movers', window: '1h', mint: '' }, schema)).toEqual({ sections: ['macro', 'movers'], window: '1h' });
	});
});