永続的なクエリとページネーション

このガイドは、Agent Java SDK v0.3.0、Java 8 以降、およびタグ付けされたパブリック コントラクトを対象としています。例は client を初期化した後にパートナー バックエンドで実行されます。 クイックスタート.

前提条件の例

Java スニペットはこれらのインポートを共有します。クイック スタートを使用して client を初期化し、保存されたバインディングから platformUserId を取得します。ユーザー/オーダー ID の例は、独自の永続化された値に置き換える必要があります。

import com.sixmm.agent.*;
import com.sixmm.agent.model.*;
import java.util.*;

無期限契約データのクエリ

6種類のインターフェースとJavaメソッド

すべてのリクエストは、/v1/agent/perpetual という共通のプレフィックスが付いた POST で署名されます。

platformUserIds は、パブリック プラットフォーム ID の文字列配列です。指定する場合は、アクセス権を持つ 1 ～ 100 人の固有のプレーヤーが必要です。省略が許可されているエンドポイントでは、現在の販売者がアクセスできる直接プレーヤーの範囲のみがクエリされます。トレードフィルクエリには常にこの配列が必要です。条件付き順序クエリにも明示的なユーザー ID が必要です。省略は [] と同等ではなく、空の配列は不正です。スコープは署名するマーチャントによって決定され、スコープを拡張するために他のマーチャント ID を渡すことはできません。

配列値は、署名ペイロードに結合する前に、コンパクト JSON としてシリアル化されます。たとえば、platformUserIds は ["1188041528"] として署名し、k=v ペイロードに platformUserIds=["1188041528"] を与えます。配列要素の順序、二重引用符、文字列 ID を保持します。書式設定スペースを挿入したり、Java List.toString() ([1188041528] など) を使用したりしないでください。 SDK はこのシリアル化を自動的に処理します。

注文クエリは orderCategory=NORMAL または CONDITIONAL を渡す必要があります。通常の注文には orderId を使用し、条件付き注文には conditionId を使用します。カテゴリ間で混在させることはできません。条件付き注文と、条件付き注文をトリガーして生成された通常の注文は、エンティティとして別々に処理されます。

フィルター条件

履歴クエリの時間は Unix ミリ秒、間隔は [startTime, endTime) です。署名を要求した時間は timestamp です、Unix 秒です。 UTC 時間枠を固定してセグメント単位でクエリを実行することをお勧めします。毎日の調整には UTC を使用してください。ステータスとタイプはプラットフォーム コントラクトの列挙を使用し、それ自体は中国語の文字列に翻訳されません。

limit デフォルトは 500、範囲は 1 ～ 1000 です。ページ サイズは、毎回同じ数値が返されることを保証するものではありません。現在、6 つのインターフェイスは、マーチャントごとに 1 秒あたり 2 回と 4 バーストのクエリ クォータを共有しており、インスタンス内の各マーチャントの最大同時実行制限は 2 です。マーチャント側は統合キューを使用しており、連続ページングと小さな履歴ウィンドウから始めることをお勧めします。

Java クエリの例

プレーヤーの現在の通常のオーダーをクエリします。

CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest();
current.orderCategory = "NORMAL";
current.platformUserIds = Collections.singletonList(platformUserId);
current.symbol = "BTCUSDT";
current.limit = 100;
PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current);

過去 1 時間の契約変更を照会し、カーソルを処理します。次の例では、自動的に再試行されません。実際のアプリケーションで現在の制限または一時的な障害が発生した場合は、リンクされた関連ガイドに従って同じページを復元してください。

PerpetualLedgerRequest ledger = new PerpetualLedgerRequest();
ledger.platformUserIds = Collections.singletonList(platformUserId);
ledger.endTime = System.currentTimeMillis();
ledger.startTime = ledger.endTime - 3_600_000L;
ledger.limit = 100;
Set<String> seenCursors = new HashSet<>();
while (true) {
    PerpetualResponse page = client.listPerpetualLedger(ledger);
    for (PerpetualRecord row : page.data.items) {
        // Persist records idempotently by platformUserId, entityType and entityId.
    }
    if (!page.data.hasMore) {
        break;
    }
    String next = page.data.nextCursor;
    if (next == null || next.isEmpty() || !seenCursors.add(next)) {
        throw new IllegalStateException("游标未推进，停止查询并排查");
    }
    ledger.cursor = next;
    Thread.sleep(650L); // Other queries must share the same partner rate-limit queue.
}

戻り値の構造と保存ルール

見る 一般的な応答とページネーション 共有フィールド用。リソースフィールドは次の場所に文書化されています。 注文, 取引約定, ポジション そして 契約台帳.

6 つのインターフェイスは一律に PerpetualResponse を返します。

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [],
    "nextCursor": "",
    "hasMore": false
  }
}

それぞれの items には platformUserId、entityType、entityId、data が含まれます。エンティティ タイプには、ORDER、CONDITION_ORDER、TRADE_FILL、POSITION、ACCOUNT_LEDGER があります。これら 3 つの ID フィールドを使用して冪等キーを構築します。条件付き注文 ID、注文 ID、約定 ID を同じ番号として扱わないでください。

data 価格、数量、ステータス、経費、損益、リソースごとの残高変化などのフィールドを提供します。金額、価格、数量、およびエンティティ ID は文字列として処理されます。ビジネスタイムはミリ秒単位です。欠落しているフィールドは 0 に埋められず、他のエンティティから推測されません。

カーソルはクエリのページング位置であり、信頼性の高い増分サブスクリプションや、保証されたクロスページのアトミック スナップショットではありません。現在のカーソルは、最初の生成から 24 時間有効です。後続のページングでは、同じ販売者、リソース、プレーヤーのコレクション、およびフィルター条件が保持されます。履歴プルの固定ウィンドウは、繰り返しプルされると冪等になります。現在の注文/ポジションのステータスは、再クエリ後に更新されます。リアルタイム インターフェイスが必要な場合、プラットフォーム フロントエンドのデータ メカニズムが使用され、ポーリング 6 インターフェイスは高頻度市場インターフェイスと見なすことはできません。

エラーとリカバリ

HTTP の成功はビジネスの成功を意味するものではありません。code を確認する必要があります。 Java SDK は、ビジネス エラーを AgentApiException としてスローします。

cursor および元の失敗したページのすべてのフィルター条件は、電流制限、タイムアウト、または一時的な失敗の後も保持されます。 SDK が再度呼び出されるたびに、新しい timestamp、nonce、sign が生成されます。次のページに直接ジャンプしたり、失敗を空の結果として扱うことはできません。 SDK は、ファンド取引を自動的に再試行する責任を負いません。

一般的な応答とページネーション

各 data.items[] の構造:

同じ ledgerId で、手数料、損益などの複数の詳細を分離できます。 ledgerId を押して重複を削除すると、データが失われます。異なるリソースの ID を混在させることはできません。ページングおよびフィールド保存ルールについては、アクセス ガイドのリンクされた関連ガイドを参照してください。

型、単位、および省略されたフィールド

• 金額、価格、数量、およびエンティティ ID には文字列が使用されます。金額の処理には 10 進数を使用し、浮動小数点数を使用したり、長い ID を JavaScript 数値に変換したりすることはできません。金額通貨と数量単位は、取引ペア/契約の仕様に従って説明されます。
• ビジネス時間には整数 (int64) が使用され、どちらも Unix ミリ秒です。要求認証タイムスタンプとエントリ資格情報 expireAt は秒を使用するため、混同することはできません。
• 通常、文字列ビジネス フィールドは空の場合は出力されず、数値フィールドが 0 の場合は一部が省略されます。 フィールドが欠落していても、ビジネス値が 0 であることを意味するわけではありません。
• 一般レコードモデルの reduceOnly、closeOnly、makerOnly は false を省略しないため、これら 3 つの false がトランザクションまたはポジションにも現れる可能性があります。これらは、リソースの順序でのみ説明されています。トランザクション/ポジションが対応する注文ルールを実行したとはみなされません。
• closePosition はオプションのブール値です。条件付き命令によって提供され、通常は他のリソースでは省略されます。 Missing は false とは異なる意味を持ちます。
• 以下の表の「現在提供されている」は、読み取りロジックにフィールド ソースがあることを意味します。オプションのフィールドには値がないため、省略することもできます。モデルに存在するフィールドは、すべてのインターフェイスに入力されることが保証されているわけではありません。

ステータスモードとマージンモードの違い

通常の注文の CANCELED のスペルは、条件付き注文の CANCELLED のスペルとは異なります。条件付き注文のトリガーは、生成された通常注文が約定されたことを意味するものではありません。すべてのリソースに対して同じステータス変換テーブルのセットを再利用しないでください。

条件付き順序 marginMode は CROSS / ISOLATED を返します。過去の通常の注文とポジションは現在「1」/「2」を返します。これらはそれぞれクロス/分離証拠金です。 marginMode は現在通常のご注文を受け付けておりません。販売者は独自の表示レイヤーのリソースによって正規化できますが、元の値を保存する必要があります。

モデルで宣言されているが、このクエリでは提供されていないフィールド

Generic RecordData / Java PerpetualData モデルは次のフィールドも宣言しますが、現在の 6 カテゴリの実稼働読み取りロジックではこれらのフィールドに値が設定されません。 **利用可能なビジネス データとしてリストされるべきではなく、フィールドのデフォルト値を実際の結果に置き換えるべきではありません。 **

実際のフィールド アプリケーションの範囲は、上記のリソース テーブルの影響を受けます。プラットフォームがフィールドまたは列挙を更新する場合、新しいインターフェイスの説明と SDK バージョンに従って適応されます。

ソースおよび関連ガイド

• 公式 v0.3.0 ソース
• 資金調達ウォレット
• アップグレードガイド