跳至主要内容

Hooks 概览

ONE SDK（@one_deploy/sdk v1.1.0）导出 27+ 个 React hooks，按上下文需求分为四个类别。了解 hook 所属的类别，有助于确定如何设置以及在哪里使用它。

Hook 类别​

1. Provider 类 Hooks​

这些 hooks 从 OneProvider（或 OneThirdwebProvider）React 上下文中读取数据。它们 仅支持 Web，如果在 provider 树之外调用将抛出异常。

Hook用途
useOne核心 SDK 上下文——配置、engine 客户端、认证状态
useOneAuth邮箱 OTP / 钱包签名认证、会话管理
useOneWallet当前活跃钱包地址、链、余额
useOneOnramp法币入金报价、订单创建
useOneSwap代币兑换报价、执行、路由预览
useOneTradingAI 交易订单、策略、投资组合（通过 provider）
useOneEngine直接访问 OneEngineClient 实例
useThirdwebClient从 OneThirdwebProvider 访问 Thirdweb 客户端实例
import { OneProvider } from '@one_deploy/sdk';

// Provider-based hooks MUST be rendered inside OneProvider
function App() {
  return (
    <OneProvider
      config={{
        apiKey: 'YOUR_API_KEY',
        projectId: 'YOUR_PROJECT_ID',
      }}
    >
      <MyPage />
    </OneProvider>
  );
}

详见 Provider Hooks 获取完整签名和示例。

2. 独立 Hooks​

这些 hooks 不需要 provider。它们直接调用 ONE Engine API，可以在 React 树中的任意位置使用——无论是 provider 内外，还是 Web 或 React Native。

Hook用途
useWalletBalance获取任意钱包地址的原生代币和 ERC-20 代币余额
useTokenPrice单个代币符号的实时价格
useTokenPrices多个代币符号的批量价格查询
import { useWalletBalance } from '@one_deploy/sdk';

// Works anywhere -- no provider needed
function QuickBalance({ address }: { address: string }) {
  const { balances, totalUsd, isLoading } = useWalletBalance(address);

  if (isLoading) return <span>Loading...</span>;
  return <span>${totalUsd}</span>;
}

详见 useWalletBalance 和 useTokenPrice & useTokenPrices。

3. AI 交易 Hooks​

六个 hooks 加上独立的 token 管理函数。这些 不会 从 OneProvider 读取数据——它们通过 setAITradingAccessToken 管理自己的认证 token。

Hook用途
useAIStrategies列出和筛选可用的 AI 交易策略
useAIStrategy按 ID 获取单个策略
useAIOrders查询当前和历史 AI 交易订单
useAIPortfolio汇总的投资组合指标和盈亏
useAIMarketData支持交易对的实时市场数据
useAITrading组合 hook——创建、取消和管理 AI 订单

Token 管理函数：

函数用途
setAITradingAccessToken(token)为所有 AI 交易 API 调用设置 bearer token
clearAITradingAccessToken()清除 token（例如登出时）
import { setAITradingAccessToken, useAIStrategies } from '@one_deploy/sdk';

// Set token once after auth
setAITradingAccessToken('eyJhbGciOiJIUzI1NiIs...');

// Then use hooks anywhere -- no provider required
function Strategies() {
  const { strategies, isLoading } = useAIStrategies();
  // ...
}

详见 AI 交易 Hooks。

4. 外汇 Hooks​

五个 hooks，拥有自己的独立 token 管理。主要为 React Native 设计，但在 Web 上同样可用。

Hook用途
useForexPools列出所有外汇流动性池（清算池、对冲池、保险池）
useForexInvestments用户投资头寸和周期管理
useForexSimulation在客户端运行资金池模拟
useForexPoolData单个资金池的每日详细指标
useForexTrading组合 hook——创建和管理外汇头寸

Token 管理函数：

函数用途
setForexAccessToken(token)为所有外汇 API 调用设置 bearer token
clearForexAccessToken()清除外汇 token
setForexEngineUrl(url)为外汇 API 调用设置 ONE Engine URL
import { setForexAccessToken, setForexEngineUrl, useForexPools } from '@one_deploy/sdk';

// Configure once
setForexEngineUrl('https://engine.one23.io');
setForexAccessToken('eyJhbGciOiJIUzI1NiIs...');

// Then use hooks anywhere
function Pools() {
  const { pools, isLoading } = useForexPools();
  // ...
}

详见 外汇 Hooks。

Provider 类与独立类的比较​

Provider 类和独立类 hooks 之间的关键区别在于 它们如何获取配置和认证信息。

方面Provider 类独立类
设置将应用包裹在 OneProvider 或 OneThirdwebProvider 中直接调用 token 设置函数
认证来源自动从 provider 上下文读取通过 setXxxAccessToken() 手动提供 token
平台仅 Web（React DOM）Web 和 React Native
树中位置必须是 provider 的子组件React 树中的任意位置
多实例共享单个上下文每个 hook 实例独立请求
缺少上下文时的错误抛出 "useOne must be used within OneProvider"在结果中返回 UNAUTHORIZED 错误

何时使用 Provider Hooks​

当你正在构建一个 Web 应用，并且已经在根节点包裹了 OneProvider 时，请使用 provider 类 hooks。Provider 会为你管理单个 OneEngineClient 实例、认证状态和 Thirdweb 客户端。

何时使用独立 Hooks​

在以下情况使用独立 hooks：

  • 你正在构建 React Native 应用（provider 仅支持 Web）。
  • 你需要在 provider 树 之外 获取钱包余额或价格数据。
  • 你希望使用 AI 交易或外汇功能，而不采用完整的 provider 模式。
  • 你正在构建 微前端 或小组件，无法假设存在父级 provider。

平台兼容性​

Hook 类别Web (React DOM)React NativeNode / Edge
Provider hooks是----
独立 hooks是是--
AI 交易 hooks是是--
外汇 hooks是是--
提示

所有 hooks 都是 React hooks，需要 React 运行时环境。如需服务端或 Node 环境使用，请直接使用 OneEngineClient 或 service 类，而非 hooks。

下一步​