Skip to main content

Agent Catalog

The agent catalog lets you browse all available AI trading strategies, filter by category or risk level, and display strategy details to your users. You can use the useAIStrategies React hook or call the OneEngineClient API methods directly.

useAIStrategies Hook​

The useAIStrategies hook fetches and manages the list of available AI strategies with built-in loading, error, and refetch support.

import { useAIStrategies } from '@one_deploy/sdk';
import type { UseAIStrategiesOptions, UseAIStrategiesResult } from '@one_deploy/sdk';

UseAIStrategiesOptions​

interface UseAIStrategiesOptions {
  /** Filter by strategy category. */
  category?: StrategyCategory;

  /** Filter by risk level. */
  riskLevel?: RiskLevel;

  /** Include performance history in response. */
  includePerformance?: boolean;

  /** Maximum number of strategies to return. */
  limit?: number;

  /** Offset for pagination. */
  offset?: number;

  /** Whether to automatically fetch on mount. Defaults to true. */
  enabled?: boolean;
}

UseAIStrategiesResult​

interface UseAIStrategiesResult {
  /** Array of fetched AI strategies. */
  strategies: AIStrategy[];

  /** True while the initial fetch is in progress. */
  isLoading: boolean;

  /** Error object if the fetch failed, otherwise null. */
  error: Error | null;

  /** Re-fetch the strategies list. */
  refetch: () => Promise<void>;

  /** Total number of strategies matching the filters (for pagination). */
  total: number;
}

Basic Usage​

import { useAIStrategies } from '@one_deploy/sdk';

function StrategyCatalog() {
  const { strategies, isLoading, error } = useAIStrategies();

  if (isLoading) return <Text>Loading strategies...</Text>;
  if (error) return <Text>Error: {error.message}</Text>;

  return (
    <FlatList
      data={strategies}
      keyExtractor={(item) => item.id}
      renderItem={({ item }) => (
        <View style={styles.card}>
          <Text style={styles.name}>{item.name}</Text>
          <Text style={styles.category}>{item.category}</Text>
          <Text style={styles.risk}>Risk: {item.riskLevel}</Text>
          <Text style={styles.apy}>Expected APY: {item.expectedApy}%</Text>
        </View>
      )}
    />
  );
}

Filtering by Category and Risk​

import { useAIStrategies } from '@one_deploy/sdk';

function ConservativeStrategies() {
  const { strategies, isLoading } = useAIStrategies({
    category: 'conservative',
    riskLevel: 'conservative',
    includePerformance: true,
  });

  if (isLoading) return <Text>Loading...</Text>;

  return (
    <View>
      <Text>Found {strategies.length} conservative strategies</Text>
      {strategies.map((strategy) => (
        <View key={strategy.id}>
          <Text>{strategy.name}</Text>
          <Text>30-day return: {strategy.performance?.return30d ?? 'N/A'}%</Text>
          <Text>Max drawdown: {strategy.performance?.maxDrawdown ?? 'N/A'}%</Text>
        </View>
      ))}
    </View>
  );
}

AIStrategy Type​

interface AIStrategy {
  /** Unique strategy identifier. */
  id: string;

  /** Human-readable strategy name. */
  name: string;

  /** Full description of the strategy approach. */
  description: string;

  /** Strategy category. */
  category: StrategyCategory;

  /** Risk classification. */
  riskLevel: RiskLevel;

  /** Expected annualised percentage yield. */
  expectedApy: number;

  /** Minimum investment amount in USD. */
  minInvestment: number;

  /** Maximum investment amount in USD, or null for unlimited. */
  maxInvestment: number | null;

  /** Supported chain IDs. */
  supportedChains: number[];

  /** Supported trading pair identifiers. */
  supportedPairs: string[];

  /** Available investment cycle durations (in days). */
  availableCycles: number[];

  /** Available tiers for this strategy. */
  tiers: Tier[];

  /** Whether the strategy is currently accepting new orders. */
  isActive: boolean;

  /** ISO 8601 creation timestamp. */
  createdAt: string;

  /** Performance metrics, present when includePerformance is true. */
  performance?: AIStrategyPerformance;
}

interface AIStrategyPerformance {
  return7d: number;
  return30d: number;
  return90d: number;
  maxDrawdown: number;
  sharpeRatio: number;
  winRate: number;
  totalTrades: number;
}

API Methods​

For non-React contexts or when you need direct control, use the OneEngineClient methods.

getAgentConfigs​

Fetches raw agent configuration data, including all available strategy templates.

import { OneEngineClient } from '@one_deploy/sdk';

const engine = new OneEngineClient({
  apiKey: process.env.ONE_API_KEY!,
  projectId: process.env.ONE_PROJECT_ID!,
});

const configs = await engine.getAgentConfigs({
  category: 'balanced',
  includeInactive: false,
});

console.log('Agent configs:', configs.length);

Method Signature​

getAgentConfigs(options?: GetAgentConfigsOptions): Promise<AgentConfig[]>
ParameterTypeDescription
options.categoryStrategyCategoryFilter by category. Optional.
options.includeInactivebooleanInclude inactive agents. Defaults to false.

getAIStrategies​

Fetches the strategy catalog with optional filters.

const strategies = await engine.getAIStrategies({
  category: 'grid',
  riskLevel: 'moderate',
});

strategies.forEach((s) => {
  console.log(`${s.name} (${s.category}) -- APY: ${s.expectedApy}%`);
});

Method Signature​

getAIStrategies(filters?: AIStrategyFilters): Promise<AIStrategy[]>
interface AIStrategyFilters {
  category?: StrategyCategory;
  riskLevel?: RiskLevel;
  chainId?: number;
  pair?: string;
  minApy?: number;
  isActive?: boolean;
}

getAIStrategy​

Fetches a single strategy by ID with optional related data.

const strategy = await engine.getAIStrategy('strat_abc123', {
  includePerformance: true,
  includeTiers: true,
});

console.log('Strategy:', strategy.name);
console.log('Tiers:', strategy.tiers.length);
console.log('Win rate:', strategy.performance?.winRate);

Method Signature​

getAIStrategy(strategyId: string, include?: AIStrategyInclude): Promise<AIStrategy>
interface AIStrategyInclude {
  includePerformance?: boolean;
  includeTiers?: boolean;
  includePairs?: boolean;
}

Building a Strategy Browser​

Here is a full example combining the hook with category tabs and a detail view.

import { useState } from 'react';
import { useAIStrategies } from '@one_deploy/sdk';
import type { StrategyCategory, AIStrategy } from '@one_deploy/sdk';

const CATEGORIES: StrategyCategory[] = [
  'conservative', 'balanced', 'aggressive', 'hedge',
  'arbitrage', 'trend', 'grid', 'dca',
];

function StrategyBrowser() {
  const [activeCategory, setActiveCategory] = useState<StrategyCategory | undefined>();
  const [selected, setSelected] = useState<AIStrategy | null>(null);

  const { strategies, isLoading, error, refetch } = useAIStrategies({
    category: activeCategory,
    includePerformance: true,
  });

  return (
    <View style={styles.container}>
      {/* Category Tabs */}
      <ScrollView horizontal style={styles.tabs}>
        <Pressable onPress={() => setActiveCategory(undefined)}>
          <Text style={!activeCategory ? styles.activeTab : styles.tab}>All</Text>
        </Pressable>
        {CATEGORIES.map((cat) => (
          <Pressable key={cat} onPress={() => setActiveCategory(cat)}>
            <Text style={activeCategory === cat ? styles.activeTab : styles.tab}>
              {cat.charAt(0).toUpperCase() + cat.slice(1)}
            </Text>
          </Pressable>
        ))}
      </ScrollView>

      {/* Strategy List */}
      {isLoading ? (
        <ActivityIndicator />
      ) : error ? (
        <Text>Failed to load: {error.message}</Text>
      ) : (
        <FlatList
          data={strategies}
          keyExtractor={(item) => item.id}
          renderItem={({ item }) => (
            <Pressable onPress={() => setSelected(item)}>
              <View style={styles.strategyCard}>
                <Text style={styles.strategyName}>{item.name}</Text>
                <Text>Category: {item.category}</Text>
                <Text>Risk: {item.riskLevel}</Text>
                <Text>APY: {item.expectedApy}%</Text>
                <Text>Min: ${item.minInvestment}</Text>
              </View>
            </Pressable>
          )}
        />
      )}

      {/* Detail View */}
      {selected && (
        <View style={styles.detail}>
          <Text style={styles.detailTitle}>{selected.name}</Text>
          <Text>{selected.description}</Text>
          <Text>7d Return: {selected.performance?.return7d}%</Text>
          <Text>30d Return: {selected.performance?.return30d}%</Text>
          <Text>Sharpe Ratio: {selected.performance?.sharpeRatio}</Text>
          <Text>Win Rate: {selected.performance?.winRate}%</Text>
          <Text>Chains: {selected.supportedChains.join(', ')}</Text>
          <Text>Pairs: {selected.supportedPairs.join(', ')}</Text>
          <Pressable onPress={() => setSelected(null)}>
            <Text>Close</Text>
          </Pressable>
        </View>
      )}
    </View>
  );
}

Next Steps​