价格 API（免费）

价格 API 提供了 5 个 endpoint，用于获取加密货币价格和市场数据。这些 endpoint 是免费的，不需要认证——你无需设置 access token 即可调用。

提示

这些方法在创建 engine 客户端后即可立即使用。无需调用 setAccessToken。

方法

方法	参数	返回值	描述
getCryptoPrices(symbols)	symbols: string[]	ApiResponse<TokenPrice[]>	在单次请求中返回多个代币的当前价格。
getCryptoPrice(symbol)	symbol: string	ApiResponse<TokenPrice>	返回单个代币的当前价格。
getCryptoCandles(symbol, interval?, limit?)	symbol: string, interval?: CandleInterval, limit?: number	ApiResponse<CryptoCandle[]>	返回代币的 OHLCV K 线数据。
getTopCryptos(limit?)	limit?: number	ApiResponse<TokenPrice[]>	返回按市值排名的热门加密货币。
getCryptoMarketOverview()	--	ApiResponse<MarketOverview>	返回市场汇总统计数据。

类型

TokenPrice

interface TokenPrice {
  symbol: string;
  name: string;
  /** Current price in USD. */
  priceUsd: string;
  /** 1-hour price change percentage. */
  change1h: number;
  /** 24-hour price change percentage. */
  change24h: number;
  /** 7-day price change percentage. */
  change7d: number;
  /** 24-hour trading volume in USD. */
  volume24h: string;
  /** Market capitalisation in USD. */
  marketCap: string;
  /** Market cap rank. */
  rank?: number;
  /** Token logo URL. */
  logoUrl?: string;
  /** Last updated timestamp. */
  updatedAt: string;
}

CandleInterval

type CandleInterval =
  | '1m'
  | '5m'
  | '15m'
  | '30m'
  | '1h'
  | '4h'
  | '1d'
  | '1w';

CryptoCandle

interface CryptoCandle {
  /** Candle open timestamp (ISO 8601). */
  timestamp: string;
  /** Open price. */
  open: string;
  /** High price. */
  high: string;
  /** Low price. */
  low: string;
  /** Close price. */
  close: string;
  /** Trading volume during the candle period. */
  volume: string;
}

MarketOverview

interface MarketOverview {
  /** Total crypto market capitalisation in USD. */
  totalMarketCap: string;
  /** 24-hour total trading volume. */
  totalVolume24h: string;
  /** Bitcoin dominance percentage. */
  btcDominance: number;
  /** Ethereum dominance percentage. */
  ethDominance: number;
  /** Number of tracked cryptocurrencies. */
  totalCryptos: number;
  /** Number of active exchanges. */
  totalExchanges: number;
  /** Market-wide 24h change percentage. */
  marketChange24h: number;
  /** Last updated timestamp. */
  updatedAt: string;
}

示例

获取多个代币价格

const engine = createOneEngineClient({
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

// No setAccessToken needed for price endpoints

const res = await engine.getCryptoPrices(['BTC', 'ETH', 'SOL', 'USDC']);

if (res.success && res.data) {
  for (const token of res.data) {
    console.log(`${token.symbol}: $${token.priceUsd} (${token.change24h > 0 ? '+' : ''}${token.change24h.toFixed(2)}%)`);
  }
}

获取单个代币价格

const res = await engine.getCryptoPrice('ETH');

if (res.success && res.data) {
  const t = res.data;
  console.log(`ETH: $${t.priceUsd}`);
  console.log(`  1h: ${t.change1h.toFixed(2)}%`);
  console.log(`  24h: ${t.change24h.toFixed(2)}%`);
  console.log(`  7d: ${t.change7d.toFixed(2)}%`);
  console.log(`  Market cap: $${t.marketCap}`);
}

获取 K 线数据

const res = await engine.getCryptoCandles('BTC', '1h', 24);

if (res.success && res.data) {
  for (const c of res.data) {
    console.log(`${c.timestamp} | O:${c.open} H:${c.high} L:${c.low} C:${c.close} V:${c.volume}`);
  }
}

热门加密货币

const res = await engine.getTopCryptos(10);

if (res.success && res.data) {
  for (const t of res.data) {
    console.log(`#${t.rank} ${t.symbol} - $${t.priceUsd} | MCap: $${t.marketCap}`);
  }
}

市场概览

const res = await engine.getCryptoMarketOverview();

if (res.success && res.data) {
  const m = res.data;
  console.log(`Total market cap: $${m.totalMarketCap}`);
  console.log(`24h volume: $${m.totalVolume24h}`);
  console.log(`BTC dominance: ${m.btcDominance.toFixed(1)}%`);
  console.log(`ETH dominance: ${m.ethDominance.toFixed(1)}%`);
  console.log(`Market 24h change: ${m.marketChange24h > 0 ? '+' : ''}${m.marketChange24h.toFixed(2)}%`);
}

速率限制

价格 API endpoint 免费使用，但受速率限制约束：

等级	每分钟请求数
免费（无认证）	30
已认证	120
Pro 计划	600

如果超过速率限制，API 将返回 "rate_limited" 错误。请实现指数退避策略或在客户端缓存结果以控制在限制范围内。

后续步骤

• Swap API -- 使用实时价格数据执行代币兑换。
• AI Trading API -- AI Agent 使用实时定价进行交易决策。