Skip to main content

Forex API

The Forex API exposes methods for interacting with on-chain forex liquidity pools. It covers pool discovery, investment creation and management, capital allocation, daily snapshots, and trade history.

Pool Methods​

MethodParametersReturnsDescription
getForexPools(filters?)filters?: ForexPoolFiltersApiResponse<ForexPool[]>Lists available forex liquidity pools, optionally filtered.
getForexPool(poolId)poolId: stringApiResponse<ForexPool>Returns details for a single forex pool.
getForexPoolSnapshots(poolId, options?)poolId: string, options?: SnapshotOptionsApiResponse<ForexPoolDailySnapshot[]>Returns daily performance snapshots for a pool.

Investment Methods​

MethodParametersReturnsDescription
createForexInvestment(request)request: ForexInvestmentRequestApiResponse<ForexInvestment>Creates a new investment in a forex pool.
getForexInvestments(filters?)filters?: ForexInvestmentFiltersApiResponse<ForexInvestment[]>Lists the user's forex investments.
getForexInvestment(investmentId)investmentId: stringApiResponse<ForexInvestment>Returns details for a single investment.
redeemForexInvestment(investmentId)investmentId: stringApiResponse<ForexRedemption>Initiates withdrawal from a forex pool.

Trade Methods​

MethodParametersReturnsDescription
getForexTradeHistory(options?)options?: ForexTradeHistoryOptionsApiResponse<ForexTradeRecord[]>Returns trade records executed by forex pool agents.

Types​

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

Examples​

Browse Pools​

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

View Pool Snapshots​

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

Create an Investment​

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

View Investments​

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

Redeem an Investment​

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

Trade History​

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 ?? '--'}`);
  }
}

Next Steps​