orderly-sdk-react-hooks

Orderly Network：SDK React Hooks 参考

@orderly.network/hooks 导出的 Hooks 参考。以下所有签名均已根据已安装的类型定义（SDK 3.1.x）验证。

适用场景

• 使用 Orderly 构建 React 应用
• 快速查阅 Hook 签名和返回值
• 基于 SDK 实现自定义交易/账户 UI

前置条件

• React 18+
• 已安装 @orderly.network/react-app 和 @orderly.network/hooks
• 使用 OrderlyAppProvider（来自 @orderly.network/react-app）包裹应用

Hooks 由 @orderly.network/hooks 提供，但只有在 OrderlyAppProvider（来自 @orderly.network/react-app，而非 @orderly.network/react）内部才能使用。QueryClientProvider 由 OrderlyAppProvider 在内部管理，请勿自行添加。

设置

import { OrderlyAppProvider } from '@orderly.network/react-app';

function App() {
  return (
    <OrderlyAppProvider
      brokerId="your_broker_id" // falls back to "demo" if unset
      networkId="mainnet"
      chainFilter={{
        // keyed by network, each value: [{ id }]
        mainnet: [{ id: 42161 }, { id: 10 }],
        testnet: [{ id: 421614 }],
      }}
      defaultChain={{ mainnet: { id: 42161 } }}
    >
      <YourApp />
    </OrderlyAppProvider>
  );
}

---

账户 Hooks

useAccount

账户实例和状态。state.status 是一个 AccountStatusEnum（来自 @orderly.network/types），而非字符串。

import { useAccount } from '@orderly.network/hooks';
import { AccountStatusEnum } from '@orderly.network/types';

const { account, state, createOrderlyKey, createAccount, switchAccount } = useAccount();

// state.status values (AccountStatusEnum):
//   NotConnected=0, Connected=1, NotSignedIn=2,
//   SignedIn=3, EnableTrading=5, DisabledTrading=4

// Example
function AccountInfo() {
  const { account, state, createAccount, createOrderlyKey } = useAccount();

  if (state.status < AccountStatusEnum.Connected) {
    return <ConnectWalletButton />;
  }
  if (state.status < AccountStatusEnum.NotSignedIn) {
    return <button onClick={() => createAccount()}>Create Account</button>;
  }
  if (state.status < AccountStatusEnum.EnableTrading) {
    return <button onClick={() => createOrderlyKey()}>Enable Trading</button>;
  }
  return <p>Account: {account.accountId}</p>;
}

useWalletConnector

钱包连接状态和操作。返回值是扁平结构——connect、disconnect、wallet 等都位于顶层（不嵌套在 wallet 下）。

import { useWalletConnector } from '@orderly.network/hooks';

const {
  connect, // (options?) => Promise<WalletState[]>
  disconnect, // (options)  => Promise<any[]>
  connecting, // boolean
  wallet, // WalletState | null
  connectedChain, // ConnectedChain | null
  setChain, // ({ chainId }) => Promise<any>
  chains, // available chains
  settingChain, // boolean
  namespace, // "evm" | "solana" | null
} = useWalletConnector();

// Example
function WalletButton() {
  const { connect, disconnect, connecting, wallet } = useWalletConnector();
  if (connecting) return <span>Connecting…</span>;
  if (wallet) {
    return <button onClick={() => disconnect({})}>Disconnect</button>;
  }
  return <button onClick={() => connect({})}>Connect Wallet</button>;
}

---

交易 Hooks

useOrderEntry

为某个交易对创建并提交订单。当前使用的重载是 useOrderEntry(symbol, options?)。使用 setValue 设置订单字段（字段包括：side、order_type、order_price、order_quantity、reduce_only、tp_trigger_price、sl_price 等），然后调用 submit()。

import { useOrderEntry } from '@orderly.network/hooks';
import { OrderSide, OrderType } from '@orderly.network/types';

const {
  submit, // (opts?: { resetOnSuccess? }) => Promise<{ success, data, timestamp }>
  setValue, // (key: keyof FullOrderState, value, options?) => void
  setValues, // (Partial<FullOrderState>) => void
  setValuesRaw, // merge setter that skips calculate() (for advanced TPSL)
  reset,
  resetErrors,
  resetMetaState,
  formattedOrder, // Partial<FullOrderState> — the computed order
  maxQty,
  maxQtys, // { maxBuy, maxSell }
  estLiqPrice, // number | null
  estLeverage, // number | null
  currentPosition, // signed qty (+ long, - short)
  freeCollateral,
  symbolInfo, // API.SymbolExt
  helper: { validate, validator /* @deprecated → validate */ },
  metaState, // { dirty, submitted, validated, errors: OrderValidationResult | null }
  isMutating, // submission in progress (NOT "isSubmitting")
  markPrice,
  symbolLeverage,
} = useOrderEntry('PERP_BTC_USDC');

// Example
function OrderForm({ symbol }: { symbol: string }) {
  const { submit, setValue, helper, isMutating, metaState } = useOrderEntry(symbol);

  useEffect(() => {
    setValue('side', OrderSide.BUY);
    setValue('order_type', OrderType.LIMIT);
  }, [symbol]);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    const result = await helper.validate();
    if (result) return; // validation errors are in metaState.errors
    await submit({ resetOnSuccess: true });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input placeholder="Price" onChange={(e) => setValue('order_price', e.target.value)} />
      <input placeholder="Quantity" onChange={(e) => setValue('order_quantity', e.target.value)} />
      <button type="submit" disabled={isMutating}>
        {isMutating ? 'Placing…' : 'Place Order'}
      </button>
    </form>
  );
}

useOrderStream

订阅订单流，并提供取消/更新操作。返回一个只读元组 [orders, actions]。

import { useOrderStream } from '@orderly.network/hooks';
import { OrderStatus } from '@orderly.network/types';

const [
  orders,
  {
    total,
    isLoading,
    refresh,
    loadMore,
    cancelOrder, // (orderId, symbol?) => Promise<any>
    cancelAllOrders, // () => Promise<[any, any, any]>
    cancelAllPendingOrders, // (symbol?) => Promise<[any,any,any]>
    cancelAllTPSLOrders, // (symbol?) => Promise<any[]>
    cancelAlgoOrder, // (orderId, symbol?) => Promise<any>
    updateOrder, // (orderId, OrderEntity) => Promise<any>
    updateAlgoOrder,
    updateTPSLOrder,
    meta, // { total, current_page, records_per_page }
    errors,
    submitting,
  },
] = useOrderStream({
  status: OrderStatus.INCOMPLETE, // use the enum, not the string 'OPEN'
  symbol, // optional, omit for all symbols
  side,
  page,
  size,
  includes,
  excludes, // CombineOrderType[], filter by type
  dateRange: { from, to },
});

// Example
function OpenOrders({ symbol }: { symbol?: string }) {
  const [orders, { cancelOrder, cancelAllPendingOrders, isLoading }] = useOrderStream({
    status: OrderStatus.INCOMPLETE,
    symbol,
  });

  return (
    <div>
      <button onClick={() => cancelAllPendingOrders(symbol)}>Cancel All</button>
      {(orders ?? []).map((o) => (
        <div key={o.order_id}>
          {o.symbol} {o.side} {o.order_quantity} @ {o.order_price}
          <button onClick={() => cancelOrder(o.order_id, o.symbol)}>✕</button>
        </div>
      ))}
    </div>
  );
}

---

持仓 Hooks

usePositionStream

订阅持仓流，并获取实时 PnL。返回一个三元组 [positions, calc, status]，而非单个对象。

import { usePositionStream } from '@orderly.network/hooks';

const [
  positions,   // { rows: API.PositionTPSLExt[], aggregated }
  calc,         // accessor fns for margin/pnl fields (see below)
  { isLoading },
] = usePositionStream(symbol?, options?);

// positions.aggregated: aggregate stats across all rows
// positions.rows[i]: { symbol, position_qty, average_open_price, mark_price,
//   unrealized_pnl, unrealized_pnl_roi, leverage, liq_price, mmr, imr, notional, ... }

// Example
function PositionsSummary() {
  const [positions, , { isLoading }] = usePositionStream();
  return (
    <table>
      {(positions?.rows ?? []).map((p) => (
        <tr key={p.symbol}>
          <td>{p.symbol}</td>
          <td>{p.position_qty}</td>
          <td>{p.unrealized_pnl?.toFixed(2)}</td>
        </tr>
      ))}
    </table>
  );
}

useTPSLOrder

管理持仓的止盈/止损。返回 [computed, actions]。

import { useTPSLOrder } from '@orderly.network/hooks';

const [computed, {
  setValue,      // (key, number|string|boolean) => void
  setValues,     // (Partial<ComputedAlgoOrder>) => void
  submit,        // (params?: { accountId? }) => Promise<any>
  validate,      // (otherErrors?) => Promise<AlgoOrderEntity>
  deleteOrder,   // (orderId, symbol) => Promise<any>
  errors,
  metaState,     // { dirty, submitted, validated, errors }
  isCreateMutating, isUpdateMutating,
}] = useTPSLOrder(position, options?);

// position: { symbol, average_open_price, position_qty, ... }
// options:  { defaultOrder?, isEditing?, positionType? }

// Example
function TPSLForm({ position }) {
  const [, { setValue, validate, submit, isCreateMutating }] = useTPSLOrder(position);
  const handleSet = async () => {
    setValue('positionTPSLOrderTPTriggerPrice', 71000);
    setValue('positionTPSLOrderSLTriggerPrice', 69000);
    await validate();
    await submit();
  };
  return <button onClick={handleSet} disabled={isCreateMutating}>Set TP/SL</button>;
}

---

市场数据 Hooks

useOrderbookStream

实时订单簿。

import { useOrderbookStream } from '@orderly.network/hooks';

const { asks, bids, isLoading } = useOrderbookStream(symbol?, options?);
// asks/bids: [price, quantity][] (number tuples)

useMarkPrice / useMarkPriceBySymbol

import { useMarkPrice, useMarkPriceBySymbol } from '@orderly.network/hooks';
const allMarkPrices = useMarkPrice(); // map of symbol -> price
const markPrice = useMarkPriceBySymbol(symbol); // number | undefined for one symbol

useTickerStream

所有交易对的 24h 行情统计数据。

import { useTickerStream } from '@orderly.network/hooks';
const tickers = useTickerStream(); // Record<symbol, Ticker> | undefined
// Ticker: { symbol, last_price, high_24h, low_24h, volume_24h,
//   quote_volume_24h, open, price_change_percent_24h, ... }

useSymbolInfo / useSymbolsInfo

某个交易对的交易规则。

import { useSymbolInfo, useSymbolsInfo } from '@orderly.network/hooks';
const symbolInfo = useSymbolInfo(symbol); // API.SymbolExt
// { symbol, base, quote, base_min, base_max, quote_tick, price_range, leverage_max, ... }

useMarkets / useMarketList

市场元数据列表。

import { useMarkets, useMarketList } from '@orderly.network/hooks';
const markets = useMarkets(); // API.MarketInfo[] | undefined

---

余额与抵押品 Hooks

useCollateral

账户抵押品和投资组合价值。接收 { dp }（小数位数）。

import { useCollateral } from '@orderly.network/hooks';

const {
  totalCollateral, // total account collateral value
  freeCollateral, // available for new positions
  freeCollateralUSDCOnly, // free collateral in USDC only
  totalValue, // number | null — total portfolio value
  availableBalance, // withdrawable
  unsettledPnL, // unrealized PnL across positions
  holding, // API.Holding[]
  accountInfo, // API.AccountInfo
  usdcHolding,
} = useCollateral({ dp: 4 });

// Example
function AccountSummary() {
  const { totalCollateral, freeCollateral } = useCollateral({ dp: 2 });
  return (
    <p>
      Total: {totalCollateral} · Free: {freeCollateral}
    </p>
  );
}

没有 useBalance Hook。如需查询各代币的持仓，请使用 useCollateral().holding，或使用 useHoldingStream 获取实时持仓流。

useHoldingStream

实时持仓流。

import { useHoldingStream } from '@orderly.network/hooks';
const holdings = useHoldingStream(); // API.Holding[] | undefined

---

链 Hooks

useChains

支持的链。返回 [chains, helpers]。

import { useChains } from '@orderly.network/hooks';
const [chains, { findByChainId }] = useChains();
// chains: API.Chain[] (id, name, network, chain_id, explorer, ...)

useMarginRatio

import { useMarginRatio } from '@orderly.network/hooks';
const { currentLeverage, marginRatio, mmr, maintenanceMargin } = useMarginRatio();

---

充值/提现 Hooks

useDeposit

处理充值（授权 + 充值）。deposit() 不接收参数——它会使用通过 setQuantity 设置的 quantity。

import { useDeposit } from '@orderly.network/hooks';

const {
  balance,              // string | null — source wallet balance
  allowance,            // string — ERC-20 allowance
  depositFee,           // bigint — in wei
  isNativeToken,
  dst,                  // { symbol, address, decimals, chainId, network }
  targetChain,          // API.Chain
  quantity, setQuantity,
  approve,              // (amount?) => Promise<void>
  deposit,              // () => Promise<any>
  fetchBalance,         // (address, decimals?) => Promise<string>
  fetchBalances,        // (tokens) => Promise<Record<string,string>>
  balanceRevalidating, allowanceRevalidating, depositFeeRevalidating,
} = useDeposit({
  // all optional
  srcChainId?, srcToken?, dstToken?, address?, decimals?,
  crossChainRouteAddress?, depositorAddress?,
});

// Example
function DepositUSDC() {
  const { balance, allowance, approve, deposit, setQuantity } = useDeposit({
    srcChainId: 42161, srcToken: 'USDC',
    address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831', decimals: 6,
  });
  const handleDeposit = async () => {
    setQuantity('100');
    if (Number(allowance) < 100) await approve();
    await deposit();
  };
  return <button onClick={handleDeposit}>Deposit</button>;
}

useWithdraw

处理提现。withdraw() 接收完整的 inputs 对象。

import { useWithdraw } from '@orderly.network/hooks';

const {
  dst,                  // { symbol, address, decimals, chainId, network }
  withdraw,             // (inputs) => Promise<any>
  maxAmount,            // number — max withdrawable (use this)
  unsettledPnL, availableBalance,
} = useWithdraw({ srcChainId?, token?, decimals? });

// Example
await withdraw({
  chainId: 42161,
  token: 'USDC',
  amount: '100',
  allowCrossChainWithdraw: false,
  receiver: '0x...',   // optional
});

availableWithdraw 已弃用，请改用 maxAmount。

---

杠杆 Hooks

账户级别的杠杆（useLeverage）不针对特定交易对。如需查询特定交易对，请使用 useSymbolLeverage / useMaxLeverage。

import { useLeverage, useSymbolLeverage, useMaxLeverage } from '@orderly.network/hooks';

// Account-level
const {
  update, // ({ leverage }) => Promise<{ max_leverage } | undefined>
  curLeverage,
  maxLeverage,
  leverageLevers,
  isLoading,
} = useLeverage();

// Symbol-level
const { maxLeverage, update, isLoading } = useSymbolLeverage(symbol);

const maxLev = useMaxLeverage(symbol); // number | "-"

// Example
function LeverageControl({ symbol }: { symbol: string }) {
  const { maxLeverage, update, isLoading } = useSymbolLeverage(symbol);
  return (
    <input
      type="range"
      min={1}
      max={maxLeverage}
      onChange={(e) => update({ leverage: parseInt(e.target.value), symbol })}
    />
  );
}

---

常见模式

交易界面

import {
  useAccount,
  useOrderEntry,
  usePositionStream,
  useOrderbookStream,
  useCollateral,
} from '@orderly.network/hooks';
import { AccountStatusEnum, OrderSide, OrderType } from '@orderly.network/types';

function TradingInterface({ symbol }: { symbol: string }) {
  const { state } = useAccount();
  const [positions] = usePositionStream();
  const { asks, bids } = useOrderbookStream(symbol);
  const { freeCollateral } = useCollateral({ dp: 2 });
  const { submit, setValue, helper, isMutating, formattedOrder } = useOrderEntry(symbol);

  if (state.status < AccountStatusEnum.Connected) return <ConnectWallet />;

  // ...render orderbook, order form, positions...
}

提示：如需完整的交易 UI，而不想手动编写，请使用 @orderly.network/trading 中的 <TradingPage>（参见 orderly-sdk-page-components）。以上 Hooks 适用于自定义 UI。

相关技能

• orderly-sdk-ui-components - 预构建 UI 组件
• orderly-sdk-trading-workflows - 端到端交易流程
• orderly-sdk-wallet-connection - 钱包 + 账户状态机
• orderly-trading-orders - 订单管理详情（REST）
• orderly-positions-tpsl - 持仓管理（REST）
• orderly-websocket-streaming - 底层 WebSocket 实现