外汇 API

外汇 API 提供了与链上外汇流动性池交互的方法。涵盖资金池发现、投资创建与管理、资金分配、每日快照和交易历史。

资金池方法

方法	参数	返回值	描述
getForexPools(filters?)	filters?: ForexPoolFilters	ApiResponse<ForexPool[]>	列出可用的外汇流动性池，可选筛选。
getForexPool(poolId)	poolId: string	ApiResponse<ForexPool>	返回单个外汇资金池的详细信息。
getForexPoolSnapshots(poolId, options?)	poolId: string, options?: SnapshotOptions	ApiResponse<ForexPoolDailySnapshot[]>	返回资金池的每日表现快照。

投资方法

方法	参数	返回值	描述
createForexInvestment(request)	request: ForexInvestmentRequest	ApiResponse<ForexInvestment>	在外汇资金池中创建新投资。
getForexInvestments(filters?)	filters?: ForexInvestmentFilters	ApiResponse<ForexInvestment[]>	列出用户的外汇投资。
getForexInvestment(investmentId)	investmentId: string	ApiResponse<ForexInvestment>	返回单笔投资的详细信息。
redeemForexInvestment(investmentId)	investmentId: string	ApiResponse<ForexRedemption>	发起从外汇资金池的提现。

交易方法

方法	参数	返回值	描述
getForexTradeHistory(options?)	options?: ForexTradeHistoryOptions	ApiResponse<ForexTradeRecord[]>	返回外汇资金池 Agent 执行的交易记录。

类型

ForexPool

interface ForexPool {
  id: string;
  name: string;
  description: string;
  /** Currency pairs traded by this pool (e.g. ["EUR/USD", "GBP/USD"]). */
  currencyPairs: string[];
  /** Chain the pool operates on. */
  chainId: string;
  /** Base stablecoin used for capital. */
  baseCurrency: string;
  /** Total value locked in the pool. */
  tvl: string;
  /** Current annualised return. */
  apy: number;
  /** Minimum investment amount. */
  minInvestment: string;
  /** Maximum investment amount. */
  maxInvestment: string;
  /** Lock-up period in days. */
  lockDays: number;
  /** Pool risk category. */
  riskLevel: 'low' | 'medium' | 'high';
  status: 'active' | 'paused' | 'closed';
  /** Capital allocation split across trading strategies. */
  capitalSplit: ForexCapitalSplit[];
  createdAt: string;
}

ForexCapitalSplit

interface ForexCapitalSplit {
  strategyName: string;
  percentage: number;
  description: string;
}

ForexPoolFilters

interface ForexPoolFilters {
  chainId?: string;
  riskLevel?: 'low' | 'medium' | 'high';
  status?: 'active' | 'paused';
  currencyPair?: string;
}

ForexPoolDailySnapshot

interface ForexPoolDailySnapshot {
  poolId: string;
  date: string;
  tvl: string;
  apy: number;
  dailyReturn: number;
  cumulativeReturn: number;
  tradesExecuted: number;
  winRate: number;
  pnl: string;
}

SnapshotOptions

interface SnapshotOptions {
  /** Number of days to look back. Default 30. */
  days?: number;
  /** Start date (ISO 8601). */
  startDate?: string;
  /** End date (ISO 8601). */
  endDate?: string;
}

ForexInvestmentRequest

interface ForexInvestmentRequest {
  /** Pool ID to invest in. */
  poolId: string;
  /** Investment amount in the pool's base currency. */
  amount: string;
  /** Wallet address funding the investment. */
  walletAddress: string;
}

ForexInvestment

interface ForexInvestment {
  id: string;
  poolId: string;
  poolName: string;
  userId: string;
  walletAddress: string;
  /** Original investment amount. */
  investedAmount: string;
  /** Current value of the investment. */
  currentValue: string;
  pnl: string;
  pnlPercentage: number;
  status: 'active' | 'locked' | 'redeeming' | 'redeemed';
  /** Lock-up expiry date. */
  lockExpiresAt: string;
  createdAt: string;
  updatedAt: string;
}

ForexInvestmentFilters

interface ForexInvestmentFilters {
  poolId?: string;
  status?: 'active' | 'locked' | 'redeemed';
  limit?: number;
  cursor?: string;
}

ForexRedemption

interface ForexRedemption {
  investmentId: string;
  redeemedAmount: string;
  fee?: string;
  txHash?: string;
  status: 'processing' | 'completed' | 'failed';
  estimatedCompletionAt: string;
}

ForexTradeRecord

interface ForexTradeRecord {
  id: string;
  poolId: string;
  pair: string;
  side: 'buy' | 'sell';
  amount: string;
  price: string;
  fee: string;
  pnl?: string;
  /** Strategy that generated the trade. */
  strategy: string;
  timestamp: string;
}

ForexTradeHistoryOptions

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

示例

浏览资金池

const res = await engine.getForexPools({ riskLevel: 'medium', status: 'active' });

if (res.success && res.data) {
  for (const pool of res.data) {
    console.log(`${pool.name} | APY: ${pool.apy}% | TVL: $${pool.tvl}`);
    console.log(`  Pairs: ${pool.currencyPairs.join(', ')}`);
    console.log(`  Min: $${pool.minInvestment} | Lock: ${pool.lockDays} days`);
  }
}

查看资金池快照

const res = await engine.getForexPoolSnapshots('pool_abc123', { days: 30 });

if (res.success && res.data) {
  for (const snap of res.data) {
    console.log(`${snap.date} | Return: ${snap.dailyReturn.toFixed(4)}% | Win rate: ${snap.winRate}%`);
  }
}

创建投资

const res = await engine.createForexInvestment({
  poolId: 'pool_abc123',
  amount: '2000',
  walletAddress: '0xABC...',
});

if (res.success && res.data) {
  console.log('Investment created:', res.data.id);
  console.log('Lock expires:', res.data.lockExpiresAt);
}

查看投资

const res = await engine.getForexInvestments({ status: 'active' });

if (res.success && res.data) {
  for (const inv of res.data) {
    console.log(`${inv.poolName} | Invested: $${inv.investedAmount} | Value: $${inv.currentValue}`);
    console.log(`  P&L: $${inv.pnl} (${inv.pnlPercentage.toFixed(2)}%)`);
  }
}

赎回投资

const res = await engine.redeemForexInvestment('inv_xyz789');

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

交易历史

const res = await engine.getForexTradeHistory({
  poolId: 'pool_abc123',
  pair: 'EUR/USD',
  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} | P&L: ${t.pnl ?? '--'}`);
  }
}

后续步骤

• AI Trading API -- AI 驱动的量化交易 Agent。
• Price API -- 免费加密货币价格 endpoint。