orderly-sdk-trading-workflows

Orderly Network：SDK を使用した取引ワークフロー

エンドツーエンドの取引ワークフロー：接続 → 入金 → 取引 → 監視 → 決済 → 出金。

使用する場面

• 完全な取引インターフェースを構築する場合
• 入金 → 取引 → 出金のフローを実装する場合
• SDK のフックを使って、カスタム注文／ポジション UI を構築する場合

前提条件

• Orderly SDK のパッケージがインストールされていること（orderly-sdk-install-dependency を参照）
• ウォレット接続が設定されていること（orderly-sdk-wallet-connection を参照）
• アプリが OrderlyAppProvider でラップされていること

概要

Connect → Deposit → Trade → Monitor → Close → Withdraw

推奨される方法：リファレンス DEX では、取引フローを独自に実装しません。<TradingPage>（@orderly.network/trading から）をレンダリングします。チャート、オーダーブック、注文入力、ポジション、注文管理がすでに含まれています。以下のフックベースのコードは、TradingPage の一部を置き換えるカスタム取引 UI 向けです。

1. 接続と認証

AccountStatusEnum は hooks ではなく、@orderly.network/types からエクスポートされます。状態遷移の全体は orderly-sdk-wallet-connection に記載されています。

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

function TradingGuard({ children }: { children: React.ReactNode }) {
  const { state, createAccount, createOrderlyKey } = useAccount();

  switch (state.status) {
    case AccountStatusEnum.NotConnected:
      return <ConnectWalletPrompt />;
    case AccountStatusEnum.Connected:
      return <button onClick={() => createAccount()}>Create Orderly Account</button>;
    case AccountStatusEnum.NotSignedIn:
      return <button onClick={() => createOrderlyKey()}>Enable Trading</button>;
    default:
      return <>{children}</>;
  }
}

AuthGuard

カスタム UI では、AuthGuard（@orderly.network/ui-connector から）を使ってコンテンツへのアクセスを制御します。注：TradingPage は独自の認証プロンプトを管理するため、AuthGuard でラップする必要はありません。

import { AuthGuard } from '@orderly.network/ui-connector';

<AuthGuard>{/* protected custom UI */}</AuthGuard>;

2. 入金

useDeposit

deposit() に引数は不要です。setQuantity で設定した金額が送信されます。トークンがネイティブトークンでない場合は、先に ERC-20 の使用許可を与えてください。

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

function DepositForm() {
  const { balance, allowance, approve, deposit, quantity, setQuantity, depositFee, isNativeToken } =
    useDeposit({
      srcChainId: 42161,
      srcToken: 'USDC',
      address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
      decimals: 6,
    });

  const handleDeposit = async () => {
    setQuantity('100');
    try {
      // Approve if allowance is insufficient (allowance is a wei string)
      if (!isNativeToken) await approve();
      await deposit();
      toast.success('Deposit submitted');
    } catch (e) {
      toast.error((e as Error).message);
    }
  };

  return (
    <div>
      <input value={quantity} onChange={(e) => setQuantity(e.target.value)} placeholder="Amount" />
      <p>Wallet balance: {balance}</p>
      <p>Deposit fee (wei): {depositFee?.toString()}</p>
      <button onClick={handleDeposit}>Deposit</button>
    </div>
  );
}

depositFee は bigint（wei 単位）です。スタイルが適用済みの UI を使う場合は、あらかじめ用意されたフォーム（@orderly.network/ui-transfer の DepositForm／DepositFormWidget）を使用してください。

3. アカウント残高の確認

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

function AccountSummary() {
  const { totalValue, freeCollateral, availableBalance, unsettledPnL } = useCollateral({ dp: 2 });
  // totalValue: number | null — total portfolio value
  // freeCollateral: available for new positions
  // availableBalance: withdrawable
  // unsettledPnL: unrealized PnL across positions
}

4. 注文の発注

推奨：TradingPage

import { TradingPage } from '@orderly.network/trading';
<TradingPage symbol="PERP_BTC_USDC" tradingViewConfig={config.tradingPage.tradingViewConfig} />;

カスタム UI：useOrderEntry

setValue／setValues で注文項目（キー：side、order_type、order_price、order_quantity、reduce_only、tp_trigger_price、sl_price）を設定し、検証してから submit() を呼び出します。検証状態はトップレベルの errors ではなく、metaState にあります。

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

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

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

  const handleSubmit = async () => {
    const result = await helper.validate();
    if (result) return; // validation issues are in metaState.errors
    try {
      await submit({ resetOnSuccess: true });
      toast.success('Order submitted');
    } catch (e) {
      toast.error((e as Error).message);
    }
  };

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

低レベル API：useMutation

orderly-entry を使用しないフロー（ボットなど）では、直接 POST します。これは DEX テンプレートが採用している方法ではありません。

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

const [submitOrder] = useMutation('/v1/order');
await submitOrder({
  symbol,
  side,
  order_type: OrderType.MARKET,
  order_quantity: quantity,
});

5. 注文の監視とキャンセル

useOrderStream は [orders, actions] を返します。OrderStatus 列挙型を使用してください。文字列 'OPEN' は使用しないでください（未決済注文は OrderStatus.INCOMPLETE です）。

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

function OpenOrders({ symbol }: { symbol?: string }) {
  const [orders, { cancelOrder, cancelAllPendingOrders }] = 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>
  );
}

6. ポジションの監視

usePositionStream は 3 要素のタプル [positions, calc, status] を返します。3 番目の要素には loading ではなく isLoading が含まれます。

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

function PositionsTable() {
  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.average_open_price}</td>
          <td>{p.mark_price}</td>
          <td className={p.unrealized_pnl >= 0 ? 'profit' : 'loss'}>
            {p.unrealized_pnl?.toFixed(2)}
          </td>
        </tr>
      ))}
    </table>
  );
}

7. ポジションの決済

useOrderEntry を使って、縮小する成行注文を送信します（reduce_only: true と反対のサイドを設定します）。

const { setValues, submit } = useOrderEntry(position.symbol);
await setValues({
  side: position.position_qty > 0 ? OrderSide.SELL : OrderSide.BUY,
  order_type: OrderType.MARKET,
  order_quantity: Math.abs(position.position_qty),
  reduce_only: true,
});
await submit();

または、usePositionClose／ポジションウィジェットの決済アクションを使うと、1 回の呼び出しで決済できます。

8. 出金

useWithdraw は withdraw(inputs) を返します。単なる金額ではなく、入力オブジェクト全体を渡してください。非推奨の availableWithdraw ではなく、maxAmount を使用してください。

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

const { withdraw, maxAmount, unsettledPnL, availableBalance, dst } = useWithdraw({
  srcChainId: 42161,
  token: 'USDC',
  decimals: 6,
});

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

スタイルが適用済みの UI には、@orderly.network/ui-transfer の WithdrawForm／WithdrawWidget を使用してください。

9. レバレッジ

アカウントレベルのレバレッジ（useLeverage）はシンボルごとに設定されるものではありません。アクティブなシンボルには useSymbolLeverage を使用してください。

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

// Account-level
const { curLeverage, maxLeverage, update, isLoading } = useLeverage();
await update({ leverage: 5 });

// Symbol-level (preferred on the trading page)
const { maxLeverage, update: setSymbolLeverage } = useSymbolLeverage(symbol);
await setSymbolLeverage({ leverage: 5, symbol });

10. リスクの監視

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

完全な取引ページ（推奨）

テンプレートの取引ページは、useOrderlyConfig() の設定を使った TradingPage だけで構成されています。認証ガードや注文の接続を手動で行う必要はありません。

// app/pages/perp/Symbol.tsx
import { TradingPage } from '@orderly.network/trading';
import { useOrderlyConfig } from '@/utils/config';

export default function PerpSymbol() {
  const params = useParams();
  const [symbol, setSymbol] = useState(params.symbol!);
  const config = useOrderlyConfig();
  return (
    <TradingPage
      symbol={symbol}
      onSymbolChange={(data) => {
        setSymbol(data.symbol);
        navigate(`/perp/${data.symbol}`);
      }}
      tradingViewConfig={config.tradingPage.tradingViewConfig}
      sharePnLConfig={config.tradingPage.sharePnLConfig}
    />
  );
}

ルートは /perp/:symbol です（/trade ではありません）。

ベストプラクティス

1. 深いカスタマイズが必要な場合を除き、注文／ポジション UI を独自に実装するよりも TradingPage を優先してください。
2. 未決済注文のストリームでは文字列 'OPEN' ではなく、OrderStatus 列挙型（INCOMPLETE）を使用してください。
3. useOrderEntry を使用する場合は、検証結果を metaState（metaState.errors、metaState.validated）から取得してください。
4. ネイティブではない ERC-20 トークンを入金する前に、使用許可を与えてください。isNativeToken を確認してください。
5. withdraw() には入力オブジェクト全体を渡し、出金可能な上限には maxAmount を使用してください。

関連スキル

• orderly-sdk-wallet-connection - ウォレットとアカウントのステートマシン
• orderly-sdk-react-hooks - フックの完全なリファレンス
• orderly-sdk-page-components - TradingPage とポートフォリオページ
• orderly-trading-orders - 注文管理（REST API）
• orderly-positions-tpsl - ポジション管理（REST API）
• orderly-deposit-withdraw - 資金管理（REST API）