Swap API

Swap API 提供 5 个方法，用于获取兑换报价、执行代币兑换、跟踪兑换状态以及查询支持的代币和链。

方法

方法	参数	返回值	说明
getSwapQuote(request)	request: SwapQuoteRequest	ApiResponse<SwapQuote>	获取代币兑换的价格报价，但不执行兑换。
executeSwap(request)	request: SwapExecuteRequest	ApiResponse<SwapResult>	使用之前获取的报价执行代币兑换。
getSwapStatus(swapId)	swapId: string	ApiResponse<SwapResult>	返回进行中或已完成兑换的当前状态。
getSupportedSwapTokens(chainId?)	chainId?: string	ApiResponse<SwapToken[]>	列出可用于兑换的代币，可选按链筛选。
getSupportedSwapChains()	--	ApiResponse<SwapChain[]>	列出支持兑换的所有链。

类型

SwapQuoteRequest

interface SwapQuoteRequest {
  /** Source token contract address. Use "native" for chain-native currency. */
  fromToken: string;
  /** Destination token contract address. Use "native" for chain-native currency. */
  toToken: string;
  /** Amount of source token to swap (human-readable, e.g. "1.5"). */
  amount: string;
  /** Chain ID for the swap. */
  chainId: string;
  /** Wallet address of the sender. */
  senderAddress: string;
  /** Maximum acceptable slippage as a decimal (e.g. 0.005 for 0.5%). */
  slippage?: number;
}

SwapQuote

interface SwapQuote {
  /** Unique quote identifier. Valid for a limited time. */
  quoteId: string;
  fromToken: string;
  toToken: string;
  fromAmount: string;
  /** Estimated amount of destination token to receive. */
  toAmount: string;
  /** Estimated USD value of the output. */
  toAmountUsd: string;
  /** Exchange rate (toToken per fromToken). */
  exchangeRate: string;
  /** Estimated gas fee in native currency. */
  estimatedGas: string;
  /** Estimated gas fee in USD. */
  estimatedGasUsd: string;
  /** Price impact as a decimal. */
  priceImpact: number;
  /** DEX or aggregator route used. */
  route: string;
  /** Quote expiry timestamp (ISO 8601). */
  expiresAt: string;
}

SwapExecuteRequest

interface SwapExecuteRequest {
  /** Quote ID from a previous getSwapQuote call. */
  quoteId: string;
  /** Wallet address executing the swap. */
  senderAddress: string;
  /** Optional: override slippage from the original quote. */
  slippage?: number;
}

SwapResult

interface SwapResult {
  /** Engine-assigned swap ID for status polling. */
  swapId: string;
  /** On-chain transaction hash. */
  txHash?: string;
  status: 'pending' | 'submitted' | 'confirmed' | 'failed';
  fromToken: string;
  toToken: string;
  fromAmount: string;
  /** Actual amount received (set once confirmed). */
  toAmount?: string;
  /** Gas fee paid. */
  gasFee?: string;
  /** Timestamp of completion. */
  completedAt?: string;
}

SwapToken

interface SwapToken {
  address: string;
  symbol: string;
  name: string;
  decimals: number;
  chainId: string;
  logoUrl?: string;
}

SwapChain

interface SwapChain {
  chainId: string;
  name: string;
  nativeSymbol: string;
  logoUrl?: string;
}

示例

获取兑换报价

const quoteRes = await engine.getSwapQuote({
  fromToken: 'native',
  toToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
  amount: '1.0',
  chainId: 'ethereum',
  senderAddress: '0xABC...',
  slippage: 0.005,
});

if (quoteRes.success && quoteRes.data) {
  const q = quoteRes.data;
  console.log(`Swap 1 ETH -> ~${q.toAmount} USDC`);
  console.log(`Rate: ${q.exchangeRate} | Gas: $${q.estimatedGasUsd}`);
  console.log(`Price impact: ${(q.priceImpact * 100).toFixed(2)}%`);
}

执行兑换

const execRes = await engine.executeSwap({
  quoteId: quoteRes.data!.quoteId,
  senderAddress: '0xABC...',
});

if (execRes.success && execRes.data) {
  console.log('Swap submitted:', execRes.data.swapId);
}

轮询兑换状态

let swap = execRes.data!;
while (swap.status !== 'confirmed' && swap.status !== 'failed') {
  await new Promise(r => setTimeout(r, 3000));
  const poll = await engine.getSwapStatus(swap.swapId);
  if (poll.success && poll.data) {
    swap = poll.data;
    console.log('Swap status:', swap.status);
  }
}

if (swap.status === 'confirmed') {
  console.log(`Received ${swap.toAmount} tokens. Tx: ${swap.txHash}`);
}

列出支持的代币

const tokensRes = await engine.getSupportedSwapTokens('ethereum');

if (tokensRes.success && tokensRes.data) {
  for (const t of tokensRes.data) {
    console.log(`${t.symbol} (${t.name}) - ${t.address}`);
  }
}

列出支持的链

const chainsRes = await engine.getSupportedSwapChains();

if (chainsRes.success && chainsRes.data) {
  for (const c of chainsRes.data) {
    console.log(`${c.name} (${c.chainId}) - native: ${c.nativeSymbol}`);
  }
}

下一步

• On-ramp & Off-ramp API -- 使用法币购买加密货币或将加密货币兑现为法币。
• Bridge & Gas API -- 跨链桥接代币。