Genesis Arbitrage

Genesis Arbitrage · · 11 menit baca

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: 200 baca datanya, 304 tidak ada yang berubah, 401 dan 403 periksa key dan paket, 429 dan 503 tunggu Retry-After detik.
  • Respons Genesis API berupa envelope berisi success, data, dan meta. Persentase datang sebagai angka biasa (0.01 berarti 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
BagianPada contohArtinya
MetodeGETMembaca data; semua endpoint Genesis API adalah GET
Base URLhttps://api.genesisarbitrage.com/v1Server dan versi API
Path/funding/ratesEndpoint funding rate
Parameter?coin=BTCFilter: hanya BTC
HeaderX-API-KeyKey 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:

KodeArtinyaYang dilakukan
200Request dilayani, data ada di bodyBaca data dan meta
304Data tidak berubah sejak respons terakhir AndaPakai ulang data sebelumnya
401Key tidak ada, tidak valid, dicabut, atau langganan berakhirPeriksa header dan langganan
403Endpoint tidak ada di paket Anda (plan_restricted)Ganti paket atau hentikan request
429Limit request, unduhan, atau kuota terlampauiTunggu Retry-After detik
503Data 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:

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

KesalahanYang dikembalikan serverCara memperbaiki
Key di URL: ?api_key=…401 dan "Missing X-API-Key header."Kirim key hanya di header X-API-Key
Variabel key kosong401 dengan teks yang sama: curl membuang header kosongPeriksa panjangnya: echo ${#GENESIS_API_KEY}
Salah ketik path: /v1/funding/rate atau tanpa /v1404Cocokkan path dengan dokumentasi
Salah ketik nama parameter: coins=BTC200 dan semua koin: parameter yang tidak dikenal diabaikanPeriksa meta.count: dengan coin=BTC nilainya 1
Koma desimal: min_spread=0,5200 tanpa filter yang diterapkanPakai titik: 0.5
Pair, bukan ticker: coin=BTCUSDT200, data kosong, meta.count 0Pakai 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

  1. Kirim request tanpa key

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" mengembalikan 401 dengan invalid_key dan "Missing X-API-Key header." di body. Cari x-request-id di antara header.

  2. Ulangi dengan key

    Atur variabel dengan read -s dan kirim request dari bagian /account/usage. Anda mendapat 200 dan paket Anda ada di data.plan.

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

  4. Cari rate tertinggi

    Tambahkan blok kedua ke skrip dan cari exchange dengan funding_8h_pct tertinggi. Normalkan funding_pct-nya ke 8 jam secara manual: rate × 8 / interval dalam jam.

  5. Rusak request dengan sengaja

    Ubah coin menjadi coins dan bandingkan meta.count, lalu hapus huruf s dari /funding/rates dan 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.