実験的コンボAPI

コンボは、オプションのレッグを固定比率で1つの注文として取引します。約定時には、必要なすべてのレッグが同時に執行されます。ポジションは個々のオプションのまま保持されます。

実験的な契約

すべての /experimental エンドポイントと、明示的に実験的とされたWebSocketメッセージは不安定です。 破壊的変更は1日(24時間)前の事前通知で発効する場合があります。これにはフィールドやエンドポイントの削除や名称変更、フィールド型の変更、リクエストやレスポンスの挙動の変更が含まれます。変更はAPIチェンジログで告知されます。クライアントはこれらの通知を監視し、記載された発効時刻までに対応する必要があります。既存の非実験的なAPI契約はこのポリシーの対象外です。

利用可否は環境によって異なります。本ページは実験的インターフェースについて説明するものであり、本番環境での提供開始やトレーディングアプリの新しいインターフェースを告知するものではありません。

接続と署名に関する共通の規約については、RESTリファレンス、認証ガイド、WebSocketガイドを参照してください。

コンボを検索する

リクエスト	結果
`GET /experimental/combos`	満期前の定義の上限付きページ。`underlying` で任意に絞り込み可能
`GET /experimental/combos/{symbol}`	満期前の1つの定義と、解決済みのオプションレッグ

最初の注文による作成: コンボがまだ検索可能でない場合は、POST /order で正規化された combo_definition を送信します。最初に受理された注文がその定義を公開します。即時に約定する注文も含みます。拒否された注文は何も公開しません。作成専用のエンドポイントはありません。

検索可能期間: 定義は、最初のレッグが満期を迎えるまで検索可能です。待機中の注文がない場合も同様です。

ページネーション: レスポンスには combos と next_cursor が含まれます。limit は1〜1,000の範囲で指定します(デフォルトは100)。返されたカーソルを次のリクエストの cursor として渡し、同じ underlying フィルターを維持してください。カーソルがnullの場合、それ以降の行は確認されなかったことを意味します。無効なlimitやカーソルはHTTP 400を返します。

GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>

ページの並び順: 最も早いレッグの満期、次にコンボIDの順です。カーソルは不透明な値として扱ってください。各ページは現在の検索状態を反映しており、リクエストの間に定義が満期を迎えたり追加されたりする可能性があります。保存したカーソルより前に並ぶ新規作成の定義を取得するには、作成更新を利用するか、検索をやり直してください。

識別子: シンボルは COMBO- に続く64文字の小文字16進数です。内容に紐づくIDにより、レッグの銘柄と符号付き整数比率が固定されます。既存のシンボルの意味が変わることはありません。

初期の対象範囲: 同じ原資産を持つ、2〜8個の異なるオプションレッグです。すべてのレッグが上場済みかつ満期前であり、要求された執行ルートの対象である必要があります。

サイド、価格、サイズを理解する

比率が +1 A, -1 B の正規化された定義の場合:

1パッケージの買い: Aを1つ買い、Bを1つ売ります。
1パッケージの売り: Aを1つ売り、Bを1つ買います。
ネット価格: price(A) - price(B) で、パッケージ単位で提示されます。
指値: 買いは指値以下のネット価格を受け入れ、売りは指値以上のネット価格を受け入れます。

マイナスやゼロの価格も有効です。 Aが $8、Bが$ 10で取引されている場合、正規化されたネット価格は -2 です。このパッケージを買うと、手数料控除前で $2を受け取ります。売ると、手数料控除前で$ 2を支払います。実際の各オプションレッグの約定価格は引き続きプラスです。

注文の刻み: パッケージサイズは人間が読める契約単位で、刻みは 0.000001 です。ネット指値価格の刻みも 0.000001 です。約定する各レッグは、それぞれの数量と価格の刻みも満たす必要があります。部分約定ではすべての比率が維持され、許容される完全なパッケージ数量が約定します。

手数料: 既存のレッグごとの料率と適用条件が適用され、パッケージ割引はありません。入ってくる注文は、自身のレッグについてテイカーとなり、送信したビルダー帰属が適用されます。アウトライトからコンボを経由するルートでは、コンボの親注文は、サポート側のアウトライトのメイカーに対する追加のサポートレッグについて通常のテイカー手数料帰属を受けます。これらのレッグにはビルダー帰属はありません。待機中のコンボの予約額には、レッグの総額に対する見込みテイカー手数料が保守的に含まれます。現在のStandard Marginの執行では、オーダーブックおよびRFQの約定で取引手数料がゼロである必要があります。SM参加者が関与するルートは、ゼロでない取引手数料では執行できません。

証拠金: 取引所は、各アカウントについて結果として生じるオプションポジションと残りの注文エクスポージャーを確認します。コンボはウォレット間で担保を合算せず、特定の証拠金削減も保証しません。アカウントのティアがカバードのオプション売りのみを許可している場合、待機中のアウトライト注文と各コンボ親注文の売りレッグは、同じ約定済みのロング在庫を共有します。別々の親注文や分割約定がそれぞれ同じ在庫を再利用することはできません。未約定の買いレッグはカバーとして加算されません。

注文を発注する

既存の署名付き POST /order リクエストをコンボシンボルで使用します。注文の署名フィールドは変わりません。 マイナス価格のマイナス記号も含め、送信する symbol、size、price の文字列そのものに署名してください。新しいコンボの場合は、後述のとおり正規化された combo_definition を追加します。署名された内容紐づけのシンボルがその定義にコミットするため、一致しない定義は拒否されます。既知のコンボでは省略できます。

{
  "wallet": "<your wallet>",
  "symbol": "<discovered COMBO symbol>",
  "side": "Buy",
  "size": "1",
  "price": "-2",
  "tif": "gtc",
  "route": "best_execution",
  "client_id": "spread-001",
  "reduce_only": false,
  "mmp_enabled": false,
  "nonce": 1,
  "signature": "<signed order>"
}

プレースホルダーとnonceは実際の値に置き換えてください。価格は説明用であり、現在の市場気配ではありません。

設定	挙動
`route: "book_only"`	利用可能な直接流動性およびサポートされるインプライド流動性と照合し、その後time in forceを適用
`route: "best_execution"`	パッケージ全体の価格改善オークションを検討し、適切な場合はオーダーブックでの執行にフォールバック
`route: "rfq_only"`	`/order` では拒否
`tif: "gtc"`	未約定のパッケージ残量を待機させる
`tif: "ioc"`	未約定の残量をキャンセル
`tif: "fok"`	要求されたパッケージ数量全体を執行するか、まったく執行しない

価格改善は、パッケージ全体の符号付きネット価格を、執行可能なフルサイズのオーダーブック基準と比較します。気配提供者は、要求された正確な比率と数量ですべてのレッグを提示する必要があります。最初のレッグだけで気配を順位付けすることは不十分です。直接のコンボ流動性とサポートされるインプライドルートの両方が基準に寄与できます。基準が利用できない、または不完全な場合、注文はオーダーブックでの執行に送られます。

気配の適格性: 既存のRFQ手数料ルールも適用されます。いずれかの参加者がStandard Marginを使用している場合、RFQの執行には取引手数料がゼロである必要があります。手数料、担保、または正確な配分のチェックに失敗した気配は、現在のオーダーブック経路での執行に委ねられ、そのレッグが部分的に執行されることはありません。

インプライドマッチングでは、1つのコンボとそれを支えるアウトライトのオプション流動性を組み合わせることができます。たとえば、アウトライトのA注文は、A-Bのコンボと、Bの流動性に対してアトミックに取引できます。Aのみを取引する顧客がBのポジションを受け取ることはありません。

インプライド検索にはリソース上限があります。アウトライト注文がその上限に達した場合、サポート流動性が利用できなくなった場合、または任意のルートがアウトライトの注文刻みを表現できない場合でも、通常の注文ルールのもとで直接のオプションのオーダーブックに対して取引できます。コンボのサポートによって、受け入れられるアウトライトの数量や価格の刻みは変わりません。対象のオプションは引き続きオーダーブック取引の対象である必要があります。検索上限を超えるコンボ注文は、部分的な配分なしで拒否されます。

現在の制限: ネイティブのコンボ注文には mmp_enabled: false が必要です。保護されたアウトライト参加者はMMPを維持します。閾値をトリガーしたパッケージはそのレッグを完了させ、以降のマッチングを停止します。不完全なFOKまたはアトミックな置き換えは、候補全体をロールバックします。reduce-only注文は価格改善オークションをスキップしてオーダーブックでの受付を使用し、結果として生じる各レッグがreduce-onlyチェックを満たす必要があります。待機中のコンボは、既存のキャンセルエンドポイントを使い、親注文IDまたはクライアント注文IDでキャンセルします。

置き換え: PUT /order は、同じコンボ定義内で親注文をアトミックに置き換えることができます。置き換えが拒否された場合、元の注文はそのまま残ります。一括置き換えのネイティブエントリも親注文ごとに1つのアトミックなコマンドを使用しますが、バッチ全体が1つのオールオアナッシングのトランザクションになるわけではありません。コンボとアウトライトの間、または異なるコンボ定義の間での置き換えは拒否されます。

自己取引防止: ルートがアカウント自身と取引しようとする前にマッチングを停止し、待機中のメイカー注文をキャンセルします。それ以前に完了した約定は残り、入ってきた注文の残量はキャンセルされます。それ以前の約定がない場合、入ってきた注文は拒否されます。FOK注文と失敗したアトミックな置き換えは、暫定的なメイカーキャンセルのロールバックも含め、オールオアナッシングの挙動を維持します。

最初の注文でコンボを定義する

署名前に正規化してください: 重複する銘柄IDを統合し、ゼロの比率を削除し、IDを数値順に並べ、比率を最大公約数で割り、最初の比率をプラスにします。正規化によって比率が反転した場合は、意図した注文のサイドを反転し、ネット価格の符号を反転します。比率をある係数で割った場合は、パッケージサイズにその係数を掛け、ネット価格をその係数で割ります。

バージョン1のIDは、以下を連結したもののKeccak-256です:

UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
     instrument ID as 32 big-endian bytes
     ratio as signed 64-bit two's-complement big-endian

銘柄IDは、UTF-8の "instrument" に正規化されたオプションシンボルをそのまま続けたもののKeccak-256です。公開されるコンボIDはダイジェスト全体で、0x と64文字の小文字16進数としてエンコードされます。コンボシンボルは COMBO- の後に同じ16進数字を使用します。

combo_definition を通常の署名付き POST /order のボディに含めます。定義には version、id、legs が含まれ、各レッグには instrument_id と ratio が含まれます。IDは 0x と64文字の小文字16進数で、比率は "1" や "-1" のような正規の符号付き10進文字列でエンコードしてください。比率にJSONの数値、先頭のプラス記号、先頭のゼロを使用すると拒否されます。

{
  "combo_definition": {
    "version": 1,
    "id": "<canonical content hash as 0x plus 64 hex digits>",
    "legs": [
      {"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
      {"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
    ]
  }
}

この断片は、上記の完全な注文例に追加されます。プレースホルダーを実際のIDに置き換え、対応する COMBO- シンボルを使用してください。追加の定義署名や、別途の公開用nonceはありません。サービスは正規化された内容とその識別子を署名済みシンボルと照合して検証します。アウトライト注文では combo_definition を省略する必要があります。

受理と検索: 受理されたすべてのコンボ注文は、永続的な注文レコードに定義を保持し、カタログエントリの存在を冪等に保証します。後続の注文が最初の作成レコードを上書きすることはありません。即時に約定した注文でも検索データは作成されますが、拒否された注文では作成されません。検索はコミット済みデータから投影されるため、注文の確認応答より遅れる場合があります。後続の注文で同じ定義を再送信することはサポートされており、最初のカタログエントリがまだ追いついていない間でも可能です。

注文と約定を読み取る

リクエスト	目的
`GET /experimental/orders`	コンボの親注文を含め、明示的な銘柄分類付きで注文を読み取る
`GET /experimental/trades`	デフォルトでは実際のレッグの取引を読み取り、`view=packages&symbol=<COMBO symbol>` を指定すると1つのコンボのパッケージサマリーを読み取る
`GET /experimental/fills`	デフォルトではウォレットの約定を読み取り、`view=packages` を指定するとウォレットのパッケージサマリーを読み取る

サポートされるフィルターとカーソルについては、RESTリファレンスを参照してください。パッケージビューは offset ではなく、limit(1〜1,000、デフォルト100)と before_execution_id でページングします。次のページを取得するには、返された next_before_execution_id を渡してください。パッケージの取引には正規の COMBO- の symbol が必要です。パッケージの約定は wallet と任意の symbol を受け付けます。パッケージサマリーはグループ化のためのレコードです: 約定IDとレッグの取引IDを使って、実際のオプション約定と結合できます。アカウントの合計を計算する際に、パッケージの数量、プレミアム、手数料を構成要素の約定に加算しないでください。

識別子の精度: 実験的な注文ID、パッケージ約定ID、構成要素の取引/注文ID、親注文ID、パッケージのページネーションカーソルは10進文字列です。クライアントでは文字列のまま保持してください。JavaScriptの数値に変換すると精度が失われる可能性があります。従来の view=legs レスポンスは既存の表現を維持します。

互換性: 従来の銘柄検索と注文ビューは、アウトライトの契約を維持します。実際のオプションレッグの約定は引き続き従来の取引/約定フィードに表示され、ポジションはオプションポジションのままです。コンボの親注文は、独立して待機するレッグ注文の集合ではありません。

明示的にサブスクライブする

実験的なプライベートチャネルには、既存のWebSocket認証ステップと明示的なサブスクリプションが必要です。認証済みウォレットの親レコードのみが配信されます。

チャネル	メッセージ	対象
`experimental_order_updates`	親ID、シンボル、銘柄タイプ(`option`、`perp`、または `combo`)、ステータス、数量、約定済み数量、ネット価格を含む `ExperimentalOrderUpdate`	認証済みウォレット
`experimental_combo_trades`	約定ID、シンボル、パッケージ数量、ネット価格、レッグの取引IDを含む `ComboTrade`	公開
`experimental_combo_fills`	ウォレットの親注文ID、サイド、パッケージ約定を含む `ComboFill`	認証済みウォレット

{"type":"Subscribe","channel":"experimental_order_updates"}

ExperimentalOrderUpdate.status は Acked、Open、PartiallyFilled、Filled、Canceled、Rejected を使用し、OrderUpdate の大文字の値は使用しません。IDと数量は文字列です。

検索したコンボシンボルを使って、既存のオーダーブックチャネルをサブスクライブします:

{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}

マーケット検索の更新では、同じ不変の定義が繰り返し届く場合があります。コンボIDで重複を除去してください。これらは market_updates 上の MarketUpdate を使用し、action: "ComboCreated"、コンボシンボル、ID、正規化されたレッグ、タイムスタンプを含みます。クライアントで照合する際は、検索、親注文のステータス、パッケージ約定サマリー、実際のレッグ約定を別個のレコードとして扱ってください。

コンボを検索する​

サイド、価格、サイズを理解する​

注文を発注する​

最初の注文でコンボを定義する​

注文と約定を読み取る​

明示的にサブスクライブする​