AI Trading API

The AI Trading API provides 18+ methods for interacting with AI-powered quantitative trading agents. It covers strategy discovery, order lifecycle management, portfolio tracking, market data, trade signals, and agent configuration.

Strategy Methods

Method	Parameters	Returns	Description
`getAIStrategies(filters?)`	`filters?: AIStrategyFilters`	`ApiResponse<AIStrategy[]>`	Lists available AI trading strategies, optionally filtered.
`getAIStrategy(strategyId)`	`strategyId: string`	`ApiResponse<AIStrategy>`	Returns details for a single strategy.
`getAIStrategyPerformance(strategyId, period?)`	`strategyId: string, period?: string`	`ApiResponse<AIStrategyPerformance>`	Returns historical performance metrics for a strategy.
`getAIStrategyMarketData(strategyId)`	`strategyId: string`	`ApiResponse<AIMarketData>`	Returns live market data relevant to a strategy's trading pairs.

Order Methods

Method	Parameters	Returns	Description
`createAIOrder(request)`	`request: AIOrderRequest`	`ApiResponse<AIOrder>`	Creates a new AI trading order (investment).
`getAIOrders(filters?)`	`filters?: AIOrderFilters`	`ApiResponse<AIOrder[]>`	Lists the user's AI trading orders, optionally filtered.
`getAIOrder(orderId)`	`orderId: string`	`ApiResponse<AIOrder>`	Returns details for a single order.
`pauseAIOrder(orderId)`	`orderId: string`	`ApiResponse<AIOrder>`	Pauses an active order. The agent stops trading but positions remain open.
`resumeAIOrder(orderId)`	`orderId: string`	`ApiResponse<AIOrder>`	Resumes a paused order.
`redeemAIOrder(orderId)`	`orderId: string`	`ApiResponse<AIOrderRedemption>`	Initiates early withdrawal / redemption of an order.

Portfolio Methods

Method	Parameters	Returns	Description
`getAIPortfolio()`	--	`ApiResponse<AIPortfolio>`	Returns aggregated portfolio metrics across all AI orders.
`getAITradeAllocations(orderId?)`	`orderId?: string`	`ApiResponse<AITradeAllocation[]>`	Returns current capital allocations, optionally scoped to one order.
`getAITradeHistory(options?)`	`options?: AITradeHistoryOptions`	`ApiResponse<AITradeRecord[]>`	Returns historical trade records executed by AI agents.

Signal Methods

Method	Parameters	Returns	Description
`executeAISignals(signals)`	`signals: AISignal[]`	`ApiResponse<AISignalResult[]>`	Manually executes one or more AI-generated trade signals.

Agent Configuration Methods

Method	Parameters	Returns	Description
`getAgentConfigs()`	--	`ApiResponse<AgentConfig[]>`	Lists all available agent configurations (tiers, parameters).
`calculateAgentParams(request)`	`request: AgentParamsRequest`	`ApiResponse<AgentParams>`	Calculates agent parameters for a given investment amount and tier.
`getTradingPairs(chainId?)`	`chainId?: string`	`ApiResponse<TradingPair[]>`	Lists supported trading pairs, optionally filtered by chain.

Types

`AIStrategy`

interface AIStrategy {
  id: string;
  name: string;
  description: string;
  tier: 'conservative' | 'moderate' | 'aggressive';
  chainId: string;
  tradingPairs: string[];
  minInvestment: string;
  maxInvestment: string;
  cycleDays: number;
  expectedApy: { min: number; max: number };
  riskScore: number;
  status: 'active' | 'paused' | 'deprecated';
  createdAt: string;
}

`AIStrategyFilters`

interface AIStrategyFilters {
  tier?: 'conservative' | 'moderate' | 'aggressive';
  chainId?: string;
  status?: 'active' | 'paused';
  minInvestment?: string;
}

`AIStrategyPerformance`

interface AIStrategyPerformance {
  strategyId: string;
  period: string;
  totalReturn: number;
  annualizedReturn: number;
  sharpeRatio: number;
  maxDrawdown: number;
  winRate: number;
  totalTrades: number;
  profitFactor: number;
  dailyReturns: { date: string; return: number }[];
}

`AIMarketData`

interface AIMarketData {
  strategyId: string;
  pairs: {
    pair: string;
    price: string;
    change24h: number;
    volume24h: string;
    high24h: string;
    low24h: string;
  }[];
  timestamp: string;
}

`AIOrderRequest`

interface AIOrderRequest {
  /** Strategy ID to invest in. */
  strategyId: string;
  /** Investment amount in USDC (or strategy base currency). */
  amount: string;
  /** Wallet address funding the order. */
  walletAddress: string;
  /** Optional: override the default cycle duration. */
  cycleDays?: number;
}

`AIOrder`

interface AIOrder {
  id: string;
  strategyId: string;
  strategyName: string;
  userId: string;
  walletAddress: string;
  /** Original investment amount. */
  investedAmount: string;
  /** Current value of the order. */
  currentValue: string;
  /** Unrealised P&L. */
  pnl: string;
  pnlPercentage: number;
  status: 'active' | 'paused' | 'completed' | 'redeeming' | 'redeemed';
  cycleDays: number;
  cycleStartDate: string;
  cycleEndDate: string;
  createdAt: string;
  updatedAt: string;
}

`AIOrderFilters`

interface AIOrderFilters {
  status?: 'active' | 'paused' | 'completed' | 'redeemed';
  strategyId?: string;
  limit?: number;
  cursor?: string;
}

`AIOrderRedemption`

interface AIOrderRedemption {
  orderId: string;
  /** Amount returned to wallet after exit. */
  redeemedAmount: string;
  /** Fee deducted for early withdrawal (if applicable). */
  earlyWithdrawalFee?: string;
  txHash?: string;
  status: 'processing' | 'completed' | 'failed';
  estimatedCompletionAt: string;
}

`AIPortfolio`

interface AIPortfolio {
  totalInvested: string;
  totalCurrentValue: string;
  totalPnl: string;
  totalPnlPercentage: number;
  activeOrders: number;
  completedOrders: number;
  orders: AIOrder[];
}

`AITradeAllocation`

interface AITradeAllocation {
  orderId: string;
  pair: string;
  allocationPercentage: number;
  allocationAmount: string;
  currentValue: string;
  pnl: string;
  side: 'long' | 'short';
}

`AITradeRecord`

interface AITradeRecord {
  id: string;
  orderId: string;
  pair: string;
  side: 'buy' | 'sell';
  amount: string;
  price: string;
  fee: string;
  pnl?: string;
  timestamp: string;
}

`AITradeHistoryOptions`

interface AITradeHistoryOptions {
  orderId?: string;
  pair?: string;
  side?: 'buy' | 'sell';
  limit?: number;
  cursor?: string;
  startDate?: string;
  endDate?: string;
}

`AISignal`

interface AISignal {
  pair: string;
  side: 'buy' | 'sell';
  amount: string;
  /** Target price. */
  price?: string;
  /** Order type. */
  type: 'market' | 'limit';
}

`AISignalResult`

interface AISignalResult {
  signalIndex: number;
  success: boolean;
  txHash?: string;
  executedPrice?: string;
  error?: string;
}

`AgentConfig`

interface AgentConfig {
  id: string;
  name: string;
  tier: 'conservative' | 'moderate' | 'aggressive';
  description: string;
  maxPositions: number;
  maxLeverage: number;
  stopLossPercentage: number;
  takeProfitPercentage: number;
  rebalanceFrequency: string;
  supportedChains: string[];
}

`AgentParamsRequest`

interface AgentParamsRequest {
  tier: 'conservative' | 'moderate' | 'aggressive';
  investmentAmount: string;
  chainId: string;
  cycleDays?: number;
}

`AgentParams`

interface AgentParams {
  tier: string;
  positionSize: string;
  maxPositions: number;
  stopLoss: number;
  takeProfit: number;
  rebalanceInterval: string;
  estimatedApy: { min: number; max: number };
  riskScore: number;
}

`TradingPair`

interface TradingPair {
  pair: string;
  baseToken: string;
  quoteToken: string;
  chainId: string;
  minTradeSize: string;
  maxTradeSize: string;
  pricePrecision: number;
  status: 'active' | 'inactive';
}

Examples

Browse Strategies

const res = await engine.getAIStrategies({ tier: 'moderate', status: 'active' });

if (res.success && res.data) {
  for (const s of res.data) {
    console.log(`${s.name} | APY: ${s.expectedApy.min}-${s.expectedApy.max}% | Risk: ${s.riskScore}`);
  }
}

Create an AI Order

const res = await engine.createAIOrder({
  strategyId: 'strat_abc123',
  amount: '1000',
  walletAddress: '0xABC...',
  cycleDays: 30,
});

if (res.success && res.data) {
  console.log('Order created:', res.data.id);
  console.log('Cycle ends:', res.data.cycleEndDate);
}

View Portfolio

const res = await engine.getAIPortfolio();

if (res.success && res.data) {
  const p = res.data;
  console.log(`Invested: $${p.totalInvested} | Value: $${p.totalCurrentValue}`);
  console.log(`P&L: $${p.totalPnl} (${p.totalPnlPercentage.toFixed(2)}%)`);
  console.log(`Active orders: ${p.activeOrders}`);
}

Pause and Resume an Order

// Pause
await engine.pauseAIOrder('order_123');

// Resume
await engine.resumeAIOrder('order_123');

Early Redemption

const res = await engine.redeemAIOrder('order_123');

if (res.success && res.data) {
  console.log(`Redeemed: $${res.data.redeemedAmount}`);
  if (res.data.earlyWithdrawalFee) {
    console.log(`Early withdrawal fee: $${res.data.earlyWithdrawalFee}`);
  }
}

Trade History

const res = await engine.getAITradeHistory({
  orderId: 'order_123',
  limit: 50,
});

if (res.success && res.data) {
  for (const t of res.data) {
    console.log(`${t.timestamp} | ${t.side} ${t.pair} | ${t.amount} @ ${t.price}`);
  }
}

Agent Configuration

// List agent configs
const configs = await engine.getAgentConfigs();

// Calculate parameters for a specific investment
const params = await engine.calculateAgentParams({
  tier: 'aggressive',
  investmentAmount: '5000',
  chainId: 'ethereum',
  cycleDays: 14,
});

if (params.success && params.data) {
  console.log(`Position size: $${params.data.positionSize}`);
  console.log(`Max positions: ${params.data.maxPositions}`);
  console.log(`Est. APY: ${params.data.estimatedApy.min}-${params.data.estimatedApy.max}%`);
}

// List trading pairs
const pairs = await engine.getTradingPairs('ethereum');

Next Steps

Forex API -- on-chain forex trading pools.
Price API -- free market data endpoints.

Strategy Methods​

Order Methods​

Portfolio Methods​

Signal Methods​

Agent Configuration Methods​

Types​

AIStrategy​

AIStrategyFilters​

AIStrategyPerformance​

AIMarketData​

AIOrderRequest​

AIOrder​

AIOrderFilters​

AIOrderRedemption​

AIPortfolio​

AITradeAllocation​

AITradeRecord​

AITradeHistoryOptions​

AISignal​

AISignalResult​

AgentConfig​

AgentParamsRequest​

AgentParams​

TradingPair​

Examples​

Browse Strategies​

Create an AI Order​

View Portfolio​

Pause and Resume an Order​

Early Redemption​

Trade History​

Agent Configuration​

Next Steps​