Platform Hyperliquid menonjol sebagai bursa terdesentralisasi berkinerja tinggi untuk kontrak berjangka abadi (perpetual futures), menawarkan perdagangan latensi rendah dan fitur canggih untuk pengembang. Pengembang sering menggunakan API Hyperliquid untuk mengotomatiskan perdagangan, memantau pasar, dan membangun aplikasi kustom.
Anda memulai dengan memahami komponen inti dari API Hyperliquid. API ini terbagi menjadi kategori-kategori utama: Info API untuk menanyakan data pasar, Exchange API untuk tindakan perdagangan, dan WebSocket untuk pembaruan real-time. Selain itu, SDK dalam bahasa seperti Python dan Node.js menyederhanakan interaksi. Seiring Anda melanjutkan, Anda akan melihat bagaimana penyesuaian kecil dalam parameter permintaan menghasilkan peningkatan signifikan dalam efisiensi eksekusi.
Apa Itu API Hyperliquid?
API Hyperliquid memungkinkan akses terprogram ke bursa perpetual terdesentralisasi Hyperliquid. Ini mendukung operasi di lingkungan mainnet dan testnet. Anda terhubung ke mainnet dan testnet. API ini menggunakan JSON untuk permintaan dan respons, mengandalkan HTTP POST untuk sebagian besar tindakan dan WebSocket untuk langganan.
Anda melakukan otentikasi menggunakan kunci pribadi (private keys) daripada kunci API tradisional dalam beberapa kasus, tetapi Hyperliquid juga menawarkan dompet API untuk delegasi yang aman. Dompet-dompet ini bertindak atas nama akun utama Anda tanpa izin penarikan, meningkatkan keamanan untuk perdagangan otomatis. Misalnya, Anda membuat dompet API melalui aplikasi Hyperliquid, mengotorisasinya, dan menggunakan kunci pribadinya dalam skrip Anda.
Selanjutnya, pertimbangkan tipe data. API ini menggunakan struct dan enum tertentu. Aset diidentifikasi oleh indeks dari daftar universe, sisi order menggunakan boolean (true untuk beli, false untuk jual), dan opsi time-in-force mencakup 'Gtc' untuk good 'til canceled. Anda mengambil detail ini dari endpoint metadata untuk memastikan akurasi dalam permintaan Anda.
Dengan dasar ini, Anda beralih ke pengaturan lingkungan pengembangan Anda. Konfigurasi yang tepat mencegah kesalahan umum dan mempercepat iterasi.
Menyiapkan Lingkungan Anda untuk API Hyperliquid
Anda memulai pengaturan dengan memilih bahasa pemrograman Anda dan menginstal SDK yang relevan. Untuk pengguna Python, hyperliquid-python-sdk menyediakan titik awal yang kuat. Instal melalui pip dengan perintah pip install hyperliquid-python-sdk. SDK ini menangani koneksi, otentikasi, dan operasi umum.
Anda kemudian mengonfigurasi kredensial Anda. Buat file config.json dengan alamat akun Anda (kunci publik) dan kunci rahasia (kunci pribadi). Untuk keamanan, Anda membuat dompet API khusus. Navigasi ke aplikasi Hyperliquid, pilih "Lainnya > API," masukkan nama untuk kunci, tempel alamat dompet Anda, dan klik "Buat." Otorisasi dompet API, dan salin kunci pribadinya ke dalam konfigurasi Anda.
SDK mengimpor konstanta untuk URL, seperti constants.TESTNET_API_URL untuk pengujian. Anda menginisialisasi klien seperti ini:
from hyperliquid.info import Info
from hyperliquid.utils import constants
info = Info(constants.TESTNET_API_URL, skip_ws=True)
Pengaturan ini awalnya melewati WebSocket, berfokus pada HTTP. Anda menguji koneksi dengan menanyakan status pengguna:
user_state = info.user_state("your_account_address")
print(user_state)
Jika respons menunjukkan detail akun Anda, lingkungan Anda berfungsi dengan benar. Namun, jika Anda mengalami kesalahan, periksa kunci pribadi dan pilihan jaringan Anda.
Untuk Node.js, Anda menggunakan paket @nktkas/hyperliquid. Instal dengan npm, lalu siapkan transport dan klien menggunakan ethers untuk manajemen dompet. Anda menentukan isTestnet: true untuk menghindari dana sungguhan selama pengembangan.
Alat seperti Apidog melengkapi pengaturan ini. Anda mengimpor spesifikasi API Hyperliquid ke Apidog, mengotentikasi dengan kunci Anda, dan mensimulasikan permintaan. Pendekatan ini mengungkapkan struktur respons dengan cepat, menghemat waktu pada pengkodean manual.
Setelah dikonfigurasi, Anda beralih ke metode otentikasi. Otentikasi yang tepat memastikan tindakan Anda dieksekusi dengan aman.
Otentikasi dengan API Hyperliquid
Anda melakukan otentikasi terutama melalui penandatanganan kunci pribadi (private key signing), karena Hyperliquid beroperasi pada sistem berbasis blockchain. SDK menangani penandatanganan secara otomatis saat Anda menyediakan instans dompet.
Untuk panggilan API langsung tanpa SDK, Anda menandatangani payload menggunakan kunci pribadi Anda. Badan permintaan mencakup nonce untuk perlindungan replay, dan Anda memposting ke endpoint /exchange atau /info.
Dompet API menambah fleksibilitas. Anda membuatnya dengan menamainya, menautkannya ke alamat dompet utama Anda, membuat kunci, dan mengotorisasinya. Dompet ini melakukan perdagangan tetapi tidak dapat menarik dana, mengurangi risiko untuk bot. Dalam kode, Anda menggunakan kunci pribadi dompet API sambil menentukan alamat akun utama.
Anda menguji otentikasi dengan mengirimkan permintaan info sederhana. Jika tidak diotorisasi, API akan mengembalikan kesalahan seperti "User or API Wallet does not exist." Untuk memperbaikinya, pastikan dompet Anda memiliki jaminan minimum, seperti USDC untuk perpetual.
Keamanan tetap menjadi yang utama. Anda menyimpan kunci dalam variabel lingkungan atau brankas aman, merotasinya secara berkala, dan memantau aktivitas yang tidak biasa. Dengan otentikasi yang sudah ada, Anda menjelajahi endpoint Info API.
Menjelajahi Endpoint Info API
Info API menyediakan akses hanya-baca ke data pasar dan akun. Anda menggunakannya untuk mengambil metadata, harga, order, dan lainnya, tanpa otentikasi untuk data publik.
Anda memulai dengan endpoint meta, yang mengembalikan universe aset dan konteks. Dalam Node.js:
const [meta] = await infoClient.metaAndAssetCtxs();
Ini menghasilkan array aset dengan nama, indeks, dan spesifikasi seperti leverage maksimum. Anda menggunakan indeks aset dalam permintaan perdagangan.
Selanjutnya, Anda menanyakan harga tengah dengan allMids, yang mengembalikan titik tengah saat ini untuk semua pasangan. Order terbuka berasal dari openOrders, yang membutuhkan alamat Anda.
Endpoint lain meliputi:
- userState: Mengambil posisi, margin, dan saldo.
- fundingHistory: Menunjukkan tingkat pendanaan dari waktu ke waktu.
- l2Book: Menyediakan buku order level 2 untuk suatu koin.
Anda mengirim permintaan POST dengan badan JSON seperti {"type": "meta"} ke /info. Respons menggunakan struktur yang konsisten, dengan "data" berisi hasil.
Apidog membantu di sini—Anda menyiapkan koleksi untuk Info API, menambahkan permintaan untuk setiap tipe, dan memparameterkan koin atau alamat. Visualisasi ini membantu dalam memahami aliran data.
Saat Anda mengumpulkan data, Anda beralih ke Exchange API untuk mengeksekusi perdagangan.
Menggunakan Endpoint Exchange API untuk Perdagangan
Exchange API menangani tindakan seperti membuat order, membatalkan, dan memodifikasi. Anda mengotentikasi semua permintaan dengan payload yang ditandatangani.
Anda menempatkan order dengan mendefinisikan parameter: indeks aset, sisi, harga, ukuran, flag reduce-only, dan tipe (limit atau market). Untuk penjualan limit:
Dalam Elixir (dari dokumen SDK):
Hyperliquid.Api.Exchange.place_order(order)
Di mana order adalah map dengan a: aset, b: false (jual), p: "100", s: "0.1", r: false, t: {limit: {tif: "Gtc"}}.
Respons mencakup status dan ID order jika berhasil.
Anda membatalkan order menggunakan aset dan oid (ID order):
Hyperliquid.Api.Exchange.cancel_order(asset, oid)
Untuk batch, Anda menggunakan cancel_orders dengan daftar.
Modifikasi mengikuti cara yang sama: tentukan oid dan parameter baru.
Tindakan lain termasuk memperbarui leverage:
Hyperliquid.Api.Exchange.update_leverage(asset, is_cross, leverage)
Dan transfer, seperti spot_perp_transfer untuk memindahkan dana antar akun.
Anda menangani kesalahan dengan memeriksa status respons— "ok" untuk keberhasilan, jika tidak detail seperti margin tidak mencukupi.
Contoh-contoh menunjukkan penggunaan praktis. Misalnya, Anda membangun bot yang menempatkan order beli ketika harga turun di bawah ambang batas, menggunakan info untuk pemeriksaan harga dan exchange untuk penempatan.
Selain itu, Anda mengintegrasikan WebSocket untuk pembaruan real-time guna meningkatkan responsivitas.
Mengintegrasikan WebSocket untuk Data Real-Time
Anda terhubung ke WebSocket untuk aliran data langsung. Gunakan wss://api.hyperliquid.xyz/ws untuk mainnet atau yang setara dengan testnet.
Anda berlangganan dengan mengirimkan JSON: {"method": "subscribe", "subscription": {"type": "trades", "coin": "SOL"}}.
Server merespons dengan konfirmasi, kemudian mendorong pembaruan seperti perdagangan baru.
Anda menangani topik seperti orderbook, peristiwa pengguna, dan notifikasi. Dalam Python SDK, atur skip_ws=False untuk mengaktifkan.
Kemampuan real-time ini memungkinkan Anda bereaksi secara instan terhadap perubahan pasar, seperti menyesuaikan order pada saat order terpenuhi.
Dengan endpoint yang telah dibahas, Anda akan memeriksa Python SDK secara mendalam.
Memanfaatkan Hyperliquid Python SDK
Python SDK mengabstraksi panggilan API ke dalam kelas. Anda mengimpor Info untuk kueri dan Exchange untuk tindakan.
Anda menempatkan order dasar seperti ini (dari contoh):
Pertama, muat konfigurasi:
import json
def address_and_private_key():
with open("examples/config.json") as f:
config = json.load(f)
return config["account_address"], config["secret_key"]
Kemudian, inisialisasi Exchange:
from hyperliquid.exchange import Exchange
from hyperliquid.utils import constants
address, private = address_and_private_key()
exchange = Exchange(address, private, base_url=constants.TESTNET_API_URL)
Tempatkan order:
order_result = exchange.order("BTC", True, 0.02, 30000, {"limit": {"tif": "Gtc"}})
print(order_result)
Ini membeli 0,02 BTC pada batas harga $30.000.
Anda memperluas ini untuk fitur-fitur canggih, seperti order batch atau pembatalan.
SDK juga mendukung alamat vault untuk akun yang dikelola.
Contoh-contoh di repositori mencakup basic_order, user_state, dan lainnya, menunjukkan alur kerja lengkap.
Saat Anda membangun, Anda menggabungkan praktik terbaik untuk mengoptimalkan kinerja.
Praktik Terbaik untuk Penggunaan API Hyperliquid
Anda memantau batas kecepatan (rate limits) untuk menghindari throttling—Hyperliquid menerapkan batas per-IP dan per-akun.
Anda menggunakan testnet untuk semua pengembangan guna mencegah kerugian finansial.
Penanganan kesalahan melibatkan pencatatan detail dan mencoba kembali kegagalan sementara dengan backoff.
Untuk skalabilitas, Anda melakukan batch permintaan jika memungkinkan, seperti beberapa pembatalan.
Keamanan meluas ke penggunaan dompet API dan prinsip hak akses paling rendah (least-privilege).
Anda juga membuat versi kode Anda dengan pembaruan SDK, karena Hyperliquid mengikuti semantic versioning.
Alat seperti Apidog membantu dalam mocking respons untuk pengujian unit.
Pemecahan masalah datang berikutnya ketika masalah muncul.
Memecahkan Masalah Umum API Hyperliquid
Anda menemui "Insufficient margin" (margin tidak mencukupi) ketika jaminan rendah—setor USDC untuk menyelesaikannya.
Jika "Asset not found" (aset tidak ditemukan), verifikasi indeks dari meta.
Kesalahan otentikasi berasal dari kunci yang tidak valid—buat ulang dan otorisasi dompet API.
Masalah jaringan memerlukan pemeriksaan URL dan penggunaan proxy jika diperlukan.
Anda men-debug dengan Apidog dengan memutar ulang permintaan yang gagal.
Log dari SDK menyediakan stempel waktu dan payload untuk analisis.
Dengan tips ini, Anda menjaga integrasi yang andal.
Kasus Penggunaan Lanjutan dengan API Hyperliquid
Anda membangun bot perdagangan yang memantau l2Book dan menempatkan order pada ketidakseimbangan.
Strategi melibatkan tingkat pendanaan dari riwayat untuk peluang arbitrase.
Sub-akun memungkinkan perdagangan yang terpisah: buat dengan nama, transfer dana, dan berdagang secara terpisah.
Transfer vault mendukung kumpulan likuiditas bersama.
Anda mensimulasikan dengan data historis dari API untuk backtest.
Integrasi dengan Apidog memungkinkan debugging kolaboratif dalam tim.
Akhirnya, Anda menyimpulkan dengan mempertimbangkan peningkatan di masa mendatang.
Kesimpulan: Menguasai API Hyperliquid untuk Perdagangan Terdesentralisasi
Anda sekarang memiliki pengetahuan untuk menggunakan API Hyperliquid secara efektif. Mulai dari pengaturan dan otentikasi hingga endpoint dan SDK, panduan ini membekali Anda untuk membangun aplikasi canggih. Ingat, penyempurnaan bertahap dalam kode Anda menghasilkan peningkatan kinerja yang substansial. Bereksperimenlah di testnet, manfaatkan alat seperti Apidog, dan tetap ikuti pembaruan dokumentasi Hyperliquid. Seiring platform berkembang, keterampilan Anda menempatkan Anda untuk memanfaatkan fitur-fitur baru.