Panduan API WEEX: Dari Kunci API hingga Pesanan Pertama Anda yang Ditandatangani

Sebagian besar integrasi API WEEX tidak gagal karena logika strategi. Mereka gagal dalam satu jam pertama, karena empat hal yang tidak jelas sampai Anda menemukannya: kunci yang baru Anda buat belum aktif, pasangan yang ingin Anda perdagangkan tidak ada dalam daftar putih API, koneksi WebSocket Anda ditolak karena Anda tidak mengirim header User-Agent, dan tanda tangan Anda meleset satu byte karena Anda menandatangani badan yang diserialisasi ulang alih-alih string persis yang Anda kirim.

Panduan ini menelusuri API WEEX dari awal hingga akhir — pembuatan kunci, izin, aturan penandatanganan, batas tarif, kode kesalahan yang benar-benar menghentikan build, dan endpoint paper-trading yang memungkinkan Anda menguji semuanya tanpa modal yang berisiko. Semua di bawah ini diperiksa terhadap dokumentasi V3 langsung pada 21 Agustus 2026.

Apa yang dicakup oleh API WEEX: spot, futures, dan WebSocket

API WEEX dibagi menjadi dua produk independen dengan dua domain REST independen. Spot berada di api-spot.weex.com di bawah jalur /api/v3. Futures berada di api-contract.weex.com di bawah jalur /capi/v3. Mereka berbagi skema penandatanganan dan set header, tetapi tidak ada yang lain — flag izin terpisah, host WebSocket terpisah, parameter pesanan terpisah.

Endpoint terbagi menjadi dua kelas akses. Endpoint publik (waktu server, kedalaman order book, kline, tingkat pendanaan, ticker 24 jam) tidak memerlukan autentikasi sama sekali, yang menjadikannya cara tercepat untuk mengonfirmasi bahwa jalur jaringan Anda berfungsi sebelum Anda menyentuh penandatanganan. Endpoint pribadi — saldo, posisi, pesanan — memerlukan tanda tangan empat header penuh pada setiap permintaan.

Untuk apa pun di tingkat tick, WEEX mendorong Anda ke WebSocket daripada polling REST, dan itu adalah keputusan yang tepat: saluran publik membawa stream ticker, kedalaman, dan perdagangan, dan saluran pribadi membawa pembaruan akun, posisi, dan pesanan. Melakukan polling kedalaman melalui REST untuk membangun order book akan menghabiskan anggaran bobot IP Anda tanpa manfaat.

Satu titik referensi bertanggal untuk skala: per 21 Agustus 2026, kontrak perpetual BTC/USDT mengutip harga terakhir 65.088,8 USDT di buku futures WEEX — tick yang sama yang dikembalikan oleh panggilan /capi/v3/market/ticker24h Anda.

Cara membuat kunci API WEEX dan mengatur izin

Kunci dibuat dari Akun → Manajemen API di platform web. Setiap akun dapat menampung hingga 10 grup kunci API.

Pembuatan mengembalikan tiga nilai, dan yang ketiga adalah yang sering hilang dari orang-orang:

• APIKey — pengenal publik, dikirim dalam header ACCESS-KEY.
• SecretKey — rahasia penandatanganan HMAC. Ditampilkan sekali.
• Passphrase — ditentukan pengguna, dikirim dalam ACCESS-PASSPHRASE. Tidak dapat diubah dan tidak dapat dipulihkan. Jika hilang, Anda harus membuat ulang kuncinya.

Tiga detail konfigurasi menyebabkan lebih banyak tiket dukungan daripada gabungan semua hal lainnya:

1. Kunci baru default ke Read-only. Izin perdagangan adalah kotak centang terpisah, dan spesifik untuk produk — Spot untuk perdagangan spot, Futures untuk kontrak. Mencentang satu tidak mengaktifkan yang lain. Menempatkan pesanan pada kunci Read-only mengembalikan -1052.
2. Kunci membutuhkan waktu sekitar 15 menit untuk menyebar secara global. Kunci yang diautentikasi dengan baik dan kemudian gagal pada endpoint yang berbeda biasanya hanya belum sepenuhnya aktif. Tunggu sebelum Anda mulai men-debug tanda tangan Anda.
3. Jaga agar passphrase tetap alfanumerik. WEEX secara eksplisit merekomendasikan tanpa karakter khusus. Ketidakcocokan pengkodean dalam karakter khusus adalah kelas bug yang benar-benar menyedihkan untuk dikejar.

Ikat daftar putih IP saat Anda berada di layar pembuatan. Kunci yang tidak terikat adalah kredensial pembawa yang berfungsi dari mana saja di internet, dan jika mesin yang memegangnya disusupi, daftar putih adalah satu-satunya hal yang berdiri di antara penyerang dan posisi Anda.

API spot WEEX vs API futures: perbedaan yang penting

Ini adalah tabel untuk tetap terbuka saat Anda membangun. Kedua produk terlihat simetris padahal tidak.

Dua dari ini paling menyulitkan. Futures memerlukan newClientOrderId pada setiap pesanan, jadi basis kode spot-first yang menghilangkannya akan ditolak saat Anda mengarahkannya ke kontrak. Dan POST_ONLY hanya ada pada futures — strategi maker-only yang ditulis terhadap API spot tidak memiliki cara asli untuk menjamin bahwa itu tidak melintasi spread.

Parameter TP/SL futures layak mendapatkan lebih banyak perhatian daripada yang biasanya mereka dapatkan. Melampirkan tpTriggerPrice dan slTriggerPrice ke pesanan masuk berarti stop Anda ada di bursa sejak posisi terbuka, alih-alih ditempatkan oleh panggilan tindak lanjut yang mungkin tidak bertahan dari crash proses atau partisi jaringan. Anda juga dapat memilih sumber pemicu per kaki melalui TpWorkingType dan SlWorkingType — MARK_PRICE untuk stop adalah default yang lebih aman, karena CONTRACT_PRICE dapat melonjak oleh cetakan perdagangan terakhir yang tipis pada pasangan yang tidak likuid.

Cara menandatangani permintaan API WEEX dengan benar

Setiap panggilan pribadi membawa empat header: ACCESS-KEY, ACCESS-SIGN, ACCESS-PASSPHRASE, ACCESS-TIMESTAMP, ditambah Content-Type: application/json.

Aturan penandatanganan identik pada kedua domain. Bangun string ini:

timestamp + METHOD + requestPath + "?" + queryString + body

Hapus ? dan queryString jika tidak ada parameter kueri; hapus body jika tidak ada. HMAC-SHA256 dengan SecretKey Anda, lalu Base64-encode hasilnya.

import base64, hashlib, hmac, json, time, requests

API_KEY, SECRET, PASSPHRASE = "...", "...", "..."
BASE = "https://api-contract.weex.com"
path = "/capi/v3/order"
body = json.dumps({
    "symbol": "BTCUSDT", "side": "BUY", "positionSide": "LONG",
    "type": "LIMIT", "timeInForce": "GTC", "quantity": "0.01",
    "price": "60000", "newClientOrderId": "my-order-0001",
}, separators=(",", ":"))

ts = str(int(time.time() * 1000))
message = ts + "POST" + path + body
sign = base64.b64encode(
    hmac.new(SECRET.encode(), message.encode(), hashlib.sha256).digest()
).decode()

r = requests.post(BASE + path, data=body, headers={
    "ACCESS-KEY": API_KEY, "ACCESS-SIGN": sign,
    "ACCESS-PASSPHRASE": PASSPHRASE, "ACCESS-TIMESTAMP": ts,
    "Content-Type": "application/json",
})

Perhatikan data=body, bukan json=payload. Tandatangani byte persis yang Anda kirimkan. Jika klien HTTP Anda menserialisasi ulang dict — menyusun ulang kunci atau menyisipkan spasi setelah pemisah — server menghitung digest yang berbeda dan Anda mendapatkan -1047, tanpa petunjuk bahwa penyebabnya adalah spasi putih.

Jendela waktu adalah 30 detik terhadap waktu server WEEX. Jika jam host Anda melambat, permintaan mulai gagal secara berkala dengan cara yang terlihat seperti bug penandatanganan. Panggil GET /capi/v3/market/time dan lacak offset daripada mempercayai waktu lokal.

Saluran pribadi WebSocket ditandatangani secara berbeda dan ini menjebak orang: pesannya hanya timestamp + requestPath, di mana requestPath adalah /v3/ws/private. Tidak ada metode, tidak ada badan.

Satu keunikan dokumentasi yang perlu diketahui sebelum Anda copy-paste: halaman Tanda Tangan futures mengilustrasikan aturan menggunakan jalur spot (/api/v3/order). Aturannya benar; jalur contohnya bukan jalur futures. Gunakan /capi/v3/... saat Anda berada di domain kontrak.

Batas tarif API WEEX: dua bucket, bukan satu

WEEX menjalankan dua penghitung batas tarif independen, dan mencampurkannya adalah alasan mengapa bot mendapatkan 429 yang tidak mereka duga.

Detail konsekuensinya: penempatan pesanan mengonsumsi nol bobot IP, dan pembatalan serta kueri mengonsumsi nol hitungan pesanan. Mereka benar-benar buku besar yang terpisah. Loop market-making yang menempatkan dan membatalkan secara agresif akan menghabiskan bucket PESANAN saat penempatan sementara lalu lintas pembatalannya diam-diam menguras bobot IP — dan tidak ada penghitung yang memperingatkan Anda tentang yang lain.

Baca header daripada menghitung permintaan di sisi klien. X-REMAINING-WEIGHT-1M dan X-ORDER-REMAINING-1M kembali pada setiap panggilan dan mencerminkan pandangan server, yang merupakan satu-satunya pandangan yang penting. Melebihi batas mengembalikan HTTP 429 dan memicu larangan 10 detik, dan terus memukul melalui 429 adalah rute tercepat untuk membuat akses API dinonaktifkan oleh kontrol risiko.

Jika Anda menjalankan beberapa strategi dari satu kotak, ingatlah bahwa bucket IP dibagikan. Dua bot di satu server bersaing untuk bobot 500 yang sama per 10 detik.

Kesalahan API WEEX yang menghentikan sebagian besar integrasi

Respons kesalahan adalah pasangan kode dan pesan. Ini adalah yang muncul selama integrasi daripada di produksi:

-1058 layak mendapatkan alur kerja khusus. Tidak setiap kontrak WEEX diaktifkan untuk perdagangan API, dan tidak ada cara untuk menyimpulkan mana dari UI. Panggil GET /capi/v3/market/apiTradingSymbols saat startup, cache array, dan validasi simbol terhadapnya sebelum strategi Anda membuat pesanan. Satu pemeriksaan itu menghilangkan seluruh kelas kegagalan runtime.

Dua lagi yang terlihat seperti bug dan bukan. Handshake WebSocket yang mengembalikan 403 hampir selalu berarti Anda menghilangkan header User-Agent — kontennya arbitrer, tetapi firewall menjatuhkan koneksi tanpanya. Dan dokumen saat ini tidak setuju tentang kegagalan pembatalan: referensi kode kesalahan memetakan -1054 ke kesalahan sistem generik dan -3200 ke "pesanan tidak ada," sementara FAQ futures mengaitkan "pesanan tidak ada" ke -1054. Tangani kedua kode pada jalur pembatalan daripada bercabang pada satu.

Uji pada endpoint paper trading WEEX terlebih dahulu

WEEX menambahkan endpoint perdagangan simulasi pada domain futures, dan mereka mencerminkan permukaan langsung cukup dekat untuk menjadi uji coba nyata daripada mainan:

• GET /capi/v3/sim/balance — saldo simulasi, dalam SUSDT
• GET /capi/v3/sim/position/allPosition — posisi, termasuk pasangan long/short mode lindung nilai
• POST /capi/v3/sim/order — penempatan pesanan di seluruh jenis biasa
• GET /capi/v3/sim/order/history — pengisian simulasi historis

Domain yang sama, header yang sama, aturan penandatanganan yang sama. Menukar /capi/v3/order untuk /capi/v3/sim/order seringkali merupakan satu-satunya perubahan yang diperlukan untuk menjalankan uji integrasi penuh.

Gunakan mereka untuk memvalidasi bagian dari sistem Anda yang hanya rusak dalam kondisi nyata: logika sambungkan kembali setelah WebSocket terputus, apakah mesin status pesanan Anda pulih ketika pengisian tiba sebelum pengakuan REST, apakah ukuran posisi Anda melakukan hal yang benar pada batas leverage. Itu adalah kegagalan yang memakan biaya dalam produksi, dan tidak satu pun dari mereka memerlukan modal langsung untuk muncul.

Perlu diketahui sebelum Anda merancang di sekitarnya: WEEX saat ini tidak mendukung eksekusi webhook TradingView maupun gateway FIX. Jika strategi Anda mengasumsikan salah satunya, anggarkan untuk REST dan WebSocket sebagai gantinya.

Kesimpulan

API WEEX mudah setelah Anda menginternalisasi bahwa spot dan futures adalah dua produk yang berbagi skema penandatanganan dan hampir tidak ada yang lain. Dapatkan empat header dengan benar, tandatangani byte persis yang Anda kirim, cache daftar putih simbol perdagangan API, baca header batas tarif daripada menghitung permintaan, dan tangani -1047, -1052, dan -1058 secara eksplisit — itu mencakup sebagian besar dari apa yang salah.

Urutan yang paling sedikit membuang waktu: buat kunci dengan izin Read-only, konfirmasi endpoint publik merespons, buat satu bacaan pribadi yang ditandatangani berfungsi, jalankan strategi lengkap Anda terhadap endpoint paper-trading, dan baru kemudian aktifkan izin perdagangan dan ikat daftar putih IP. Referensi endpoint lengkap ada di dokumentasi API futures WEEX dan dokumentasi API spot WEEX, dengan spesifikasi izin dan batas tarif dikumpulkan di FAQ API futures.

FAQ

1. Apakah saya memerlukan kunci API WEEX terpisah untuk spot dan futures?

Tidak — satu kunci dapat membawa kedua izin. Tetapi mereka adalah kotak centang terpisah, dan masing-masing default ke mati. Kunci dengan hanya Spot dicentang akan mengembalikan -1052 pada setiap pesanan futures, dan sebaliknya.

2. Berapa batas tarif API WEEX?

Dua bucket independen: 500 bobot per 10 detik per IP untuk endpoint REST umum, dan 300 penempatan pesanan per menit per akun untuk futures. WebSocket dibatasi hingga 20 koneksi bersamaan per IP, 100 saluran per koneksi. Melebihi salah satunya mengembalikan HTTP 429 dan larangan 10 detik.

3. Mengapa kunci API WEEX saya mengembalikan -1049 tepat setelah saya membuatnya?

Kunci baru dan yang dimodifikasi membutuhkan waktu sekitar 15 menit untuk menyebar di seluruh sistem WEEX. Jika kuncinya baru, tunggu sebelum men-debug lebih lanjut. Jika tetap ada, periksa apakah passphrase berisi karakter khusus — WEEX merekomendasikan hanya alfanumerik.

4. Bisakah saya memperdagangkan setiap pasangan WEEX melalui API?

Tidak. Hanya pasangan dalam daftar putih perdagangan API yang tersedia secara terprogram. Panggil GET /capi/v3/market/apiTradingSymbols untuk daftar saat ini; apa pun di luarnya mengembalikan -1058.

5. Apakah WEEX mendukung peringatan TradingView atau FIX?

Tidak didukung per pembaruan dokumentasi April 2026. Otomatisasi berjalan melalui API REST dan WebSocket.

6. Bagaimana cara saya menguji strategi API WEEX tanpa mempertaruhkan dana?

Gunakan endpoint paper-trading futures di bawah /capi/v3/sim/. Mereka menerima autentikasi dan penandatanganan yang sama seperti endpoint langsung dan diselesaikan dalam SUSDT simulasi.

Peringatan Risiko

Aset kripto fluktuatif dan dapat kehilangan nilai dengan cepat; memperdagangkannya dapat mengakibatkan hilangnya modal sebagian atau seluruhnya. Perdagangan API memusatkan risiko itu daripada menguranginya. Sistem otomatis dapat menempatkan ratusan pesanan sebelum manusia menyadari kesalahan, dan kesalahan tanda tangan, umpan harga yang basi, atau sambungkan kembali yang tidak tertangani dapat membuka posisi yang tidak dimaksudkan oleh siapa pun. Perdagangan futures menambah risiko leverage: dengan leverage tersedia hingga 400x pada beberapa kontrak WEEX, pergerakan yang merugikan dapat melikuidasi posisi dalam hitungan detik, dan menggunakan CONTRACT_PRICE sebagai pemicu stop di pasar yang tipis membuat Anda terpapar pada stop-out yang didorong oleh sumbu. Kunci API juga merupakan risiko kustodian — kunci yang tidak terikat dengan izin perdagangan adalah kredensial langsung yang berfungsi dari IP mana pun di internet. Ikat daftar putih IP, jaga izin perdagangan tetap mati sampai integrasi Anda diuji terhadap endpoint paper-trading, dan ukur posisi dengan asumsi bahwa kode Anda sendiri pada akhirnya akan berperilaku buruk.