> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.6mm.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server. # 永続的なクエリとページネーション このガイドは、**Agent Java SDK `v0.3.0`**、Java 8 以降、およびタグ付けされたパブリック コントラクトを対象としています。例は `client` を初期化した後にパートナー バックエンドで実行されます。 [クイックスタート](/ja/sdk/agent-sdk/java/quick-start). ## 前提条件の例 Java スニペットはこれらのインポートを共有します。クイック スタートを使用して `client` を初期化し、保存されたバインディングから `platformUserId` を取得します。ユーザー/オーダー ID の例は、独自の永続化された値に置き換える必要があります。 ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## 無期限契約データのクエリ ### 6種類のインターフェースとJavaメソッド すべてのリクエストは、`/v1/agent/perpetual` という共通のプレフィックスが付いた POST で署名されます。 | パス接尾辞 | Java メソッド/リクエスト タイプ | プレイヤー範囲 | | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- | | `/orders/current` | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)` | NORMAL player は省略できます。 CONDITIONAL プレーヤーを指定する必要があります | | `/orders/history` | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)` | 同上 | | `/trades` | `listPerpetualTrades(PerpetualTradesRequest)` | プレーヤーを指定する必要があります | | `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | プレイヤーは省略可能 | | `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)` | プレイヤーは省略可能 | | `/account/ledger` | `listPerpetualLedger(PerpetualLedgerRequest)` | プレイヤーは省略可能 | `platformUserIds` は、パブリック プラットフォーム ID の文字列配列です。指定する場合は、アクセス権を持つ 1 ～ 100 人の固有のプレーヤーが必要です。省略が許可されているエンドポイントでは、現在の販売者がアクセスできる直接プレーヤーの範囲のみがクエリされます。トレードフィルクエリには常にこの配列が必要です。条件付き順序クエリにも明示的なユーザー ID が必要です。省略は `[]` と同等ではなく、空の配列は不正です。スコープは署名するマーチャントによって決定され、スコープを拡張するために他のマーチャント ID を渡すことはできません。 配列値は、署名ペイロードに結合する前に、コンパクト JSON としてシリアル化されます。たとえば、`platformUserIds` は `["1188041528"]` として署名し、`k=v` ペイロードに `platformUserIds=["1188041528"]` を与えます。配列要素の順序、二重引用符、文字列 ID を保持します。書式設定スペースを挿入したり、Java `List.toString()` (`[1188041528]` など) を使用したりしないでください。 SDK はこのシリアル化を自動的に処理します。 注文クエリは `orderCategory=NORMAL` または `CONDITIONAL` を渡す必要があります。通常の注文には `orderId` を使用し、条件付き注文には `conditionId` を使用します。カテゴリ間で混在させることはできません。条件付き注文と、条件付き注文をトリガーして生成された通常の注文は、エンティティとして別々に処理されます。 ### フィルター条件 | クエリ | 利用可能なビジネスフィルター | | ----- | ------------------------------------------------------------------------------------------------------- | | 現在の注文 | `orderCategory`、`symbol` | | 歴史的順序 | `orderCategory`、`symbol`、`startTime`、`endTime`、`orderId`、`conditionId`、`clientOrderId`、`side`、 `status` | | 取引をする | `symbol`、`startTime`、`endTime`、`orderId` | | 現在位置 | `symbol` | | 歴史的地位 | `symbol`、`startTime`、`endTime`、`positionSide` | | 契約変更 | `startTime`、`endTime`、`assetType`、`changeType` | 履歴クエリの時間は Unix **ミリ秒**、間隔は `[startTime, endTime)` です。署名を要求した時間は `timestamp` です、Unix **秒**です。 UTC 時間枠を固定してセグメント単位でクエリを実行することをお勧めします。毎日の調整には UTC を使用してください。ステータスとタイプはプラットフォーム コントラクトの列挙を使用し、それ自体は中国語の文字列に翻訳されません。 `limit` デフォルトは 500、範囲は 1 ～ 1000 です。ページ サイズは、毎回同じ数値が返されることを保証するものではありません。現在、6 つのインターフェイスは、マーチャントごとに 1 秒あたり 2 回と 4 バーストのクエリ クォータを共有しており、インスタンス内の各マーチャントの最大同時実行制限は 2 です。マーチャント側は統合キューを使用しており、連続ページングと小さな履歴ウィンドウから始めることをお勧めします。 ### Java クエリの例 プレーヤーの現在の通常のオーダーをクエリします。 ```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 時間の契約変更を照会し、カーソルを処理します。次の例では、自動的に再試行されません。実際のアプリケーションで現在の制限または一時的な障害が発生した場合は、リンクされた関連ガイドに従って同じページを復元してください。 ```java PerpetualLedgerRequest ledger = new PerpetualLedgerRequest(); ledger.platformUserIds = Collections.singletonList(platformUserId); ledger.endTime = System.currentTimeMillis(); ledger.startTime = ledger.endTime - 3_600_000L; ledger.limit = 100; Set 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. } ``` ### 戻り値の構造と保存ルール 見る [一般的な応答とページネーション](#common-response-and-pagination) 共有フィールド用。リソースフィールドは次の場所に文書化されています。 [注文](/ja/sdk/agent-sdk/java/perpetual-orders), [取引約定](/ja/sdk/agent-sdk/java/perpetual-trades), [ポジション](/ja/sdk/agent-sdk/java/perpetual-positions) そして [契約台帳](/ja/sdk/agent-sdk/java/perpetual-ledger). 6 つのインターフェイスは一律に `PerpetualResponse` を返します。 ```json { "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` としてスローします。 | 事業者コード | 代表的な意味 | 取り扱い | | -------- | --------------------------------------------- | ------------------------------------------------------ | | `102001` | 必須パラメータが欠落しています。たとえば、条件付き順序クエリにプレーヤーが欠落しています。 | 不足しているパラメータを指定します | | `102002` | 不正なパラメータ、空の配列、カーソルの不一致、または期限切れ | パラメータを修正してください。期限切れのカーソルをクリアした後、固定ウィンドウを再確認し、冪等に保存します。 | | `102003` | 不正な制限、プレイヤー数、または時間範囲 | 狭い範囲または正しい範囲 | | `6001` | 署名エラー | キー、配列シリアル化、および署名フィールドをチェックします。 | | `6009` | 販売者のアクセス方法またはアクセス範囲は許可されていません | 販売者の権限とプレーヤーの所有権を確認する | | `6904` | サービスは一時的に利用できません。同時実行またはクエリ リソースの保護 | 同時実行性を減らし、ウィンドウを縮小します。エラーが解決しない場合はサポートにお問い合わせください | | `6905` | 6 種類のクエリの共有割り当てが枯渇しました | 後戻りして、元の失敗したページを再試行してください | `cursor` および元の失敗したページのすべてのフィルター条件は、電流制限、タイムアウト、または一時的な失敗の後も保持されます。 SDK が再度呼び出されるたびに、新しい `timestamp`、`nonce`、`sign` が生成されます。次のページに直接ジャンプしたり、失敗を空の結果として扱うことはできません。 SDK は、ファンド取引を自動的に再試行する責任を負いません。 ## 一般的な応答とページネーション | 分野 | JSON タイプ | 説明する | | ----------------- | -------- | --------------------------------------------------------- | | `code` | integer | ビジネス コード。0 は成功を意味します。 0 でない場合はエラーとして扱われ、失敗は空ページとして扱われません。 | | `message` | string | 結果の説明は経営判断の唯一の根拠ではありません。 | | `data` | object | 成功した場合のページ分割された結果 | | `data.items` | array | このページの記録。法的な空のページは `[]` です | | `data.nextCursor` | string | 次のページのカーソル。後続のページがない場合は通常は空の文字列 | | `data.hasMore` | boolean | 後続のページがあるかどうか。 true の場合、nextCursor を使用して同じクエリを続行します | 各 `data.items[]` の構造: | 分野 | JSON タイプ | 説明する | | ---------------- | -------- | --------------------------------------------------------------- | | `platformUserId` | string | プラットフォームのパブリック ユーザー ID。文字列として保存されます。内部データベースのユーザー ID ではありません | | `entityType` | string | レコードが属するエンティティ タイプ。以下の表を参照してください。 | | `entityId` | string | 現在のエンティティの識別子は、プラットフォーム ユーザーおよびエンティティ タイプと結合されて、ローカル冪等キーを構築します。 | | `data` | object | このエンティティの事業分野。リソースフィールドが異なれば異なる | | クエリリソース | `entityType` | `entityId` 通信 | | -------- | ----------------- | -------------------------------------------- | | 通常の順序 | `ORDER` | `data.orderId` | | 条件付き注文 | `CONDITION_ORDER` | `data.conditionId` | | 取引約定の詳細 | `TRADE_FILL` | `data.fillId`、tradeIdではありません | | 現在/過去の役職 | `POSITION` | `data.positionId` | | 契約台帳記録 | `ACCOUNT_LEDGER` | 単一アカウント変更の詳細識別。\*\* はデータではありません。ledgerId\*\* | 同じ `ledgerId` で、手数料、損益などの複数の詳細を分離できます。 ledgerId を押して重複を削除すると、データが失われます。異なるリソースの ID を混在させることはできません。ページングおよびフィールド保存ルールについては、アクセス ガイドのリンクされた関連ガイドを参照してください。 ## 型、単位、および省略されたフィールド * 金額、価格、数量、およびエンティティ ID には文字列が使用されます。金額の処理には 10 進数を使用し、浮動小数点数を使用したり、長い ID を JavaScript 数値に変換したりすることはできません。金額通貨と数量単位は、取引ペア/契約の仕様に従って説明されます。 * ビジネス時間には整数 (int64) が使用され、どちらも Unix ミリ秒です。要求認証タイムスタンプとエントリ資格情報 expireAt は秒を使用するため、混同することはできません。 * 通常、文字列ビジネス フィールドは空の場合は出力されず、数値フィールドが 0 の場合は一部が省略されます。 **フィールドが欠落していても、ビジネス値が 0 であることを意味するわけではありません**。 * 一般レコードモデルの `reduceOnly`、`closeOnly`、`makerOnly` は false を省略しないため、これら 3 つの false がトランザクションまたはポジションにも現れる可能性があります。これらは、リソースの順序でのみ説明されています。トランザクション/ポジションが対応する注文ルールを実行したとはみなされません。 * `closePosition` はオプションのブール値です。条件付き命令によって提供され、通常は他のリソースでは省略されます。 Missing は false とは異なる意味を持ちます。 * 以下の表の「現在提供されている」は、読み取りロジックにフィールド ソースがあることを意味します。オプションのフィールドには値がないため、省略することもできます。モデルに存在するフィールドは、すべてのインターフェイスに入力されることが保証されているわけではありません。 ## ステータスモードとマージンモードの違い | リソース | 現在の戻り値 | | ---------------------------- | ---------------------------------------------------------------------------------------------- | | 現在の通常注文状況 | NEW、PENDING、PARTIALLY_FILLED | | 過去の通常注文状況 | FILLED、CANCELED、REJECTED、PARTIAL_FILLED_CANCELED、または PARTIALLY_FILLED_CANCELED;実際のソースのスペルを維持する | | 現在の注文ステータス / triggerStatus | PENDING_ACTIVATION、PENDING、TRIGGERING | | 履歴条件の注文ステータス / triggerStatus | TRIGGERED、CANCELLED、REJECTED、FIRED | | 現在位置ステータス | 数値文字列「1」はポジションにあり、「3」は清算中です | | 過去のポジションのステータス | 数値文字列「2」はポジションをクローズし、「4」は強制清算を示します | 通常の注文の CANCELED のスペルは、条件付き注文の CANCELLED のスペルとは異なります。条件付き注文のトリガーは、生成された通常注文が約定されたことを意味するものではありません。すべてのリソースに対して同じステータス変換テーブルのセットを再利用しないでください。 条件付き順序 marginMode は CROSS / ISOLATED を返します。過去の通常の注文とポジションは現在「1」/「2」を返します。これらはそれぞれクロス/分離証拠金です。 marginMode は現在通常のご注文を受け付けておりません。販売者は独自の表示レイヤーのリソースによって正規化できますが、元の値を保存する必要があります。 ## モデルで宣言されているが、このクエリでは提供されていないフィールド Generic RecordData / Java PerpetualData モデルは次のフィールドも宣言しますが、現在の 6 カテゴリの実稼働読み取りロジックではこれらのフィールドに値が設定されません。 \*\*利用可能なビジネス データとしてリストされるべきではなく、フィールドのデフォルト値を実際の結果に置き換えるべきではありません。 \*\* | 分野 | モデルタイプ | 現在の境界 | | ---------------- | ------- | ------------------------------------------------------- | | `closeReason` | string | 過去のポジションをクローズする理由は提供されていません | | `walletDelta` | string | アカウント変更インターフェースはウォレットの差分を返しません | | `frozenDelta` | string | アカウント変更インターフェイスは凍結されたデルタを返しません | | `usedDelta` | string | 口座変更インターフェースが使用済み証拠金デルタを返さない | | `feeDelta` | string | アカウント変更インターフェースは料金の差分を返しません | | `pnlDelta` | string | 口座変更インターフェースでは損益デルタが返されません | | `accountVersion` | string | アカウント変更インターフェイスはアカウントのバージョンを返さないため、信頼性の高い増分同期には使用できません。 | | `occurredAt` | integer | アカウント変更インターフェイスは createdAt を使用し、別のイベント発生時間のセットを提供しません。 | 実際のフィールド アプリケーションの範囲は、上記のリソース テーブルの影響を受けます。プラットフォームがフィールドまたは列挙を更新する場合、新しいインターフェイスの説明と SDK バージョンに従って適応されます。 ## ソースおよび関連ガイド * [公式 v0.3.0 ソース](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [資金調達ウォレット](/ja/sdk/agent-sdk/java/funding-wallet) * [アップグレードガイド](/ja/sdk/agent-sdk/java/upgrade)