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.

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.

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.

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

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:

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.

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.
}

Struktur pengembalian dan aturan penyimpanan

Melihat Respon umum dan penomoran halaman untuk bidang bersama. Bidang sumber daya didokumentasikan dalam Pesanan, Perdagangan terisi, Posisi Dan Buku besar kontrak.

Keenam antarmuka secara seragam mengembalikan PerpetualResponse:

{
  "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.

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

Struktur masing-masing data.items[]:

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

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. **

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
• Dompet pendanaan
• Panduan peningkatan