外汇概览

ONE SDK（@one_deploy/sdk v1.1.0）提供了一个完整的链上外汇模块，称为 StableFX。StableFX 使用稳定币作为结算层实现外汇风格的交易，将传统外汇市场机制与 DeFi 流动性池相结合。

StableFX 概念

传统外汇交易需要法币银行通道、主经纪商关系和集中清算。StableFX 用链上稳定币结算替代了所有这些：

Traditional Forex                       StableFX
+-----------------+                     +-----------------+
| Bank / Broker   |                     | Smart Contracts |
| Fiat settlement |                     | USDC/USDT pairs |
| T+2 clearing    |                     | Instant settle  |
| Margin accounts |                     | Pool-backed     |
+-----------------+                     +-----------------+

用户交易以稳定币计价的货币对（例如 EUR/USD）。所有结算、对冲和保险都通过三个专用流动性池在链上完成。

架构

+------------------------------------------------------------------+
|                        Your Application                          |
+------------------------------------------------------------------+
|  Forex Hooks              |  React Native Components             |
|  - useForexPools          |  - OneForexPoolCard                  |
|  - useForexInvestments    |  - OneForexCapitalSplit              |
|  - useForexSimulation     |  - OneForexConsoleView               |
|  - useForexPoolData       |  - OneForexPairSelector              |
|  - useForexTrading        |  - OneForexTradeHistory              |
+------------------------------------------------------------------+
|                     @one_deploy/sdk                               |
|  +-----------+  +------------------+  +-----------------------+  |
|  | Hooks     |  | Services         |  | Utils                 |  |
|  | (5 forex) |  | forexSimulation  |  | computePoolAllocations|  |
|  |           |  | Engine           |  | FOREX_CAPITAL_SPLIT   |  |
|  +-----------+  +------------------+  +-----------------------+  |
+------------------------------------------------------------------+
         |                    |
         v                    v
   ONE Engine API        Stablecoin Pools
   engine.one23.io       (clearing, hedging, insurance)

3 池架构

StableFX 将资金分配到三个专用池中，每个池在交易生命周期中承担不同的角色：

池	类型	用途
清算池	`'clearing'`	结算已完成的交易。在 RFQ 到结算的生命周期内持有稳定币。
对冲池	`'hedging'`	吸收方向性风险。当净敞口超过阈值时自动重新平衡。
保险池	`'insurance'`	为失败结算或极端市场事件造成的损失提供保障。由交易手续费的一部分资助。

import type { ForexPoolType } from '@one_deploy/sdk';

// The pool type is a union of three literal strings
type ForexPoolType = 'clearing' | 'hedging' | 'insurance';

资金分配 -- 50/50 模型

每笔存入 StableFX 的资金都使用 FOREX_CAPITAL_SPLIT 常量进行分配：50% 用于活跃交易资金，50% 用于池储备金。这确保了池始终保持足够的流动性用于结算、对冲和保险。

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

console.log(FOREX_CAPITAL_SPLIT); // 0.5

// For a $10,000 deposit:
// - $5,000 allocated to trading
// - $5,000 allocated to pool reserves

详见资金分配获取完整的分配说明和实用函数。

支持的货币对

StableFX 支持 6 种主要货币对：

货币对	基础货币	报价货币
EUR/USD	欧元	美元
GBP/USD	英镑	美元
USD/JPY	美元	日元
USD/CHF	美元	瑞士法郎
AUD/USD	澳元	美元
USD/CAD	美元	加元

详见货币对了解 FOREX_CURRENCY_PAIRS 常量和 ForexCurrencyPair 类型。

独立令牌管理

外汇不使用 OneProvider

与钱包和支付模块不同，外汇 hook 使用其自身的独立令牌管理。你不需要将应用包裹在 OneProvider 或 OneThirdwebProvider 中来使用外汇功能。相反，你可以直接设置访问令牌和引擎 URL。

import {
  setForexAccessToken,
  clearForexAccessToken,
  setForexEngineUrl,
} from '@one_deploy/sdk';

// 1. Point to your engine instance
setForexEngineUrl('https://engine.one23.io');

// 2. Set the user's access token (obtained from your auth flow)
setForexAccessToken('eyJhbGciOiJIUzI1NiIs...');

// 3. Now all forex hooks and services will use this token
//    No provider wrapper needed

// 4. On logout, clear the token
clearForexAccessToken();

为什么采用独立模式？

外汇组件专为 React Native 设计，在此环境中 Web 小部件使用的 provider 模式不适用。独立令牌函数允许你将外汇功能集成到任何 React Native 导航结构中，无需嵌套 provider。

函数签名

/** Set the access token used by all forex hooks and services. */
function setForexAccessToken(token: string): void;

/** Clear the current forex access token (e.g. on logout). */
function clearForexAccessToken(): void;

/** Set the ONE Engine URL for forex API calls. */
function setForexEngineUrl(url: string): void;

核心类型

ForexPool

interface ForexPool {
  id: string;
  type: ForexPoolType;
  totalValueLocked: number;
  apy: number;
  utilization: number;
  currency: string;
  createdAt: string;
  updatedAt: string;
}

ForexPoolTransaction

interface ForexPoolTransaction {
  id: string;
  poolId: string;
  type: 'deposit' | 'withdrawal' | 'fee' | 'rebalance';
  amount: number;
  currency: string;
  timestamp: string;
  txHash?: string;
}

外汇 Hook

Hook	用途
`useForexPools`	列出所有外汇流动性池
`useForexInvestments`	用户投资仓位和周期管理
`useForexSimulation`	在客户端运行池模拟
`useForexPoolData`	单个池的详细每日指标
`useForexTrading`	创建和管理外汇仓位

React Native 组件

所有外汇 UI 组件仅适用于 React Native。它们从 @one_deploy/sdk/react-native 导出。

组件	用途
`OneForexPoolCard`	显示池统计数据（TVL、APY、利用率）
`OneForexCapitalSplit`	可视化 50/50 资金分配
`OneForexConsoleView`	实时交易日志显示
`OneForexPairSelector`	货币对选择 UI
`OneForexTradeHistory`	带状态追踪的交易记录

后续步骤

资金分配 -- 了解 50/50 分配模型。
池系统 -- 深入了解 3 池架构。
货币对 -- 支持的货币对和配置。
创建投资 -- 开立外汇仓位。
池指标 -- 获取每日快照和分析数据。
交易历史 -- 追踪交易生命周期和状态。
控制台视图 -- 构建实时交易控制台。

StableFX 概念​

架构​

3 池架构​

资金分配 -- 50/50 模型​

支持的货币对​

独立令牌管理​

为什么采用独立模式？​

函数签名​

核心类型​

ForexPool​

ForexPoolTransaction​

外汇 Hook​

React Native 组件​

后续步骤​