API 参考概览

OneEngineClient 是 @one_deploy/sdk v1.1.0 中提供的核心 API 客户端。它提供了 91+ 个方法，涵盖身份验证、钱包、兑换、法币出入金、AI 交易、外汇、合约、NFT、账单、质押、跨链桥、Gas 估算、价格查询、Webhooks、管理员操作和项目管理。

创建客户端

使用 createOneEngineClient 工厂函数来实例化客户端。

import { createOneEngineClient } from '@one_deploy/sdk';

const engine = createOneEngineClient({
  engineUrl: 'https://engine.one23.io',
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

工厂函数签名

function createOneEngineClient(options?: OneEngineClientOptions): OneEngineClient;

配置选项

选项	类型	是否必填	默认值	说明
engineUrl	string	否	https://engine.one23.io	ONE Engine API 的基础 URL。
clientId	string	是	--	从控制面板获取的项目 Client ID。
secretKey	string	是	--	从控制面板获取的项目 Secret Key。

响应模式

每个方法都返回一个类型化的 ApiResponse<T> 封装对象，以便您能一致地处理成功和错误路径。

interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
}

消费响应

const res = await engine.getWalletBalance('0xABC...', ['ethereum']);

if (res.success) {
  console.log('Balances:', res.data);
} else {
  console.error('Error:', res.error);
}

身份验证

大多数 endpoint 需要 Bearer token。在通过邮箱 OTP 或钱包签名完成身份验证后，在客户端实例上调用 setAccessToken。

// After successful auth
engine.setAccessToken(authResponse.accessToken);

所有后续请求将包含以下请求头：

Authorization: Bearer <token>

提示

免费的 Price API endpoint 不需要身份验证。您无需设置 access token 即可调用它们。

基础 URL 配置

默认情况下，客户端指向 https://engine.one23.io。如需连接测试环境或自托管部署，请覆盖此 URL：

const engine = createOneEngineClient({
  engineUrl: 'https://staging-engine.one23.io',
  clientId: 'your-client-id',
  secretKey: 'your-secret-key',
});

错误处理模式

基本 Try/Catch

try {
  const res = await engine.getWalletBalance('0xABC...');
  if (!res.success) {
    // API returned an error payload
    console.error('API error:', res.error);
    return;
  }
  // Use res.data safely
} catch (err) {
  // Network or unexpected error
  console.error('Network error:', err);
}

集中式错误处理器

async function safeCall<T>(fn: () => Promise<ApiResponse<T>>): Promise<T | null> {
  try {
    const res = await fn();
    if (!res.success) {
      console.error('[API Error]', res.error);
      return null;
    }
    return res.data ?? null;
  } catch (err) {
    console.error('[Network Error]', err);
    return null;
  }
}

// Usage
const balance = await safeCall(() => engine.getWalletBalance('0xABC...'));

常见错误字符串

错误	含义
"unauthorized"	Access token 缺失或已过期。请调用 setAccessToken 或重新进行身份验证。
"forbidden"	已验证的用户不具备所需角色（例如管理员）。
"not_found"	请求的资源不存在。
"rate_limited"	已超出项目的速率限制。请退避后重试。
"validation_error"	一个或多个请求参数验证失败。请查看 error 字符串获取详情。
"internal_error"	服务端错误。请使用指数退避策略重试。

方法索引

客户端将其 91+ 个方法划分为以下 API 模块。点击各页面查看完整的参数和返回类型文档。

API 模块	方法数	页面
Auth	6	Auth API
Wallet	7	Wallet API
Swap	5	Swap API
On-ramp / Off-ramp	10	On-ramp & Off-ramp API
AI Trading	18+	AI Trading API
Forex	8+	Forex API
Contracts & NFTs	9	Contracts & NFTs API
Bills & Staking	9	Bills & Staking API
Bridge & Gas	6	Bridge & Gas API
Price（免费）	5	Price API
Webhooks	7	Webhooks API
Admin	11	Admin API
Project	8	Project API

TypeScript 支持

所有请求和响应类型均从包的根路径导出：

import type {
  ApiResponse,
  OneEngineClientOptions,
  EngineAuthResponse,
  EngineWalletBalance,
  SwapQuote,
  // ... all other types
} from '@one_deploy/sdk';

下一步

• Engine Client -- 详细的构造和配置说明。
• Auth API -- 在调用受保护 endpoint 前进行用户身份验证。
• Price API -- 无需身份验证即可使用的免费 endpoint。