Konvensi API
Aturan yang berlaku di semua endpoint: tata letak URL, envelope respons, simbol, satuan, stempel waktu, paginasi, dan caching.
URL dasar dan versi
Semua endpoint berada di bawah satu URL dasar dan dipanggil dengan HTTPS GET. Path saat ini adalah versi v1. Di dalam v1, perubahan bersifat aditif: kolom dan endpoint dapat ditambahkan, sedangkan kolom yang sudah ada tetap mempertahankan nama, tipe, dan maknanya. Perubahan yang merusak kompatibilitas akan dirilis di bawah path baru dan diumumkan lebih dulu di catatan perubahan.
https://www.coinboss.com/apiEnvelope respons
Setiap respons JSON memiliki flag success di tingkat teratas. Endpoint lapisan data mandiri, yaitu data yang dikumpulkan sendiri (path di bawah /api/sd), memiliki blok tambahan yang sama:
| Kolom | Deskripsi |
|---|---|
| success | true jika panggilan berhasil. Selalu periksa nilainya. |
| schema | Pengidentifikasi dan versi mayor dari bentuk respons. |
| now | Waktu server saat respons disusun, dalam milidetik. |
| coverage | Bursa mana yang disertakan, mana yang tidak tersedia beserta alasannya, dan mana yang dikecualikan karena usang. |
| method | Rumus atau aturan di balik setiap agregat dalam respons. |
| meta | Sumber, stempel waktu, jendela, peringkat kualitas, flag usang, masa berlaku cache, dan perilaku fallback. |
Endpoint lama mengembalikan success beserta kolom data dan mungkin tidak menyertakan coverage, method, atau meta. Halaman referensinya mendokumentasikan kolom-kolomnya secara persis.
Koin, kontrak, dan bursa
- Parameter coin menerima simbol dasar dalam huruf besar, misalnya BTC atau PEPE.
- Kontrak berpengali seperti 1000PEPE atau kPEPE digabung ke koin dasarnya, dengan kuantitas yang dikonversi.
- Pengidentifikasi bursa ditulis dengan huruf kecil, misalnya binance, okx, bybit, hyperliquid.
- Simbol kontrak dikembalikan sesuai penamaan dari bursa. Kontrak bermargin USDT, USDC, dan koin serta kontrak berjangka dengan jatuh tempo dibedakan melalui kolom jenis kontrak pada endpoint yang mencampurkannya.
- Kontrak perpetual saham tertokenisasi dan komoditas yang ticker-nya sama dengan aset kripto dikecualikan dari agregat kripto.
Satuan
- Kolom yang berakhiran _usd adalah nilai nosional dalam dolar AS.
- Funding rate berupa pecahan, bukan persen: 0.0001 berarti 0.01%. Kolom yang berakhiran _8h dinormalkan ke interval 8 jam; interval aslinya dikembalikan di samping rate mentahnya.
- Kolom yang berakhiran _pct adalah persentase: 1.5 berarti 1.5%.
- Open interest adalah nilai nosional satu sisi dalam USD kecuali deskripsi kolom menyatakan lain. Bursa yang memublikasikan angka dua sisi dicatat di blok method.
- Beberapa endpoint lawas mengembalikan desimal sebagai string untuk menjaga presisi. Tabel kolom menampilkan tipenya sebagai string(decimal).
Stempel waktu
- Stempel waktu berupa milidetik Unix epoch dalam UTC kecuali deskripsi kolom menyatakan lain.
- observed_at adalah stempel waktu dari bursa itu sendiri untuk catatan terbaru yang disertakan, atau null jika bursa tidak menyediakannya.
- received_at adalah saat kolektor CoinBoss menyimpan catatan tersebut.
- fetched_at adalah saat respons disusun. Pada respons dari cache, nilainya lebih lama daripada waktu panggilan Anda, dengan selisih paling banyak sebesar TTL cache.
- Deret harian memakai batas hari UTC.
Jendela dan interval
- Parameter jendela memakai token pendek: 1h, 4h, 12h, 24h, dan pada beberapa endpoint 3d, 7d, 30d, 90d. Halaman referensi mencantumkan nilai yang diterima untuk setiap endpoint.
- Nilai jendela yang tidak dikenal akan ditolak dengan INVALID_PARAM atau dialihkan ke default yang didokumentasikan, sebagaimana dinyatakan per parameter.
- Ukuran bucket untuk deret waktu bergantung pada jendela dan dinyatakan di halaman referensi.
Paginasi dan pengurutan
- Endpoint daftar memakai limit dan offset, atau page dan size, sebagaimana didokumentasikan per endpoint. Limit memiliki batas atas; nilai yang lebih besar diturunkan ke batas tersebut.
- Jika respons menyertakan total, nilainya adalah jumlah baris sebelum paginasi.
- Urutan bersifat tetap kecuali endpoint mendokumentasikan parameter pengurutan.
Null, nol, dan tidak ada
- null berarti nilainya tidak diketahui atau tidak tersedia. 0 berarti nol yang terukur.
- Grafik harus menampilkan celah untuk null. Jangan melakukan interpolasi.
- Kolom bertanda “bisa tidak ada” di tabel kolom dapat sepenuhnya tidak muncul di objek; perlakukan seperti null.
Caching
- Setiap endpoint memiliki TTL cache server, yang ditampilkan di halaman referensinya dan sebagai meta.cache_ttl_s. Header X-Cache melaporkan HIT, STALE, atau MISS.
- Cache edge singkat berdurasi sekitar sepuluh detik berada di depan sebagian besar endpoint GET.
- Polling yang lebih cepat daripada TTL mengembalikan data yang identik dan hanya menghabiskan batas permintaan Anda.
WebSocket
wss://www.coinboss.com/ws- Stream berupa JSON yang hanya dikirim satu arah dari server. Setiap pesan memiliki kolom type.
- Setelah koneksi terputus, sambungkan kembali dengan jeda dan lakukan backfill dari endpoint HTTP yang bersesuaian.
Dokumentasi yang dapat dibaca mesin
Katalog, parameter dan tabel kolom setiap endpoint, status, serta matriks kualitas tersedia sebagai JSON di bawah /api/meta, dan seluruh katalog tersedia sebagai dokumen OpenAPI 3.