Genesis Arbitrage

Genesis Arbitrage · · 12 menit baca

Respons dan error Genesis API: format JSON, ETag dan 304, kode HTTP

Ringkasan

  • Respons Genesis API yang berhasil berupa envelope success, data, dan meta; error berupa success: false plus objek error berisi kode dan pesan.
  • Mengirim ETag sebelumnya di If-None-Match mengembalikan 304 tanpa body jika data tidak berubah, dan 304 tidak memakai kuota.
  • Coba ulang 429 dan 503 setelah jeda Retry-After. Coba ulang tidak memperbaiki 400, 401, 403, 404, atau 410 — ubah request, key, atau paketnya.

Genesis API menjawab setiap request dalam JSON, format data teks yang terdiri dari objek key–value dan array. Respons yang berhasil selalu datang dalam envelope yang sama berisi success, data, dan meta; error datang dengan kode status HTTP dan objek error. Kode status memberi tahu program Anda langkah berikutnya: memakai datanya, menunggu Retry-After detik lalu mencoba ulang, atau memperbaiki request.

Envelope respons: success, data, dan meta

Respons GET /arbitrage/spot-spot yang dipersingkat dari dokumentasi (endpoint ini tersedia di semua paket):

{
  "success": true,
  "data": [
    {
      "coin": "FUEL",
      "exchange_buy": "ByBit",
      "exchange_sell": "Gate",
      "spread_pct": 0.11,
      …
    }
  ],
  "meta": {
    "count": 214,
    "updated_at": 1783802410,
    "freshness_sec": 10,
    "plan": "pro"
  }
}
FieldTipeIsi
successbooleantrue — request berhasil, false — error
dataarray atau objekData endpoint
meta.countintJumlah item di data
meta.updated_atintWaktu Unix saat data dibuat
meta.freshness_secintJeda penyajian untuk paket Anda, dalam detik
meta.planstringPaket Anda, pro pada contoh

Pengecualiannya adalah analitik funding: meta-nya memuat count, updated_at, dan schema_version, tanpa freshness_sec atau plan. Envelope dijelaskan di bagian Format respons dalam dokumentasi, dan field data ada di halaman setiap endpoint.

Tiga konvensi berlaku untuk semua endpoint:

data: array baris atau objek

Bentuk data dijelaskan pada deskripsi setiap endpoint. Untuk GET /arbitrage/spot-spot bentuknya array: satu item per pasangan arbitrase, seperti satu baris tabel di situs. Untuk GET /account/usage bentuknya satu objek berisi status key Anda:

curl "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
  "success": true,
  "data": {
    "plan": "pro",
    "calls_used": 184201,
    "calls_limit": 5000000,
    "rps_limit": 5,
    "freshness_sec": 10,
    "period_resets_at": 1786492800
  },
  "meta": { … }
}

/account/usage tersedia di semua paket dan menampilkan paket, pemakaian kuota, dan freshness_sec Anda: polling lebih sering dari itu tidak ada gunanya. Field dijelaskan di Penggunaan, dan request pertama dibahas langkah demi langkah di panduan cepat. Kode yang bekerja dengan beberapa endpoint sebaiknya memeriksa bentuknya secara eksplisit: isinstance(data, list) di Python.

Filter: opsional, dataset lengkap tanpa filter

Semua parameter filter bersifat opsional: request tanpa filter mengembalikan dataset lengkap endpoint. Tulis beberapa exchange di exchange dengan pemisah koma, dan tentukan coin lewat tickernya di coin:

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d coin=BTC -d exchange=Binance,OKX -d min_spread=0.5 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

Flag -G mengubah parameter -d menjadi query string: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Tulis nama exchange seperti yang muncul di field respons: ByBit, Gate, MEXC. Parameter endpoint arbitrase ada di panduan endpoint arbitrase.

Kuota menghitung respons, bukan baris: request dengan atau tanpa filter dihitung satu panggilan. Filter memperkecil body respons, dan bersama itu trafik serta pemakaian batas unduh. Semua batas dibahas di panduan batas Genesis API.

Kompresi gzip

Genesis API mengirim dataset lengkap dan respons besar dalam bentuk gzip jika klien mengirim header Accept-Encoding: gzip (RFC 9110, bagian 12.5.3). Respons kecil bisa datang tanpa kompresi.

requests di Python mengirim header itu sendiri dan mendekompresi respons. curl tidak meminta kompresi tanpa flag --compressed; dengan flag itu, curl meminta dan mendekompresinya.

Batas unduh menghitung data terkompresi: maksimal 60 MB per 10 detik per key, dan respons di bawah 64 KB tidak dihitung. Jika melewati batas, Anda mendapat 429 download_limited.

ETag dan 304: lewati data yang tidak berubah

ETag adalah header respons berisi tag versi data. Klien mengirim tag itu kembali di header If-None-Match. Jika data tidak berubah, server menjawab 304 Not Modified tanpa body; jika berubah, server memberi 200 biasa dengan data baru dan ETag baru.

# Dataset lengkap, tanpa filter: cetak header respons saja
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# Ulangi dengan ETag dari respons pertama (nilai ilustrasi)
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
  -H 'If-None-Match: W/"5d1f0c9a"'

ETag datang bersama respons untuk request tanpa filter dan berubah di setiap snapshot data baru. Respons untuk request berfilter dibuat khusus untuk request itu dan datang tanpa ETag; di sana filter itu sendiri yang menghemat trafik. ETag paling berguna pada data yang berubah lambat: ringkasan analitik funding mengganti ETag kira-kira setiap 15 menit, dan balasan 304 tidak dihitung ke batas unduh penuhnya.

Respons 304 tidak memakai kuota tetapi dihitung ke batas request per detik. Kirim tag persis seperti yang diterima: menurut RFC 9110, tag adalah string dalam tanda kutip, dan awalan W/ menandai weak tag.

Kode error dan tindakan yang perlu diambil

Saat terjadi error, Genesis API mengembalikan status HTTP yang sesuai dan body dengan success: false:

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Requests per second limit exceeded."
  }
}

error.code adalah kode yang bisa dibaca mesin dan dipakai program Anda untuk bercabang. error.message adalah penjelasan untuk manusia: untuk 400 berisi alasannya, untuk 410 berisi alamat penggantinya.

HTTPerror.codeArtiTindakan
400bad_requestParameter request tidak valid, misalnya volume=700 di /orderbooks/execPerbaiki parameter sesuai message: request yang sama akan gagal lagi
401invalid_keyKey tidak ada, tidak valid, atau dicabut, atau langganan API berakhirPeriksa header X-API-Key dan status langganan di profil Anda
403plan_restrictedEndpoint tidak ada di paket AndaPindah ke paket yang mencakupnya atau hentikan request
404not_foundEndpoint atau resource tidak ditemukan: dataset, bagian, coin, order bookCocokkan path dan parameter dengan dokumentasi
410goneEndpoint sudah dihentikanPindah ke alamat yang tertera di message
429rate_limitedBatas request per detik terlampaui, atau kuota periode habisTunggu Retry-After detik dan perlambat; jika kuota habis, tunggu reset atau tingkatkan paket
429download_limitedVolume unduh terlampaui: 60 MB data terkompresi per 10 detik per keyTunggu Retry-After, kurangi trafik dengan filter, coin, dan If-None-Match
500internal_errorError internalCoba lagi nanti; jika berlanjut, hubungi dukungan dengan X-Request-Id
503snapshot_not_readyData sedang dibangun ulang atau sumbernya sedang restartCoba lagi setelah Retry-After detik

Header Retry-After datang bersama 429 dan 503 dan berisi jumlah detik yang harus ditunggu: biasanya beberapa detik, tetapi jika kuota periode habis, isinya adalah waktu sampai kuota di-reset, yang bisa berhari-hari. Error 4xx dan 5xx tidak memakai kuota tetapi dihitung ke batas request per detik, sehingga percobaan ulang yang terlalu cepat kemungkinan besar mengembalikan error yang sama. Istilah di glosarium: HTTP 429 dan rate limit.

X-Request-Id: yang perlu dikirim ke dukungan

Setiap respons Genesis API, berhasil atau tidak, membawa header X-Request-Id berisi pengenal request. Jika error terus muncul atau datanya tampak salah, kirim ke dukungan:

Jangan kirim key Anda. Jika key sampai masuk ke chat, log, atau kode yang bisa dilihat orang lain, terbitkan ulang di profil Anda: key lama langsung berhenti berfungsi.

Urutan menangani respons

  1. Periksa kode status

    200 — baca data dan meta, dan simpan ETag jika ada. 304 — pakai data dari respons sebelumnya.

  2. Tangani error sementara

    429 dan 503 dengan jeda pendek — tunggu Retry-After detik lalu coba ulang, paling banyak tiga kali berturut-turut. 500 — coba lagi nanti.

  3. Berhenti pada error request

    400, 401, 403, 404, 410, dan 429 dengan jeda berjam-jam atau berhari-hari — perbaiki parameter, key, atau paket, atau tunggu reset kuota.

  4. Periksa usia data

    Bandingkan meta.updated_at dengan waktu sekarang: bot yang bertindak berdasarkan snapshot lama melihat spread yang sudah hilang.

  5. Jadwalkan request berikutnya

    Paling cepat meta.freshness_sec detik kemudian, dengan If-None-Match untuk request tanpa filter.

Fungsi get_json di Python

Fungsi ini menyatukan aturan tersebut: menyimpan ETag terakhir untuk setiap alamat dan mengembalikan data sebelumnya pada 304, menunggu Retry-After pada 429 dan 503 dan mencoba ulang hingga tiga kali, tetapi tidak menunggu jeda lebih dari semenit. Error lain memunculkan exception berisi status, pesan, dan X-Request-Id. Key diambil dari variabel lingkungan GENESIS_API_KEY.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
session = requests.Session()
session.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # (path, params) -> (ETag, data)


class GenesisError(Exception):
    def __init__(self, status, text):
        super().__init__(f"{status} {text}")
        self.status = status


def get_json(path, params=None):
    key = (path, tuple(sorted((params or {}).items())))
    for attempt in range(4):  # satu request plus maksimal 3 percobaan ulang
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = session.get(BASE + path, params=params,
                        headers=hdr, timeout=15)
        if r.status_code == 304:
            return cache[key][1]  # data tidak berubah
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # jangan menunggu berjam-jam atau berhari-hari
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "bukan JSON") from None
        if r.status_code != 200 or not body.get("success"):
            err = body.get("error") or {}
            raise GenesisError(r.status_code, (
                f"{err.get('code')}: {err.get('message')}; "
                f"X-Request-Id {r.headers.get('X-Request-Id')}"))
        if "ETag" in r.headers:  # hanya pada respons tanpa filter
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

Parameter timeout=15 wajib ada: tanpa timeout, requests menunggu respons selamanya.

Polling pada interval paket Anda: dataset lengkap datang dengan ETag, dan baris difilter di kode. Error 4xx menghentikan program; kegagalan server menunggu siklus berikutnya.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # dataset lengkap
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "pasangan dengan spread 1% atau lebih")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: request, key, paket, atau kuota
        print("error server, dicoba lagi di siklus berikutnya:", e)
    time.sleep(pause)

Tanya jawab

Apakah respons 304 memakai kuota?

Tidak. Hanya respons 200 yang memakai kuota. Respons 304 serta error 4xx dan 5xx gratis, tetapi dihitung ke batas request per detik.

Apa yang harus dilakukan setelah 410 ?

Endpoint sudah dihentikan, dan alamat penggantinya ada di error.message. Misalnya, GET /arbitrage/predictions dihentikan pada 15 November 2026, dan message-nya menunjuk ke /predictions/arbitrage. Perbarui path di kode Anda.

Mengapa data kosong padahal tidak ada error?

Filter menghapus semua baris: misalnya min_spread di atas semua spread saat ini. Respons seperti itu memiliki meta.count sama dengan 0, jadi longgarkan filternya.

Mengapa tidak ada ETag di respons?

ETag datang bersama respons untuk request tanpa filter. Respons untuk request dengan coin, exchange, min_spread, atau filter lain dibuat khusus untuk request itu dan datang tanpa tag, sehingga If-None-Match tidak berlaku untuk respons tersebut.