Get Models

Retrieve a list of all AI models configured for trading

GET /api/rpc/models.getModels

Get Models

cURL

curl --request GET \
  --url https://api.example.com/api/rpc/models.getModels \
  --header 'Content-Type: application/json' \
  --data '{
  "input": {}
}'

200

{
  "models": [
    {
      "id": "<string>",
      "name": "<string>"
    }
  ],
  "warning": "<string>"
}

Overview

The getModels endpoint returns a list of all trading models currently configured in the system. Each model represents an AI trading agent with its own unique identifier and display name.

Model Variants

Each model in the system belongs to a specific variant that defines its trading strategy:

• Apex - Aggressive 10x leverage with Kelly engine, VWAP momentum validation, squeeze trading
• Trendsurfer - Trend follower with ADX > 25 filter and Kijun-Sen trailing stops
• Contrarian - Mean reversion strategy for ranging markets (ADX < 25), fade to VWAP
• Sovereign - Flexible regime-adaptive allocator blending trend & range strategies

While variants are stored in the database schema, the basic getModels endpoint returns only id and name fields for lightweight model listing.

Request

input · object

Empty object - no parameters required

// oRPC schema
z.object({})

Response

models · array

Array of model objects with basic identification fields

Show Model Object Properties

id · string · required

Unique model identifier (UUID format)

name · string · required

Display name of the model

warning · string

Optional warning message if fallback data is being used (e.g., “Database unavailable, using static model metadata.”)

// Response schema
z.object({
  models: z.array(
    z.object({
      id: z.string(),
      name: z.string(),
    })
  ),
  warning: z.string().optional(),
})

Database Schema

The full Models table includes additional fields not exposed by this endpoint:

{
  id: string;                    // Primary key (UUID)
  name: string;                  // Model display name
  openRouterModelName: string;   // OpenRouter model identifier
  variant: VariantId;            // "Apex" | "Trendsurfer" | "Contrarian" | "Sovereign"
  lighterApiKey: string;         // API key for Lighter exchange
  invocationCount: number;       // Total AI invocations counter
  totalMinutes: number;          // Total runtime in minutes
  accountIndex: string;          // Exchange account index
  failedWorkflowCount: number;   // Failed workflow counter
  failedToolCallCount: number;   // Failed tool call counter
}

Fallback Behavior

If the database is unavailable, the endpoint returns a static fallback list derived from MODEL_INFO configuration:

// Fallback data structure
Object.entries(MODEL_INFO).map(([id, info]) => ({
  id,
  name: info.label || id,
}))

The response will include a warning field when fallback data is being served.

TanStack Query Integration

Client Usage

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

function ModelsDropdown() {
  const { data, error, isLoading } = useQuery(
    orpc.models.getModels.queryOptions({ input: {} })
  );

  if (isLoading) return <div>Loading models...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (data?.warning) console.warn(data.warning);

  return (
    <select>
      {data?.models.map((model) => (
        <option key={model.id} value={model.id}>
          {model.name}
        </option>
      ))}
    </select>
  );
}

Query Configuration

export const modelsListQuery = () =>
  queryOptions({
    queryKey: ["models", "simple-list"],
    queryFn: fetchModelsList,
    staleTime: 30_000,  // 30 seconds
    gcTime: 5 * 60_000, // 5 minutes
  });

Example Response

{
  "models": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "GPT-4 Turbo"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Claude 3 Opus"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Gemini Pro"
    }
  ]
}

Error Handling

The endpoint includes Sentry error tracking and graceful fallback:

try {
  const models = await fetchModelsList();
  return { models };
} catch (error) {
  console.error("Failed to fetch models", error);
  Sentry.captureException(error);
  
  // Return static fallback data
  const fallback = Object.entries(MODEL_INFO).map(([id, info]) => ({
    id,
    name: info.label || id,
  }));
  
  return {
    models: fallback,
    warning: "Database unavailable, using static model metadata.",
  };
}

Related Endpoints

• Get Invocations - Fetch model invocation history with tool calls
• Get Positions - Fetch active positions for all models
• Get Trades - Fetch closed trades across models

Implementation Details

Source Files:

• Router: src/server/orpc/router/models.ts:18-41
• Query Function: src/server/features/trading/queries.server.ts:696-703
• Schema: src/db/schema.ts:29-48

Cache Strategy:

• Stale Time: 30 seconds (models rarely change)
• GC Time: 5 minutes
• Refetch: On window focus (default TanStack behavior)