跳至主要内容

代理目录

代理目录允许您浏览所有可用的 AI 交易策略，按类别或风险等级进行筛选，并向用户展示策略详情。您可以使用 useAIStrategies React hook，或直接调用 OneEngineClient 的 API 方法。

useAIStrategies Hook​

useAIStrategies hook 负责获取和管理可用 AI 策略列表，内置加载状态、错误处理和重新获取支持。

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;
}

基本用法​

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>
      )}
    />
  );
}

按类别和风险筛选​

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 类型​

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 方法​

对于非 React 场景或需要直接控制的情况，请使用 OneEngineClient 方法。

getAgentConfigs​

获取原始代理配置数据，包括所有可用的策略模板。

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);

方法签名​

getAgentConfigs(options?: GetAgentConfigsOptions): Promise<AgentConfig[]>
参数类型描述
options.categoryStrategyCategory按类别筛选。可选。
options.includeInactiveboolean包含非活跃代理。默认为 false。

getAIStrategies​

获取策略目录，支持可选筛选条件。

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

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

方法签名​

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

getAIStrategy​

根据 ID 获取单个策略，支持可选的关联数据。

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);

方法签名​

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

构建策略浏览器​

以下是一个完整示例，结合了 hook、类别标签页和详情视图。

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>
  );
}

后续步骤​