Genesis Arbitrage

Genesis Arbitrage · · 11 мин чтения

Ответы и ошибки Genesis API: формат JSON, ETag и 304, коды HTTP

Коротко

  • Успешный ответ Genesis API — конверт из success, data и meta, ошибка — success: false и объект error с кодом и текстом.
  • Прошлый ETag в заголовке If-None-Match даёт ответ 304 без тела, если данные не изменились, — квота на него не тратится.
  • 429 и 503 повторяют после паузы из Retry-After. Ошибки 400, 401, 403, 404 и 410 повтор не исправит — меняйте запрос, ключ или тариф.

Genesis API отвечает на любой запрос в формате JSON — текстовом формате данных из объектов «ключ — значение» и массивов. Успешный ответ всегда приходит в одном конверте из success, data и meta, ошибка — с кодом HTTP и объектом error. По коду ответа программа решает, что делать дальше: взять данные, подождать Retry-After секунд и повторить или исправить запрос.

Конверт ответа: success, data и meta

Сокращённый ответ GET /arbitrage/spot-spot из документации — эндпоинт есть на всех тарифах:

{
  "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"
  }
}
ПолеТипЧто содержит
successbooleantrue — запрос выполнен, false — ошибка
dataмассив или объектДанные эндпоинта
meta.countintСколько элементов в data
meta.updated_atintUnix-время, когда собраны данные
meta.freshness_secintЗадержка отдачи для вашего тарифа, секунды
meta.planstringВаш тариф, в примере pro

Исключение — аналитика фандинга: в её meta приходят count, updated_at и schema_version, без freshness_sec и plan. Описание конверта — в разделе «Формат ответа» документации, поля data — на странице каждого эндпоинта.

Во всех эндпоинтах действуют три соглашения:

data: массив строк или объект

Форма data указана в описании эндпоинта. У GET /arbitrage/spot-spot это массив: один элемент — одна связка, как строка таблицы на сайте. У GET /account/usage — один объект с состоянием ключа:

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 есть на всех тарифах: в нём тариф, расход квоты и freshness_sec — интервал, чаще которого опрашивать данные нет смысла. Поля — в разделе «Использование», первый запрос — в быстром старте. Код, который работает с разными эндпоинтами, проверяет форму явно: isinstance(data, list) в Python.

Фильтры: без них — полный набор

Все параметры фильтров необязательны: запрос без них возвращает полный набор данных эндпоинта. Несколько бирж в exchange перечисляют через запятую, монету задают тикером в 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"

Флаг -G собирает параметры -d в строку запроса: ?coin=BTC&exchange=Binance,OKX&min_spread=0.5. Названия бирж пишите так же, как они приходят в полях ответа: ByBit, Gate, MEXC. Параметры эндпоинтов арбитража — в инструкции «Эндпоинты арбитража».

Квота считает ответы, а не строки: запрос с фильтрами и без них — один вызов. Фильтр уменьшает тело ответа, а с ним трафик и расход лимита скачивания. Все лимиты — в инструкции «Лимиты Genesis API».

Сжатие gzip

Полные наборы и крупные ответы Genesis API отдаёт сжатыми gzip, если клиент передал заголовок Accept-Encoding: gzip (RFC 9110, раздел 12.5.3). Небольшой ответ может прийти без сжатия.

requests в Python сам отправляет этот заголовок и распаковывает ответ. curl без флага --compressed сжатия не запрашивает, с флагом — запрашивает и распаковывает.

Лимит скачивания считает сжатые данные: не больше 60 МБ за 10 секунд на ключ, ответы меньше 64 КБ в него не входят. Сверх лимита приходит 429 download_limited.

ETag и 304: не скачивать одно и то же

ETag — заголовок ответа с меткой версии данных. Клиент отправляет эту метку обратно в заголовке If-None-Match. Если данные не изменились, сервер отвечает 304 Not Modified без тела, если изменились — обычным 200 с новыми данными и новым ETag.

# Полный набор без фильтров: печатаем только заголовки ответа
curl -sS -D - -o /dev/null --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

# Повтор с ETag из первого ответа (значение — условный пример)
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 приходит с ответом без фильтров и меняется с каждым новым снимком данных. Ответ на запрос с фильтром собирается под запрос и приходит без ETag: трафик в нём экономит сам фильтр. Сильнее всего ETag помогает на медленных данных: у сводки аналитики фандинга он меняется примерно раз в 15 минут, а ответы 304 под ограничение полной выгрузки не попадают.

Ответ 304 квоту не расходует, но учитывается в лимите запросов в секунду. Метку передавайте ровно такой, какой она пришла: по RFC 9110 это строка в кавычках, а префикс W/ отмечает слабую метку.

Коды ошибок и что делать

При ошибке Genesis API возвращает подходящий код HTTP и тело с success: false:

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

error.code — машинный код, по нему программа выбирает реакцию. error.message — пояснение для человека: у 400 в нём причина, у 410 — адрес замены.

HTTPerror.codeЧто значитЧто делать
400bad_requestНеверные параметры запроса, например volume=700 в /orderbooks/execИсправить параметры по message: тот же запрос снова не пройдёт
401invalid_keyКлюча нет, он неверен, отозван или подписка на API истеклаПроверить заголовок X-API-Key и статус подписки в профиле
403plan_restrictedЭндпоинт не входит в тарифПерейти на тариф с этим эндпоинтом или убрать запрос
404not_foundЭндпоинт или ресурс не найден: набор, секция, монета, стаканСверить путь и параметры с документацией
410goneЭндпоинт выведен из работыПерейти на адрес из message
429rate_limitedПревышен лимит запросов в секунду или исчерпана квота периодаПодождать Retry-After секунд и снизить частоту; при исчерпанной квоте — дождаться сброса или сменить тариф
429download_limitedПревышен объём скачивания: 60 МБ сжатых данных за 10 с на ключПодождать Retry-After, сократить трафик фильтрами, coin и If-None-Match
500internal_errorВнутренняя ошибкаПовторить позже; если не проходит — написать в поддержку с X-Request-Id
503snapshot_not_readyДанные пересобираются или источник перезапускаетсяПовторить через Retry-After секунд

Заголовок Retry-After приходит с 429 и 503 и содержит число секунд до повтора: обычно единицы секунд, а при исчерпанной квоте периода — время до её сброса, которое может измеряться днями. Ошибки 4xx и 5xx квоту не расходуют, но считаются в лимите запросов в секунду, поэтому повтор раньше срока, скорее всего, вернёт ту же ошибку. Термины — в глоссарии: ошибка 429 и лимит запросов.

X-Request-Id: что прислать в поддержку

Каждый ответ Genesis API, успешный и с ошибкой, содержит заголовок X-Request-Id — идентификатор запроса. Если ошибка повторяется или данные выглядят неверно, пришлите в поддержку:

Ключ присылать не нужно. Если он попал в переписку, логи или код, который видят другие, перевыпустите его в профиле: старый ключ перестанет работать сразу.

Порядок обработки ответа

  1. Проверьте код ответа

    200 — читайте data и meta, сохраните ETag, если он пришёл. 304 — берите данные прошлого ответа.

  2. Обработайте временные ошибки

    429 и 503 с короткой паузой — подождите Retry-After секунд и повторите, не больше трёх раз подряд. 500 — повторите позже.

  3. Остановитесь на ошибках запроса

    400, 401, 403, 404, 410 и 429 с паузой в часы или дни — исправьте параметры, ключ или тариф либо дождитесь сброса квоты.

  4. Проверьте возраст данных

    Сравните meta.updated_at с текущим временем: по старому снимку бот видит спреды, которых уже нет.

  5. Запланируйте следующий запрос

    Не раньше чем через meta.freshness_sec секунд, для запроса без фильтров — с If-None-Match.

Функция get_json на Python

Функция собирает эти правила: хранит ETag последнего ответа для каждого адреса и при 304 возвращает прошлые данные, при 429 и 503 ждёт Retry-After и повторяет до трёх раз, а паузу длиннее минуты не ждёт. Остальные ошибки поднимают исключение с кодом, текстом и X-Request-Id. Ключ — из переменной окружения 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 = {}  # (путь, параметры) -> (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):  # запрос и не больше 3 повторов
        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]  # данные не изменились
        wait = float(r.headers.get("Retry-After", 1))
        if r.status_code in (429, 503) and attempt < 3 and wait <= 60:
            time.sleep(wait)  # паузу в часы и дни не ждём
            continue
        try:
            body = r.json()
        except ValueError:
            raise GenesisError(r.status_code, "ответ не 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:  # есть у ответа без фильтров
            cache[key] = (r.headers["ETag"], body["data"])
        return body["data"]

Параметр timeout=15 нужен всегда: без таймаута requests ждёт ответа бесконечно.

Опрос с интервалом тарифа: полный набор приходит с ETag, отбор строк идёт в коде. Ошибки 4xx останавливают программу, сбой сервера ждёт следующего цикла.

pause = get_json("/account/usage")["freshness_sec"]
while True:
    try:
        rows = get_json("/arbitrage/spot-spot")  # полный набор
        top = [x for x in rows if x["spread_pct"] >= 1]
        print(len(top), "связок со спредом от 1 %")
    except GenesisError as e:
        if e.status < 500:
            raise  # 4xx: запрос, ключ, тариф или квота
        print("сбой на сервере, повтор в следующем цикле:", e)
    time.sleep(pause)

Вопросы и ответы

Расходует ли ответ 304 квоту?

Нет. Квоту расходуют только ответы 200. Ответы 304 и ошибки 4xx и 5xx бесплатны, но учитываются в лимите запросов в секунду.

Что делать, если пришёл 410 ?

Эндпоинт выведен из работы, адрес замены указан в error.message. Например, GET /arbitrage/predictions выведен 15 ноября 2026 года, и его message отсылает к /predictions/arbitrage. Поменяйте путь в коде.

Почему data пустой, хотя ошибки нет?

Фильтры отсекли все строки: например, min_spread выше любого текущего спреда. В таком ответе meta.count равен 0 — ослабьте фильтр.

Почему в ответе нет ETag?

ETag приходит с ответом без фильтров. Ответ на запрос с coin, exchange, min_spread или другим фильтром собирается под запрос и приходит без метки, поэтому If-None-Match к нему не применяется.