> 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. # Kueri & Paginasi Abadi Panduan ini menargetkan **Agent Java SDK `v0.3.0`**, Java 8+, dan kontrak publik yang diberi tag. Contoh dijalankan di backend mitra setelah menginisialisasi `client` di [Mulai Cepat](/id/sdk/agent-sdk/java/quick-start). ## Contoh prasyarat Cuplikan Java membagikan impor ini. Inisialisasi `client` menggunakan Quick Start dan dapatkan `platformUserId` dari pengikatan yang disimpan. Contoh ID pengguna/pesanan harus diganti dengan nilai Anda yang tetap. ```java import com.sixmm.agent.*; import com.sixmm.agent.model.*; import java.util.*; ``` ## Kueri data kontrak perpetual ### Enam jenis antarmuka dan metode Java Semua permintaan ditandatangani POST dengan awalan umum `/v1/agent/perpetual`. | akhiran jalur | Java Metode/Jenis Permintaan | jangkauan pemain | | -------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- | | `/orders/current` | `listCurrentPerpetualOrders(CurrentPerpetualOrdersRequest)` | NORMAL Pemain dapat dihilangkan; CONDITIONAL Pemain harus ditentukan | | `/orders/history` | `listPerpetualOrderHistory(PerpetualOrderHistoryRequest)` | Sama seperti di atas | | `/trades` | `listPerpetualTrades(PerpetualTradesRequest)` | Pemain harus ditentukan | | `/positions/current` | `listCurrentPerpetualPositions(CurrentPerpetualPositionsRequest)` | Pemain dapat dihilangkan | | `/positions/history` | `listPerpetualPositionHistory(PerpetualPositionHistoryRequest)` | Pemain dapat dihilangkan | | `/account/ledger` | `listPerpetualLedger(PerpetualLedgerRequest)` | Pemain dapat dihilangkan | `platformUserIds` adalah rangkaian string ID platform publik. Jika ditentukan, diperlukan 1 hingga 100 pemain unik yang memiliki akses; pada titik akhir yang memungkinkan penghilangan, hanya kisaran pemain langsung yang dapat diakses oleh pedagang saat ini yang ditanyakan. Kueri isi dagang selalu memerlukan larik ini; kueri pesanan bersyarat juga memerlukan ID pengguna eksplisit. Kelalaian tidak setara dengan `[]`, dan array kosong adalah ilegal. Cakupannya ditentukan oleh pedagang yang menandatangani, dan ID pedagang lainnya tidak dapat diteruskan untuk memperluas cakupan. Nilai array diserialkan sebagai kompak JSON sebelum bergabung dengan payload penandatanganan. Misalnya, `platformUserIds` ditandai sebagai `["1188041528"]`, memberikan `platformUserIds=["1188041528"]` dalam payload `k=v`. Pertahankan urutan elemen array, tanda kutip ganda, dan ID string; jangan menyisipkan spasi pemformatan atau menggunakan Java `List.toString()` (seperti `[1188041528]`). SDK menangani serialisasi ini secara otomatis. Kueri pesanan harus melewati `orderCategory=NORMAL` atau `CONDITIONAL`. Gunakan `orderId` untuk pesanan biasa dan `conditionId` untuk pesanan bersyarat. Mereka tidak dapat dicampur antar kategori. Pesanan bersyarat dan pesanan biasa yang dihasilkan dengan memicunya diproses secara terpisah sebagai entitas. ### Menyaring kondisi | Pertanyaan | Filter bisnis yang tersedia | | ------------------- | -------------------------------------------------------------------------------------------------------------- | | Pesanan saat ini | `orderCategory`, `symbol` | | tatanan sejarah | `orderCategory`, `symbol`, `startTime`, `endTime`, `orderId`, `conditionId`, `clientOrderId`, `side`, `status` | | membuat kesepakatan | `symbol`, `startTime`, `endTime`, `orderId` | | Posisi saat ini | `symbol` | | Posisi bersejarah | `symbol`, `startTime`, `endTime`, `positionSide` | | Perubahan kontrak | `startTime`, `endTime`, `assetType`, `changeType` | Waktu kueri historis adalah Unix **milidetik**, dan intervalnya adalah `[startTime, endTime)`; waktu permintaan tanda tangan adalah `timestamp` adalah Unix **detik**. Disarankan untuk memperbaiki jangka waktu UTC dan kueri dalam segmen; gunakan UTC untuk rekonsiliasi harian. Status dan jenis menggunakan enumerasi kontrak platform dan tidak diterjemahkan ke dalam string bahasa Mandarin sendiri. `limit` Defaultnya adalah 500, rentangnya adalah 1\~1000; ukuran halaman tidak menjamin bahwa nomor yang sama akan dikembalikan setiap saat. Keenam antarmuka saat ini berbagi kuota kueri sebanyak 2 kali per detik dan 4 burst per pedagang, dan batas konkurensi maksimum untuk setiap pedagang dalam instans adalah 2. Sisi pedagang menggunakan antrean terpadu, dan disarankan untuk memulai dengan paging berurutan dan jendela riwayat yang lebih kecil. ### Java contoh kueri Kueri pesanan biasa pemain saat ini: ```java CurrentPerpetualOrdersRequest current = new CurrentPerpetualOrdersRequest(); current.orderCategory = "NORMAL"; current.platformUserIds = Collections.singletonList(platformUserId); current.symbol = "BTCUSDT"; current.limit = 100; PerpetualResponse currentPage = client.listCurrentPerpetualOrders(current); ``` Kueri perubahan kontrak dalam satu jam terakhir dan proses kursor. Contoh berikut tidak mencoba ulang secara otomatis; ketika aplikasi sebenarnya mengalami batasan saat ini atau kegagalan sementara, ikuti panduan terkait yang tertaut untuk memulihkan halaman yang sama. ```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. } ``` ### Struktur pengembalian dan aturan penyimpanan Melihat [Respon umum dan penomoran halaman](#common-response-and-pagination) untuk bidang bersama. Bidang sumber daya didokumentasikan dalam [Pesanan](/id/sdk/agent-sdk/java/perpetual-orders), [Perdagangan terisi](/id/sdk/agent-sdk/java/perpetual-trades), [Posisi](/id/sdk/agent-sdk/java/perpetual-positions) Dan [Buku besar kontrak](/id/sdk/agent-sdk/java/perpetual-ledger). Keenam antarmuka secara seragam mengembalikan `PerpetualResponse`: ```json { "code": 0, "message": "success", "data": { "items": [], "nextCursor": "", "hasMore": false } } ``` Setiap `items` berisi `platformUserId`, `entityType`, `entityId`, `data`. Tipe entitas mencakup `ORDER`, `CONDITION_ORDER`, `TRADE_FILL`, `POSITION`, `ACCOUNT_LEDGER`. Gunakan ketiga bidang identitas ini untuk membuat kunci idempoten; jangan perlakukan ID pesanan bersyarat, ID pesanan, dan ID pengisian sebagai nomor yang sama. `data` Menyediakan kolom seperti harga, kuantitas, status, pengeluaran, laba dan rugi, atau perubahan saldo berdasarkan sumber daya. Jumlah, harga, kuantitas, dan ID entitas ditangani sebagai string; waktu bisnis dalam milidetik. Bidang yang hilang tidak diisi hingga 0 dan tidak disimpulkan dari entitas lain. Kursor adalah posisi halaman kueri, bukan langganan tambahan yang dapat diandalkan, atau snapshot atomik lintas halaman yang dijamin. Kursor saat ini berlaku selama 24 jam sejak putaran pertama pembuatan; paging berikutnya mempertahankan pedagang, sumber daya, koleksi pemain, dan kondisi filter yang sama. Jendela tetap untuk tarikan historis adalah idempoten ketika ditarik berulang kali; status pesanan/posisi saat ini disegarkan setelah kueri ulang. Ketika antarmuka real-time diperlukan, mekanisme data front-end platform digunakan, dan antarmuka enam polling tidak dapat dianggap sebagai antarmuka pasar frekuensi tinggi. ### Kesalahan dan pemulihan HTTP sukses bukan berarti sukses dalam bisnis, anda harus mencentang `code`. Java SDK akan memunculkan kesalahan bisnis sebagai `AgentApiException`. | Kode bisnis | Arti yang khas | Penanganan | | ----------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `102001` | Parameter yang diperlukan tidak ada, misalnya, kueri pesanan bersyarat tidak ada pemain. | Berikan parameter yang hilang | | `102002` | Parameter ilegal, array kosong, kursor tidak cocok, atau kedaluwarsa | Perbaiki parameternya; periksa kembali jendela yang diperbaiki setelah menghapus kursor yang kedaluwarsa dan simpan secara idempoten. | | `102003` | Batas ilegal, jumlah pemain, atau rentang waktu | Cakupan sempit atau benar | | `6001` | Kesalahan tanda tangan | Periksa bidang kunci, serialisasi array, dan tanda tangan | | `6009` | Metode akses pedagang atau cakupan akses tidak diperbolehkan | Periksa izin pedagang dan kepemilikan pemain | | `6904` | Layanan tidak tersedia untuk sementara, konkurensi, atau perlindungan sumber daya kueri | Mengurangi konkurensi dan mengecilkan jendela; hubungi dukungan jika kesalahan terus berlanjut | | `6905` | Kuota bersama untuk enam jenis kueri telah habis | Mundur, lalu coba lagi halaman asli yang gagal | `cursor` dan semua kondisi filter dari halaman asli yang gagal akan dipertahankan setelah pembatasan saat ini, batas waktu, atau kegagalan sementara; setiap kali SDK dipanggil kembali, `timestamp`, `nonce`, `sign` baru akan dihasilkan. Anda tidak bisa langsung melompat ke halaman berikutnya, dan Anda tidak bisa menganggap kegagalan sebagai hasil kosong. SDK tidak bertanggung jawab untuk mencoba ulang transaksi dana secara otomatis. ## Respon umum dan penomoran halaman | Bidang | JSON ketik | menjelaskan | | ----------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | integer | Kode bisnis, 0 berarti sukses; jika bukan 0, maka akan dianggap sebagai kesalahan, dan kegagalan tidak akan dianggap sebagai halaman kosong. | | `message` | string | Deskripsi hasil bukanlah satu-satunya dasar penilaian bisnis. | | `data` | object | Hasil paginasi pada kesuksesan | | `data.items` | array | Catatan di halaman ini; halaman kosong yang sah adalah `[]` | | `data.nextCursor` | string | Kursor halaman berikutnya; biasanya string kosong jika tidak ada halaman berikutnya | | `data.hasMore` | boolean | Apakah ada halaman berikutnya; bila benar, gunakan nextCursor untuk melanjutkan kueri yang sama | Struktur masing-masing `data.items[]`: | Bidang | JSON ketik | menjelaskan | | ---------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- | | `platformUserId` | string | ID pengguna publik platform, disimpan sebagai string; bukan ID pengguna basis data internal | | `entityType` | string | Jenis entitas tempat rekaman tersebut berada, lihat tabel di bawah | | `entityId` | string | Pengidentifikasi entitas saat ini digabungkan dengan pengguna platform dan tipe entitas untuk membuat kunci idempoten lokal. | | `data` | object | Bidang usaha badan ini; bidang sumber daya yang berbeda berbeda | | Sumber daya kueri | `entityType` | `entityId` Korespondensi | | ---------------------------- | ----------------- | ------------------------------------------------------------------------ | | Pesanan biasa | `ORDER` | `data.orderId` | | perintah bersyarat | `CONDITION_ORDER` | `data.conditionId` | | Detail pengisian perdagangan | `TRADE_FILL` | `data.fillId`, bukan tradeId | | Posisi saat ini/historis | `POSITION` | `data.positionId` | | Catatan buku besar kontrak | `ACCOUNT_LEDGER` | Identifikasi detail perubahan akun tunggal, \*\* bukan data.ledgerId\*\* | `ledgerId` yang sama dapat memisahkan beberapa detail seperti biaya penanganan, keuntungan dan kerugian, dll.; menekan ledgerId untuk menghapus duplikat akan menyebabkan hilangnya data. ID dari sumber yang berbeda tidak dapat dicampur. Lihat panduan terkait yang tertaut dari Panduan Akses untuk aturan paging dan penyimpanan bidang. ## Jenis, unit, dan bidang yang dihilangkan * Jumlah, harga, kuantitas, dan ID entitas menggunakan string; menggunakan desimal untuk memproses jumlah, dan tidak dapat menggunakan angka floating point atau mengonversi ID panjang menjadi Nomor JavaScript. Jumlah mata uang dan satuan kuantitas dijelaskan sesuai dengan spesifikasi pasangan perdagangan/kontrak. * Waktu bisnis menggunakan bilangan bulat (int64), keduanya milidetik Unix; meminta stempel waktu autentikasi dan kredensial entri expireAt menggunakan hitungan detik dan tidak dapat disalahartikan. * Bidang bisnis string biasanya tidak ditampilkan saat kosong, dan beberapa akan dihilangkan jika bidang numerik bernilai 0. **Kolom yang hilang bukan berarti nilai bisnis adalah 0**. * `reduceOnly`, `closeOnly`, `makerOnly` dalam model pencatatan umum tidak menghilangkan false, sehingga ketiga false ini juga dapat muncul dalam transaksi atau posisi. Mereka hanya dijelaskan dalam urutan sumber daya; tidak dapat dianggap bahwa transaksi/posisi mengeksekusi aturan order yang sesuai. * `closePosition` adalah boolean opsional: disediakan oleh perintah bersyarat, biasanya dihilangkan untuk sumber daya lain. Hilang memiliki arti yang berbeda dengan salah. * Tabel di bawah "saat ini disediakan" berarti logika baca memiliki sumber bidang; bidang opsional masih dapat dihilangkan karena tidak memiliki nilai. Field yang ada pada model tidak dijamin terisi di setiap antarmuka. ## Perbedaan antara status dan mode margin | sumber | nilai pengembalian saat ini | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Status pesanan biasa saat ini | NEW, PENDING, PARTIALLY_FILLED | | Status pesanan biasa historis | FILLED, CANCELED, REJECTED, PARTIAL_FILLED_CANCELED, atau PARTIALLY_FILLED_CANCELED; pertahankan ejaan sumber sebenarnya | | Status pesanan kondisi saat ini / triggerStatus | PENDING_ACTIVATION, PENDING, TRIGGERING | | Status pesanan kondisi historis / triggerStatus | TRIGGERED, CANCELLED, REJECTED, FIRED | | Status posisi saat ini | String numerik "1" dalam posisi, "3" dalam likuidasi | | Status posisi historis | String numerik "2" telah menutup posisi, "4" telah memaksa likuidasi | Ejaan CANCELED untuk tatanan biasa berbeda dengan CANCELLED untuk tatanan bersyarat; memicu order bersyarat tidak berarti order biasa yang dihasilkan telah terpenuhi. Jangan menggunakan kembali kumpulan tabel terjemahan status yang sama untuk semua sumber daya. Urutan bersyarat marginMode mengembalikan CROSS / ISOLATED; pesanan dan posisi biasa historis saat ini menghasilkan "1" / "2", yang masing-masing merupakan margin silang/terisolasi. marginMode saat ini tidak tersedia untuk pesanan biasa. Pedagang dapat melakukan normalisasi berdasarkan sumber daya di lapisan tampilan mereka sendiri, dan nilai aslinya masih perlu disimpan. ## Bidang yang dideklarasikan dalam model tetapi tidak disediakan dalam kueri ini Generic RecordData / Java Model PerpetualData juga mendeklarasikan kolom berikut, namun logika baca produksi enam kategori saat ini tidak mengisinya. \*\*Tidak boleh dicantumkan sebagai data bisnis yang tersedia, dan default bidang juga tidak boleh diganti dengan hasil nyata. \*\* | Bidang | Tipe model | batas saat ini | | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- | | `closeReason` | string | Alasan penutupan posisi historis tidak diberikan | | `walletDelta` | string | Antarmuka perubahan akun tidak mengembalikan delta dompet | | `frozenDelta` | string | Antarmuka perubahan akun tidak mengembalikan delta yang dibekukan | | `usedDelta` | string | Antarmuka perubahan akun tidak mengembalikan delta margin yang digunakan | | `feeDelta` | string | Antarmuka perubahan akun tidak mengembalikan biaya delta | | `pnlDelta` | string | Antarmuka perubahan akun tidak mengembalikan delta untung dan rugi | | `accountVersion` | string | Antarmuka perubahan akun tidak mengembalikan versi akun dan tidak dapat digunakan untuk sinkronisasi tambahan yang andal. | | `occurredAt` | integer | Antarmuka perubahan akun menggunakan createdAt dan tidak menyediakan kumpulan waktu terjadinya peristiwa lainnya. | Cakupan penerapan lapangan sebenarnya tunduk pada tabel sumber daya di atas; ketika platform memperbarui bidang atau enumerasi, bidang atau enumerasi tersebut harus disesuaikan sesuai dengan deskripsi antarmuka baru dan versi SDK. ## Sumber dan panduan terkait * [Sumber resmi v0.3.0](https://github.com/6mm-com/agent-java-sdk/tree/54aa3c1) * [Dompet pendanaan](/id/sdk/agent-sdk/java/funding-wallet) * [Panduan peningkatan](/id/sdk/agent-sdk/java/upgrade)