orderly-sdk-debugging

Orderly Network：SDK のデバッグ

Orderly SDK の実行時の動作をデバッグするためのガイドです。アカウント／認証状態、データストリーム、注文や入出金の失敗、SDK がスローするエラーを扱います。

このスキルでは、SDK 独自の実行時の挙動を扱います。ビルド／セットアップの問題（Vite のポリフィル、CSS のインポート、パッケージのバージョン）については orderly-sdk-install-dependency と orderly-sdk-dex-architecture をご覧ください。接続設定（プロバイダーの props、.env の設定）については orderly-sdk-dex-architecture をご覧ください。

使用するタイミング

• アカウント／認証状態のデバッグ（「接続中のまま」「サインインできない」）
• データが読み込まれない問題の調査（オーダーブック、ポジション、残高）
• 注文の送信／拒否に関するトラブルシューティング
• 入金／出金の失敗に関するトラブルシューティング
• SDK がスローするエラー（ApiError／SDKError）の理解

前提条件

• Orderly SDK プロバイダーがマウントされていること（@orderly.network/react-app の OrderlyAppProvider）
• ブラウザーの DevTools に慣れていること

1. アカウントと認証の状態

SDK アカウントは、固定された段階的な状態遷移をたどります。「何も動かない」問題のほとんどは、アカウントが SignedIn より前の状態で止まっていることが原因です。

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

function AccountDebugger() {
  const { state, account } = useAccount();

  // state.status is an AccountStatusEnum (numeric)
  console.log('account state', state.status, AccountStatusEnum[state.status]);
  console.log('accountId', account?.accountId);
}

AccountStatusEnum（@orderly.network/types から）

値	名前	意味
-1	EnableTradingWithoutConnected	ウォレットが接続されていない状態で取引が有効になっています
0	NotConnected	ウォレットが接続されていません
1	Connected	ウォレットは接続されていますが、Orderly アカウントはまだ解決されていません
2	NotSignedIn	Orderly キーを作成するには、EIP-712／Ed25519 署名が必要です
3	SignedIn	認証が完了しており、プライベートストリーム／注文が機能します
4	DisabledTrading	このアカウントでは取引が無効になっています
5	EnableTrading	取引が有効になっています

認証の段階とよくある停滞ポイント

NotConnected ──connect wallet──▶ Connected ──resolve account──▶ NotSignedIn ──sign──▶ SignedIn

症状	考えられる状態	解決方法
プライベートデータ（ポジション／残高）が空	< SignedIn	署名を行い、ユーザーをサインインさせます
アプリが接続を促し続ける	NotConnected	WalletConnectorProvider がマウントされ、設定されているか確認します
「署名」が完了しない	NotSignedIn	ウォレットで拒否されています。再度プロンプトを表示します。キーの有効期限は 365 日です
注文が未認証として拒否される	NotSignedIn／Connected	注文を送信するには、アカウントが SignedIn である必要があります
state.validating が true のままになる	任意	アカウント解決のためのネットワーク／リクエストが停止しています。WS／ネットワークを確認してください

useAccount() は { account, state, ... } を返します。state は status: AccountStatusEnum と validating: boolean を持つ AccountState です。

2. データが読み込まれない

パブリックストリーム（オーダーブック、取引、マーク価格）は認証なしで利用できます。プライベートストリーム（ポジション、注文、残高、ウォレット）には、アカウントが SignedIn である必要があります。パブリックデータは表示されるのにプライベートデータが空の場合は、まずアカウントの状態を確認してください（§1）。

WebSocket 接続の状態

import { useWsStatus, WsNetworkStatus } from '@orderly.network/hooks';

function StreamHealth() {
  const ws = useWsStatus();
  // WsNetworkStatus is string-valued: 'connected' | 'unstable' | 'disconnected'
  return <span>{ws}</span>;
}

WsNetworkStatus	意味
Connected	WS が接続され、ストリームが流れています
Unstable	接続が切れ、SDK が再接続しています
Disconnected	接続が切れ、再接続していません。プロバイダーを再マウントしてください

起動／プリロードの状態

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

const { done, error } = usePreLoadData();
// done === false for the lifetime of the app = the initial data fetch failed/stalled

チェックリスト：データが読み込まれない

• useWsStatus() は Connected ですか？
• プライベートデータの場合：state.status >= SignedIn ですか？
• networkId は想定しているチェーン（mainnet と testnet）に一致していますか？
• usePreLoadData().done === true ですか？
• シンボル文字列は正確ですか？ 例：PERP_ETH_USDC
• コンソールに SDK エラーはありませんか（§5）？

3. 注文送信エラー

useOrderEntry(symbol, options) は、送信前の注文準備状態と検証結果を公開します。metaState を確認し、helper.validate() を呼び出してください。

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

function OrderDebugger() {
  const { formattedOrder, metaState, helper, maxQty, estLiqPrice, submit } =
    useOrderEntry('PERP_ETH_USDC');

  // metaState.errors: OrderValidationResult | null  (null = valid)
  // metaState.validated: boolean
  console.log({ ready: metaState.validated && !metaState.errors, maxQty, estLiqPrice });

  async function place() {
    try {
      const res = await submit({ resetOnSuccess: true });
      console.log('ok', res);
    } catch (e) {
      // SDK wraps REST failures in ApiError (see §5)
      console.error('order failed', e);
    }
  }
}

setValue() で設定するフィールドキーは side、order_type、order_price、order_quantity、reduce_only、tp_trigger_price、sl_price です。送信ミューテーションのフラグは metaState によって制御されます。またはフックの isMutating を使用します。isSubmitting はありません。

注文ストリームの注文状態を読み取る

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

const [orders] = useOrderStream({ status: OrderStatus.INCOMPLETE });
// OrderStatus: OPEN | NEW | FILLED | PARTIAL_FILLED | CANCELLED | REPLACED | COMPLETED | INCOMPLETE | REJECTED

オープン注文をクエリするには、文字列の 'OPEN' ではなく OrderStatus.INCOMPLETE を使用してください。ストリーム内の REJECTED エントリーは、サーバーが送信された注文を拒否したことを示します。その理由フィールドを確認してください。

チェックリスト：注文が送信されない／拒否される

• state.status は SignedIn ですか？
• シンボルは正確ですか（PERP_ETH_USDC）？
• metaState.errors は null（検証済み）ですか？
• 数量はシンボルの最小値以上ですか（maxQty を確認してください）？
• 指値価格はマーク価格の許容範囲内ですか？
• 利用可能な担保は十分ですか（useCollateral().freeCollateral）？

4. 入金・出金エラー

入金（先に ERC-20 の許可が必要）

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

function DepositDebugger() {
  const { balance, allowance, approve, deposit, dst } = useDeposit({
    /* srcChainId, token, ... */
  });

  async function run(amount: string) {
    // allowance must cover amount, else approve first
    if (Number(amount) > Number(allowance)) {
      await approve(amount); // wallet prompt
    }
    await deposit(); // NOTE: deposit() takes NO arguments
  }
}

• approve(amount?) と deposit() はどちらもウォレットの確認画面を表示します。try/catch で囲んでください。
• deposit() に引数は不要です。金額はフックの quantity／setQuantity の状態から取得されます。
• depositFee は bigint です。

出金

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

const { withdraw, maxAmount, unsettledPnL } = useWithdraw({
  /* srcChainId, token, decimals */
});

await withdraw({
  chainId,
  token,
  amount,
  allowCrossChainWithdraw: true,
  // receiver?: '<optional custom address>'
});

• 上限には、非推奨の availableWithdraw ではなく maxAmount を使用してください。
• unsettledPnL によって出金可能額が減少します。残高不足で出金に失敗する場合は、これを確認してください。

出金可能状態の読み取り

WithdrawStatus（@orderly.network/types）：NotSupported | NotConnected | Unsettle（未決済の損益により出金不可）| InsufficientBalance | Normal。出金できるのは Normal の場合のみです。

ユーザーによる拒否／トランザクションの残高不足を検出する

これらの失敗は Orderly API ではなく、ウォレット／チェーンに起因します。error.message に基づいて判定してください。

catch (e) {
  const msg = String((e as Error)?.message ?? '');
  if (/reject|denied/i.test(msg))  /* user rejected the wallet prompt */;
  if (/insufficient/i.test(msg))   /* not enough gas/balance on-chain */;
}

5. SDK エラーの読み取り

SDK は @orderly.network/types から次の 2 つのエラークラスを公開します。

• ApiError — REST API の失敗です。(message: string, code: number) を指定して生成されます。数値の code は失敗の種類を示します。詳細は error.message を確認してください。
• SDKError — クライアント側／SDK 内部の失敗です。

import { ApiError, SDKError } from '@orderly.network/types';

try {
  await someSdkAction();
} catch (e) {
  if (e instanceof ApiError) {
    console.error('API error', e.message /* numeric code lives on the instance */);
  } else if (e instanceof SDKError) {
    console.error('SDK error', e.message);
  }
}

REST エラーコードの表をハードコードしないでください。コードは変更されることがあります。error.message をログに記録し、実際のワークフローで確認したコードに基づいて分岐してください。

レート制限

REST の -1003 のようなレート制限は ApiError として通知されます。バックオフを設けて再試行してください。

async function withRetry<T>(fn: () => Promise<T>, retries = 3, base = 1000): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (e) {
      const code = (e as ApiError & { code?: number })?.code;
      if (code === -1003 && i < retries) {
        await new Promise((r) => setTimeout(r, base * 2 ** i));
        continue;
      }
      throw e;
    }
  }
}

5. フックの状態を調べる

簡易ロガーを使うと、レンダー間で非同期フックの出力を追跡できます。

function useDebugHook<T>(name: string, value: T): T {
  useEffect(() => {
    console.log(`[${name}]`, value);
  }, [name, value]);
  return value;
}

戻り値の形式を確認する（よくある混乱）

フック	形式
usePositionStream	3 要素のタプル：[positions, calc, { isLoading }]
useCollateral	オブジェクト：{ totalCollateral, freeCollateral, availableBalance, ... }
useOrderEntry	オブジェクト：{ submit, metaState, helper, setValue, ... }
useAccount	オブジェクト：{ account, state, ... }（state.status）
useOrderStream	2 要素のタプル：[orders, { total, isLoading, cancelOrder, ... }]

分割代入する要素数を間違えると、気づきにくいバグが頻繁に発生します（例：最初の要素から isLoading を読み取る）。

開発パネル

function OrderlyDebugPanel() {
  const { state } = useAccount();
  const ws = useWsStatus();
  // mount this component only while developing (gate it however your app prefers)
  return (
    <div style={{ position: 'fixed', right: 8, bottom: 8, fontSize: 11 }}>
      <div>account: {state.status}</div>
      <div>ws: {ws}</div>
    </div>
  );
}

6. エラーバウンダリー

コンポーネントのエラーには、SDK の ErrorBoundary（@orderly.network/react-app）を使用します。

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

<ErrorBoundary fallback={<SomethingWentWrong />}>{children}</ErrorBoundary>;

ルートレベルのエラー（遅延インポートの失敗、スローされたローダー／アクション）は、ルーターの errorElement で捕捉してください。ErrorBoundary は React ツリー用です。

デバッグチェックリスト

何も動作しない／アプリが真っ白

• OrderlyAppProvider が有効な brokerId ／ networkId でマウントされていますか？
• usePreLoadData().done === true ですか？
• useWsStatus() === Connected ですか？

プライベートデータが空

• state.status は SignedIn ですか？
• 表示されるチェーンに対して正しい networkId ですか？
• WS は Connected ですか？

注文に失敗する

• SignedIn ですか？
• metaState.errors === null ですか？
• 数量は最小値以上で、価格は範囲内ですか？
• freeCollateral は十分ですか？

入金／出金に失敗する

• Allowance は入金額をカバーしていますか（そうでない場合は approve）？
• withdraw の金額は maxAmount 以下ですか？
• unsettledPnL は考慮されていますか？
• ウォレットのプロンプトは拒否されていませんか？

関連スキル

• orderly-sdk-dex-architecture — プロバイダーの接続と設定
• orderly-sdk-wallet-connection — ウォレット連携
• orderly-api-authentication — サインイン／キーのフロー
• orderly-sdk-install-dependency — パッケージのインストールとビルド設定