orderly-sdk-react-hooks

Orderly Network：SDK React Hooks リファレンス

@orderly.network/hooks からエクスポートされるフックのリファレンスです。以下のシグネチャはすべて、インストール済みの型定義（SDK 3.1.x）で確認されています。

使用する場面

• Orderly を使った React アプリケーションの構築
• フックのシグネチャと戻り値をすばやく確認
• SDK 上に独自の取引／アカウント UI を実装

前提条件

• React 18+
• @orderly.network/react-app と @orderly.network/hooks がインストールされていること
• アプリをラップする OrderlyAppProvider（@orderly.network/react-app から提供）

フックは @orderly.network/hooks から提供されますが、@orderly.network/react-app の OrderlyAppProvider 内でのみ動作します（@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>
  );
}

---

アカウント関連のフック

useAccount

アカウントインスタンスと状態です。state.status は文字列ではなく、@orderly.network/types の AccountStatusEnum です。

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

---

取引関連のフック

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

---

ポジション関連のフック

usePositionStream

リアルタイムの PnL を含むポジションをストリーミングします。単一のオブジェクトではなく、3 要素のタプル [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>;
}

---

市場データ関連のフック

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

すべての銘柄の 24 時間ティッカー統計です。

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

---

残高と担保関連のフック

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 フックはありません。トークンごとの保有量を取得するには、useCollateral().holding またはリアルタイム保有量フィードの useHoldingStream を使用してください。

useHoldingStream

リアルタイムの保有量フィードです。

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

---

チェーン関連のフック

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

---

入金／出金関連のフック

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() はすべての入力を含むオブジェクトを受け取ります。

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 を使用してください。

---

レバレッジ関連のフック

アカウントレベルのレバレッジ（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 を参照）。上記のフックは独自 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 の実装