Request API pertama: HTTP, header, dan JSON
Ringkasan
- Request HTTP ke API terdiri dari metode, alamat yang dibentuk dari base URL, path, dan parameter, serta header. Key Genesis API hanya dikirim lewat header
X-API-Key. - Kode status menentukan langkah berikutnya:
200baca datanya,304tidak ada yang berubah,401dan403periksa key dan paket,429dan503tungguRetry-Afterdetik. - Respons Genesis API berupa envelope berisi
success,data, danmeta. Persentase datang sebagai angka biasa (0.01berarti 0,01%), dan waktu dalam detik unix. - Kesalahan umum pemula: key di URL, variabel lingkungan kosong, serta salah ketik pada path atau nama parameter. Salah ketik parameter tidak memunculkan error: Anda mendapat seluruh dataset, bukan yang terfilter.
Untuk memanggil API, program Anda mengirim request HTTP yang terdiri dari metode, alamat, dan header, lalu server mengembalikan kode status, header-nya sendiri, dan body, yang pada Genesis API berupa JSON. Request bisa dikirim dari terminal dengan curl atau dari kode dalam bahasa apa pun yang punya HTTP client. Request pertama di bawah memeriksa key lewat /account/usage, dan request kedua mengambil funding rate BTC dari /funding/rates. Apa itu API dan apa saja yang bisa diotomatisasi dengannya dibahas di pelajaran 1.
Anatomi request
Ini adalah request funding rate BTC yang dikirim curl ke server, seperti ditampilkan flag -v pada baris berawalan > (key diganti placeholder):
> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
| Bagian | Pada contoh | Artinya |
|---|---|---|
| Metode | GET | Membaca data; semua endpoint Genesis API adalah GET |
| Base URL | https://api.genesisarbitrage.com/v1 | Server dan versi API |
| Path | /funding/rates | Endpoint funding rate |
| Parameter | ?coin=BTC | Filter: hanya BTC |
| Header | X-API-Key | Key yang dipakai server untuk mengenali akun dan paket Anda |
Parameter ditulis setelah ? sebagai pasangan nama=nilai yang digabung dengan &: ?coin=BTC&exchange=Binance,OKX. Filter Genesis API bersifat opsional, jadi tanpa coin endpoint yang sama mengembalikan semua koin. Desimal memakai titik, bukan koma: min_spread=0.5.
Header adalah baris nama: nilai yang dikirim bersama alamat. Nama header tidak peka huruf besar/kecil (RFC 9110, bagian 5.1): X-API-Key dan x-api-key adalah header yang sama, dan x-request-id huruf kecil di output curl sama dengan X-Request-Id. Genesis API hanya menerima key di X-API-Key.
Kode status
Baris pertama respons membawa kode status, dan program Anda menentukan langkah berikutnya berdasarkan kode itu:
| Kode | Artinya | Yang dilakukan |
|---|---|---|
200 | Request dilayani, data ada di body | Baca data dan meta |
304 | Data tidak berubah sejak respons terakhir Anda | Pakai ulang data sebelumnya |
401 | Key tidak ada, tidak valid, dicabut, atau langganan berakhir | Periksa header dan langganan |
403 | Endpoint tidak ada di paket Anda (plan_restricted) | Ganti paket atau hentikan request |
429 | Limit request, unduhan, atau kuota terlampaui | Tunggu Retry-After detik |
503 | Data sedang dibangun ulang (snapshot_not_ready) | Coba lagi setelah Retry-After detik |
Hanya 200 yang memakai kuota Anda: 304 dan error gratis, tetapi tetap dihitung dalam limit request per detik. 304 hanya dikembalikan untuk request dengan header If-None-Match; header itu serta kode 400, 404, 410, dan 500 dibahas di respons dan error Genesis API. Mengapa retry setelah 429 perlu jeda dijelaskan di entri glosarium HTTP 429 Too Many Requests.
Request pertama: /account/usage
/account/usage menampilkan status key Anda: paket, kuota terpakai, dan limit. Endpoint ini tersedia di setiap paket dan tidak memakai panggilan, jadi request pertama Anda ke sini. Simpan key di variabel lingkungan dulu, lalu kirim request:
# tempel key lalu tekan Enter: tidak tampil di layar
read -s GENESIS_API_KEY
export GENESIS_API_KEY
curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
-H "X-API-Key: $GENESIS_API_KEY"
Flag -i mencetak baris status dan header sebelum body. Body respons, contoh ilustratif untuk paket Trial:
{
"success": true,
"data": {
"plan": "trial",
"calls_used": 0,
"calls_limit": 500000,
"rps_limit": 1,
"freshness_sec": 60,
"period_resets_at": 1796463000
},
"meta": {
"count": 1,
"updated_at": 1794730811,
"freshness_sec": 60,
"plan": "trial"
}
}
plan adalah paket Anda, dan calls_used dari calls_limit adalah pemakaian kuota untuk periode 30 hari. Contoh menunjukkan 0 karena belum ada request lain, dan /account/usage sendiri tidak memakai panggilan. rps_limit adalah request per detik, freshness_sec adalah seberapa sering data paket Anda diperbarui, dan period_resets_at adalah waktu kuota direset. Field dijelaskan di bagian dokumentasi Penggunaan.
Di antara header, cari X-Request-Id, ID request yang Anda kirim ke dukungan sebagai ganti key, dan X-RateLimit-Remaining, jumlah request yang tersisa di jendela rate limit saat ini.
Request yang sama dengan Python
Skrip Python 3.10+ dengan library requests membaca key dari variabel lingkungan yang sama:
import os
from datetime import datetime, timezone
import requests
BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"] # KeyError jika belum diatur
r = requests.get(
BASE + "/account/usage",
headers={"X-API-Key": key},
timeout=10, # tanpa timeout, requests bisa menunggu selamanya
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
err = body.get("error") or {}
raise SystemExit(f"{r.status_code} {err.get('code')}")
usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("plan:", usage["plan"])
print("calls:", usage["calls_used"], "of", usage["calls_limit"])
print("quota resets:", resets.strftime("%Y-%m-%d %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))
os.environ["GENESIS_API_KEY"] menghentikan skrip jika variabel belum diatur, lebih baik daripada mengirim request tanpa key dan mendapat 401. r.headers tidak peka huruf besar/kecil, jadi X-Request-Id tetap ditemukan meski server mengirim x-request-id.
period_resets_at adalah waktu unix: jumlah detik sejak 1 Januari 1970, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) mengubahnya menjadi tanggal: 1796463000 adalah 5 Desember 2026, 09:30 UTC.
Request kedua: funding rate BTC
Funding adalah pembayaran berkala antara posisi long dan short pada kontrak futures perpetual, dan exchange menyelesaikannya setiap 8, 4, atau 1 jam. /funding/rates mengembalikan rate di semua exchange, dan parameter coin mempersempitnya ke satu koin. Respons untuk GET /funding/rates?coin=BTC, contoh ilustratif dengan dua exchange dari daftar:
{
"success": true,
"data": [
{
"coin": "BTC",
"exchanges": [
{
"exchange": "Bitget",
"funding_pct": 0.01,
"funding_8h_pct": 0.01,
"next_payout": "00:00",
"interval": "8h",
"price": 96021.5,
"trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
},
{
"exchange": "Hyper",
"funding_pct": 0.0013,
"funding_8h_pct": 0.0104,
"next_payout": null,
"interval": "1h",
"price": 96030.0,
"trade_url": "https://app.hyperliquid.xyz/trade/BTC"
},
…
]
}
],
"meta": {
"count": 1,
"updated_at": 1794675861,
"freshness_sec": 60,
"plan": "trial"
}
}
Cara membaca respons ini:
- envelope:
successbernilaitrue, data ada didata, dan field layanan ada dimeta;meta.countadalah jumlah item didata, yaitu satu koin untukcoin=BTC, dengan arrayexchangesdi dalamnya; - persentase datang sebagai angka biasa:
"funding_pct": 0.01berarti 0,01% per interval, bukan 1%; pada posisi $10.000, satu pembayaran dengan rate ini adalah 10.000 × 0,01 / 100 = $1; funding_8h_pctmenormalkan rate ke 8 jam agar exchange dengan interval berbeda bisa dibandingkan langsung: Hyper menyelesaikan setiap jam, dan 0,0013 × 8 = 0,0104% per 8 jam;next_payoutadalah waktu pembayaran berikutnya dalam UTC berupa string "HH:MM", dannullberarti tidak ada data, bukan nol;meta.updated_atadalah waktu unix saat snapshot dibangun: 1794675861 adalah 14 November 2026, 17:04:21 UTC; pada Trial snapshot diperbarui setiap 60 detik.
Semua field ada di bagian dokumentasi Funding rate. Blok berikutnya melanjutkan skrip: BASE, key, dan import sudah ada.
r = requests.get(
BASE + "/funding/rates",
headers={"X-API-Key": key},
params={"coin": "BTC"}, # requests membentuk ?coin=BTC
timeout=10,
)
r.raise_for_status() # melempar error pada 4xx dan 5xx
body = r.json()
if not body["data"]:
raise SystemExit("coin not in the data: check the ticker")
ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("snapshot from", snap.strftime("%Y-%m-%d %H:%M:%S UTC"))
rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
print(f'{e["exchange"]:<8} {e["funding_pct"]:>7}% '
f'per {e["interval"] or "?"}, '
f'{e["funding_8h_pct"]:>7}% per 8h')
Untuk contoh respons tadi, skrip mencetak:
snapshot from 2026-11-14 17:04:21 UTC
Hyper 0.0013% per 1h, 0.0104% per 8h
Bitget 0.01% per 8h, 0.01% per 8h
Hyper berada di atas Bitget meskipun rate per intervalnya 0,01 / 0,0013 ≈ 7,7 kali lebih rendah. Tanpa normalisasi ke 8 jam, perbandingan ini keliru.
Kesalahan umum pemula
| Kesalahan | Yang dikembalikan server | Cara memperbaiki |
|---|---|---|
Key di URL: ?api_key=… | 401 dan "Missing X-API-Key header." | Kirim key hanya di header X-API-Key |
| Variabel key kosong | 401 dengan teks yang sama: curl membuang header kosong | Periksa panjangnya: echo ${#GENESIS_API_KEY} |
Salah ketik path: /v1/funding/rate atau tanpa /v1 | 404 | Cocokkan path dengan dokumentasi |
Salah ketik nama parameter: coins=BTC | 200 dan semua koin: parameter yang tidak dikenal diabaikan | Periksa meta.count: dengan coin=BTC nilainya 1 |
Koma desimal: min_spread=0,5 | 200 tanpa filter yang diterapkan | Pakai titik: 0.5 |
Pair, bukan ticker: coin=BTCUSDT | 200, data kosong, meta.count 0 | Pakai ticker koin: BTC |
Salah ketik parameter adalah yang paling licik: tidak ada error, tetapi skrip menerima seluruh dataset, bukan satu koin, dan menghabiskan satu panggilan untuk itu. Setelah menambahkan filter baru, bandingkan meta.count dengan yang Anda harapkan.
Coba sendiri
Kirim request tanpa key
curl -i "https://api.genesisarbitrage.com/v1/account/usage"mengembalikan401denganinvalid_keydan "Missing X-API-Key header." di body. Carix-request-iddi antara header.Ulangi dengan key
Atur variabel dengan
read -sdan kirim request dari bagian/account/usage. Anda mendapat200dan paket Anda ada didata.plan.Periksa tanggal reset
Jalankan skrip Python dan bandingkan tanggal reset kuota dengan baris "resets …" di blok "Genesis API" pada profil Anda. Cara mendapatkan key langkah demi langkah ada di mulai cepat Genesis API.
Cari rate tertinggi
Tambahkan blok kedua ke skrip dan cari exchange dengan
funding_8h_pcttertinggi. Normalkanfunding_pct-nya ke 8 jam secara manual: rate × 8 / interval dalam jam.Rusak request dengan sengaja
Ubah
coinmenjadicoinsdan bandingkanmeta.count, lalu hapus hurufsdari/funding/ratesdan lihat kode statusnya.
Endpoint mana yang melayani keputusan soal spread, order book, dan funding menjadi topik pelajaran 3.
Tanya jawab
Bisakah saya memanggil API dari browser?
Hanya alamat yang tidak butuh key: https://api.genesisarbitrage.com/health terbuka di browser dan menampilkan {"ok":true}. Address bar tidak bisa menambahkan header X-API-Key, jadi request dengan key lewat curl, skrip, atau formulir "Coba sekarang" di dokumentasi. Jangan pernah menanam key di kode situs web atau ekstensi: siapa pun yang membuka source halaman akan melihatnya.
Apa beda flag -i dan -v di curl?
-i mencetak baris status dan header respons sebelum body. -v juga menampilkan request itu sendiri: baris berawalan > adalah yang dikirim ke server, dan baris berawalan < adalah yang kembali.
Bagaimana mengubah waktu unix menjadi tanggal tanpa Python?
Di macOS jalankan date -u -r 1796463000; di Linux date -u -d @1796463000. Untuk angka ini, keduanya menampilkan 5 Desember 2026, 09:30 UTC.