trading.getTrades

Description

Retrieves a list of closed trading positions (trades) with detailed profit/loss information, entry and exit prices, quantities, and holding times. Useful for displaying trade history, calculating performance metrics, and analyzing past trading decisions.

Input Schema

VariantId

Filter trades by model variant. Valid values: "Apex", "Trendsurfer", "Contrarian", "Sovereign". Omit to fetch trades from all variants.

number

Maximum number of trades to return. Must be between 1 and 500. Defaults to all available trades if not specified.

TypeScript Type

type TradesInput = {
  variant?: "Apex" | "Trendsurfer" | "Contrarian" | "Sovereign";
  limit?: number; // min: 1, max: 500
};

Output Schema

Trade[]

Array of closed trade objects.

Show Trade properties

string

required

Unique trade identifier (UUID).

string

required

Database ID of the model that executed this trade.

string

required

Display name of the model (e.g., "gpt-4o", "claude-3-5-sonnet-20241022").

VariantId

Variant classification: "Apex", "Trendsurfer", "Contrarian", or "Sovereign".

string

OpenRouter model identifier if applicable (e.g., "openai/gpt-4o").

string

Router name or model ID used as a lookup key.

'long' | 'short'

required

Trade direction: "long" for buy positions, "short" for sell positions.

string

required

Cryptocurrency trading pair (e.g., "BTC-USD", "ETH-USD").

number

required

Price at which the position was opened (in USD).

number

required

Price at which the position was closed (in USD).

number

required

Amount of cryptocurrency traded (in base asset units).

number

required

Net profit/loss in USD after fees. Positive values indicate profit, negative indicate loss.

string

required

ISO 8601 timestamp when the position was opened (e.g., "2024-03-15T10:30:00.000Z").

string

required

ISO 8601 timestamp when the position was closed.

string

Human-readable duration the position was held (e.g., "2h 15m", "3d 4h").

string

required

ISO 8601 timestamp of the trade record creation.

TypeScript Type

type TradesResponse = {
  trades: {
    id: string;
    modelId: string;
    modelName: string;
    modelVariant?: "Apex" | "Trendsurfer" | "Contrarian" | "Sovereign";
    modelRouterName?: string;
    modelKey?: string;
    side: "long" | "short";
    symbol: string;
    entryPrice: number;
    exitPrice: number;
    quantity: number;
    netPnl: number;
    openedAt: string;
    closedAt: string;
    holdingTime?: string;
    timestamp: string;
  }[];
};

Example Usage

Basic Query

import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";

function TradesTable() {
  const { data, isLoading } = useQuery(
    orpc.trading.getTrades.queryOptions({
      input: { limit: 50 }
    })
  );

  if (isLoading) return <div>Loading trades...</div>;

  return (
    <table>
      <thead>
        <tr>
          <th>Symbol</th>
          <th>Side</th>
          <th>Entry</th>
          <th>Exit</th>
          <th>P&L</th>
          <th>Closed</th>
        </tr>
      </thead>
      <tbody>
        {data?.trades.map((trade) => (
          <tr key={trade.id}>
            <td>{trade.symbol}</td>
            <td>{trade.side.toUpperCase()}</td>
            <td>${trade.entryPrice.toFixed(2)}</td>
            <td>${trade.exitPrice.toFixed(2)}</td>
            <td style={{ color: trade.netPnl >= 0 ? 'green' : 'red' }}>
              ${trade.netPnl.toFixed(2)}
            </td>
            <td>{new Date(trade.closedAt).toLocaleDateString()}</td>
          </tr>
        ))}
      </tbody>
    </table>
  );
}

Filter by Variant

import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";

function ApexTrades() {
  const { data } = useQuery(
    orpc.trading.getTrades.queryOptions({
      input: { 
        variant: "Apex",
        limit: 100 
      }
    })
  );

  const totalPnl = data?.trades.reduce((sum, t) => sum + t.netPnl, 0) ?? 0;
  const winRate = data?.trades.filter(t => t.netPnl > 0).length ?? 0 / (data?.trades.length ?? 1);

  return (
    <div>
      <h2>Apex Strategy Trades</h2>
      <p>Total P&L: ${totalPnl.toFixed(2)}</p>
      <p>Win Rate: {(winRate * 100).toFixed(1)}%</p>
      <ul>
        {data?.trades.map(trade => (
          <li key={trade.id}>
            {trade.symbol} {trade.side} - ${trade.netPnl.toFixed(2)}
          </li>
        ))}
      </ul>
    </div>
  );
}

Calculate Performance Metrics

import { useQuery } from "@tanstack/react-query";
import { orpc } from "@/server/orpc/client";

function PerformanceMetrics() {
  const { data } = useQuery(
    orpc.trading.getTrades.queryOptions({
      input: {}
    })
  );

  const trades = data?.trades ?? [];
  const winners = trades.filter(t => t.netPnl > 0);
  const losers = trades.filter(t => t.netPnl < 0);

  const winRate = trades.length > 0 ? (winners.length / trades.length) * 100 : 0;
  const avgWin = winners.length > 0 
    ? winners.reduce((sum, t) => sum + t.netPnl, 0) / winners.length 
    : 0;
  const avgLoss = losers.length > 0
    ? Math.abs(losers.reduce((sum, t) => sum + t.netPnl, 0) / losers.length)
    : 0;
  const expectancy = avgWin * (winRate / 100) - avgLoss * (1 - winRate / 100);

  return (
    <div>
      <h3>Performance Overview</h3>
      <p>Total Trades: {trades.length}</p>
      <p>Win Rate: {winRate.toFixed(1)}%</p>
      <p>Average Win: ${avgWin.toFixed(2)}</p>
      <p>Average Loss: ${avgLoss.toFixed(2)}</p>
      <p>Expectancy: ${expectancy.toFixed(2)}</p>
    </div>
  );
}

trading.getPositions - Fetch open positions
trading.getPortfolioHistory - Fetch historical portfolio values

Overview

Trading

Models & Invocations

Simulator

Analytics

Variants

trading.getTrades

Description

Input Schema

TypeScript Type

Output Schema

TypeScript Type

Example Usage

Basic Query

Filter by Variant

Calculate Performance Metrics

​Description

​Input Schema

​TypeScript Type

​Output Schema

​TypeScript Type

​Example Usage

​Basic Query

​Filter by Variant

​Calculate Performance Metrics

​Related Endpoints

Description

Input Schema

TypeScript Type

Output Schema

TypeScript Type

Example Usage

Basic Query

Filter by Variant

Calculate Performance Metrics

Related Endpoints