Hooks Overview

The ONE SDK (@one_deploy/sdk v1.1.0) exports 27+ React hooks organized into four categories based on their context requirements. Understanding which category a hook belongs to determines how you set it up and where you can use it.

Hook Categories

1. Provider-based Hooks

These hooks read from the OneProvider (or OneThirdwebProvider) React context. They are web-only and will throw if called outside a provider tree.

Hook	Purpose
useOne	Core SDK context -- config, engine client, auth state
useOneAuth	Email OTP / wallet-signature auth, session management
useOneWallet	Active wallet address, chain, balances
useOneOnramp	Fiat on-ramp quotes, order creation
useOneSwap	Token swap quotes, execution, route previews
useOneTrading	AI trading orders, strategies, portfolio (via provider)
useOneEngine	Direct access to the OneEngineClient instance
useThirdwebClient	Access the Thirdweb client instance from OneThirdwebProvider

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

See Provider Hooks for full signatures and examples.

2. Standalone Hooks

These hooks require no provider. They call the ONE Engine API directly and can be used anywhere in your React tree -- inside or outside a provider, on web or React Native.

Hook	Purpose
useWalletBalance	Fetch native + ERC-20 token balances for any wallet address
useTokenPrice	Real-time price for a single token symbol
useTokenPrices	Batch price lookup for multiple token symbols

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

See useWalletBalance and useTokenPrice & useTokenPrices.

3. AI Trading Hooks

Six hooks plus standalone token management functions. These do not read from OneProvider -- they manage their own auth token via setAITradingAccessToken.

Hook	Purpose
useAIStrategies	List and filter available AI trading strategies
useAIStrategy	Fetch a single strategy by ID
useAIOrders	Query open and historical AI trading orders
useAIPortfolio	Aggregated portfolio metrics and P&L
useAIMarketData	Live market data for supported trading pairs
useAITrading	Combined hook -- create, cancel, and manage AI orders

Token management functions:

Function	Purpose
setAITradingAccessToken(token)	Set the bearer token for all AI trading API calls
clearAITradingAccessToken()	Clear the token (e.g. on logout)

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();
  // ...
}

See AI Trading Hooks.

4. Forex Hooks

Five hooks with their own standalone token management. Designed primarily for React Native but work on web as well.

Hook	Purpose
useForexPools	List all forex liquidity pools (clearing, hedging, insurance)
useForexInvestments	User investment positions and cycle management
useForexSimulation	Run pool simulations client-side
useForexPoolData	Detailed daily metrics for a single pool
useForexTrading	Combined hook -- create and manage forex positions

Token management functions:

Function	Purpose
setForexAccessToken(token)	Set the bearer token for all forex API calls
clearForexAccessToken()	Clear the forex token
setForexEngineUrl(url)	Set the ONE Engine URL for forex API calls

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();
  // ...
}

See Forex Hooks.

Provider-based vs Standalone

The key difference between provider-based and standalone hooks is how they obtain configuration and authentication.

Aspect	Provider-based	Standalone
Setup	Wrap app in OneProvider or OneThirdwebProvider	Call token-setter functions directly
Auth source	Reads from provider context automatically	You supply the token via setXxxAccessToken()
Platform	Web only (React DOM)	Web and React Native
Tree position	Must be a descendant of the provider	Anywhere in the React tree
Multiple instances	Share a single context	Each hook instance fetches independently
Error on missing context	Throws "useOne must be used within OneProvider"	Returns UNAUTHORIZED error in the result

When to Use Provider Hooks

Use provider-based hooks when you are building a web application that already wraps the root in OneProvider. The provider manages a single OneEngineClient instance, auth state, and Thirdweb client for you.

When to Use Standalone Hooks

Use standalone hooks when:

• You are building a React Native app (providers are web-only).
• You need wallet balance or price data outside the provider tree.
• You want to use AI trading or forex features without adopting the full provider model.
• You are building a micro-frontend or widget that cannot assume a parent provider.

Platform Compatibility

Hook Category	Web (React DOM)	React Native	Node / Edge
Provider hooks	Yes	--	--
Standalone hooks	Yes	Yes	--
AI Trading hooks	Yes	Yes	--
Forex hooks	Yes	Yes	--

tip

All hooks are React hooks and require a React runtime. For server-side or Node usage, use OneEngineClient or the service classes directly instead of hooks.

Next Steps

• Provider Hooks -- useOne, useOneAuth, useOneWallet, and more.
• useWalletBalance -- standalone balance fetching.
• useTokenPrice & useTokenPrices -- standalone price feeds.
• AI Trading Hooks -- strategy discovery, order management, portfolio.
• Forex Hooks -- pools, investments, simulations, trading.