Forex Overview

The ONE SDK (@one_deploy/sdk v1.1.0) ships a full on-chain forex module called StableFX. StableFX enables forex-style trading using stablecoins as the settlement layer, combining traditional FX market mechanics with DeFi liquidity pools.

StableFX Concept

Traditional forex trading requires fiat bank rails, prime brokerage relationships, and centralized clearing. StableFX replaces all of that with on-chain stablecoin settlement:

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

Users trade currency pairs (e.g. EUR/USD) denominated in stablecoins. All settlement, hedging, and insurance happens on-chain through three dedicated liquidity pools.

Architecture

+------------------------------------------------------------------+
|                        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-Pool Architecture

StableFX distributes capital across three specialized pools, each serving a distinct role in the trading lifecycle:

Pool	Type	Purpose
Clearing Pool	'clearing'	Settles completed trades. Holds stablecoins during the RFQ-to-settlement lifecycle.
Hedging Pool	'hedging'	Absorbs directional risk. Automatically rebalances when net exposure exceeds thresholds.
Insurance Pool	'insurance'	Backstops losses from failed settlements or extreme market events. Funded by a portion of trading fees.

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

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

Capital Allocation -- the 50/50 Model

Every deposit into StableFX is split using the FOREX_CAPITAL_SPLIT constant: 50% goes to active trading capital and 50% goes to pool reserves. This ensures that pools always maintain adequate liquidity for settlement, hedging, and insurance.

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

See Capital Allocation for the full breakdown and utility functions.

Supported Currency Pairs

StableFX supports 6 major currency pairs:

Pair	Base	Quote
EUR/USD	Euro	US Dollar
GBP/USD	British Pound	US Dollar
USD/JPY	US Dollar	Japanese Yen
USD/CHF	US Dollar	Swiss Franc
AUD/USD	Australian Dollar	US Dollar
USD/CAD	US Dollar	Canadian Dollar

See Currency Pairs for the FOREX_CURRENCY_PAIRS constant and ForexCurrencyPair type.

Standalone Token Management

Forex Does Not Use OneProvider

Unlike the wallet and payments modules, forex hooks use their own standalone token management. You do not wrap your app in OneProvider or OneThirdwebProvider for forex functionality. Instead, you set an access token and engine URL directly.

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();

Why Standalone?

Forex components are designed for React Native where the provider model used by the web widgets does not apply. The standalone token functions allow you to integrate forex into any React Native navigation structure without nesting providers.

Function Signatures

/** 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;

Core Types

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;
}

Forex Hooks

Hook	Purpose
useForexPools	List all forex liquidity pools
useForexInvestments	User investment positions and cycle management
useForexSimulation	Run pool simulations client-side
useForexPoolData	Detailed daily metrics for a single pool
useForexTrading	Create and manage forex positions

React Native Components

All forex UI components are React Native only. They are exported from @one_deploy/sdk/react-native.

Component	Purpose
OneForexPoolCard	Displays pool statistics (TVL, APY, utilization)
OneForexCapitalSplit	Visualizes the 50/50 capital allocation
OneForexConsoleView	Real-time trading log display
OneForexPairSelector	Currency pair selection UI
OneForexTradeHistory	Trade records with status tracking

Next Steps

• Capital Allocation -- understand the 50/50 split model.
• Pool System -- deep dive into the 3-pool architecture.
• Currency Pairs -- supported pairs and configuration.
• Creating Investments -- open forex positions.
• Pool Metrics -- fetch daily snapshots and analytics.
• Trade History -- track trade lifecycle and status.
• Console View -- build a real-time trading console.