Genesis Arbitrage

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

Лимиты Genesis API: квота вызовов, запросы в секунду, свежесть данных и ошибка 429

Коротко

  • Тариф задаёт квоту вызовов за 30 дней (от 500 тыс. на Trial до 10 млн на Max), лимит запросов в секунду (от 1 до 15) и свежесть данных (от 60 до 5 секунд).
  • Квоту тратит только ответ 200. Ответы 304 и ошибки бесплатны, но занимают место в лимите запросов в секунду; сверх лимитов сервер отвечает 429 и денег не списывает.
  • Опрос чаще meta.freshness_sec новых данных не даёт: тариф получает свежий снимок раз в этот интервал, а If-None-Match превращает лишние опросы в бесплатные ответы 304.

Лимиты Genesis API — четыре ограничения на ключ: квота вызовов за 30-дневный период, лимит запросов в секунду, свежесть данных и объём скачивания. Первые три задаёт тариф, объём скачивания одинаков для всех: 60 МБ сжатых данных за 10 секунд. Сверх любого лимита сервер возвращает ошибку 429 и ничего не списывает.

Лимиты по тарифам

ТарифВызовов за 30 днейЗапросов в секундуСвежесть
Trial, $20 в месяц500 000160 с
Start, $50 в месяц2 000 000230 с
Pro, $100 в месяц5 000 000510 с
Max, $200 в месяц10 000 000155 с

Свежесть данных — шаг, с которым тариф получает новый снимок: на Trial раз в 60 секунд, на Max раз в 5. В ответах она приходит в поле meta.freshness_sec. Оплата на 3 месяца даёт скидку 10 %, на 6 месяцев — 20 %. Сравнение тарифов — на странице «Тарифы Genesis API», правила — в разделе документации «Тарифы и лимиты».

Что списывает квоту

Вызов — это ответ 200. Ответы 304 (данные не изменились) и ошибки 4xx и 5xx квоту не тратят, но учитываются в лимите запросов в секунду. Запрос к /account/usage вызов не списывает.

Квота считается за 30-дневный период, а не за календарный месяц. Время обнуления показывают заголовок X-Quota-Reset, поле period_resets_at и строка «сброс …» в профиле. Когда квота кончилась, сервер отвечает 429 rate_limited, а Retry-After равен числу секунд до сброса: это могут быть дни.

Заголовки лимитов

Ответ эндпоинта с данными несёт состояние лимитов (значения условные):

ЗаголовокПримерЧто показывает
X-RateLimit-Limit5Лимит запросов в секунду на тарифе
X-RateLimit-Remaining4Сколько запросов осталось в текущем окне
X-RateLimit-Reset1785200001Unix-время сброса окна
X-Quota-Limit5000000Квота вызовов на 30-дневный период
X-Quota-Remaining4815799Сколько вызовов осталось в периоде
X-Quota-Reset1786492800Unix-время обнуления квоты
Retry-After1Через сколько секунд повторить, при 429 и 503

Окно лимита запросов — одна секунда, в обычном ответе X-RateLimit-Reset указывает на начало следующей. Остаток квоты в примере: 5 000 000 − 184 201 = 4 815 799 вызовов, те же числа вернёт /account/usage.

Эндпоинт /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": { … }
}
ПолеТипЧто значит
planstringТариф: trial, start, pro или max
calls_usedintВызовов израсходовано в текущем периоде
calls_limitintКвота вызовов на период
rps_limitintЛимит запросов в секунду
freshness_secintЗадержка данных, секунды
period_resets_atintUnix-время обнуления квоты

Эндпоинт доступен на всех тарифах, описание — в разделе «Использование». Его удобно вызывать при старте бота: проверить тариф и остаток до начала опроса.

Ошибки 429: rate_limited и download_limited

ОтветКогда приходитЧто делать
429 rate_limitedЗапросов в секунду больше, чем позволяет тарифЖдать Retry-After и разносить запросы
429 rate_limitedКончилась квота периодаЖдать сброса или сменить тариф
429 rate_limitedПолная выгрузка аналитики фандинга чаще разрешённогоБрать срез с coin или слать If-None-Match
429 download_limitedБольше 60 МБ сжатых данных за 10 секундЖдать Retry-After, сужать запрос фильтрами

Код 429 Too Many Requests описан в RFC 6585, где Retry-After необязателен. Genesis API присылает его в каждом 429, всегда в секундах.

Ответы меньше 64 КБ в объём скачивания не засчитываются, и опрос всех наборов с частотой тарифа укладывается в лимит с запасом. Полные выгрузки аналитики фандинга без coin ограничены отдельно: /funding/analytics/summary и /funding/analytics/recent — раз в 60 секунд, /funding/analytics/daily — раз в 300 секунд на ключ. Запросы с coin и ответы 304 не ограничены, подробности — в разделе «Аналитика фандинга».

Доступ по тарифам и 403 plan_restricted

ТарифЧто открыто
TrialCEX-арбитраж (Спот – Спот, Спот – Фьючерсы, Фьючерсы – Фьючерсы), ставки и спред фандинга, Fair – Last, CEX Пампы – Дампы, открытый интерес, AI-сигналы, поиск монет, /account/usage
StartВсё из Trial, а также акции /arbitrage/stocks, ончейн-разделы /onchain/{section}, арбитраж прогнозов в режимах exact и dutch, состояние площадок
Pro и MaxВсе эндпоинты: DEX – Спот, DEX – Фьючерсы, Кроссчейн, DEX Дампы, стаканы, аналитика фандинга, аналитика рынков предсказаний, умные деньги, сделки, трейдеры, режимы llm и sport, свапы DEX, аналитика и монета OnChain

Эндпоинт вне тарифа отвечает 403, как и запрос mode=sport к /predictions/arbitrage на Start:

{
  "success": false,
  "error": {
    "code": "plan_restricted",
    "message": "This endpoint is not included in your plan."
  }
}

Квоту 403 не тратит. Повторять такой запрос бесполезно: доступ откроет только тариф выше.

Как подобрать тариф под нагрузку

Условный пример: бот опрашивает три эндпоинта — /arbitrage/spot-spot, /funding/spread и /market/open-interest — раз в 10 секунд круглосуточно.

Тот же бот при опросе с частотой свежести каждого тарифа:

Свежесть и опросВызовов за 30 днейТарифДоля квоты
Раз в 60 с129 600Trial26 %
Раз в 30 с259 200Start13 %
Раз в 10 с777 600Pro16 %
Раз в 5 с1 555 200Max16 %

Опрос раз в 10 секунд имеет смысл с Pro: 777 600 / 5 000 000 = 15,552 % квоты, а лимита 5 запросов в секунду хватит и на одновременную отправку. Если боту достаточно данных 30-секундной давности, Start с опросом раз в 30 секунд обойдётся в 259 200 / 2 000 000 = 12,96 % квоты.

Опрос без лишних вызовов: ETag и Retry-After

Тариф получает новый снимок раз в meta.freshness_sec секунд, и опрос чаще вернёт тот же снимок с тем же meta.updated_at. Без заголовка If-None-Match такой ответ — 200 и списанный вызов. С ним сервер ответит 304 без тела: квота не тронута, место в секундном лимите занято.

ETag приходит не во всех ответах. Его отдают полные наборы — запросы без фильтров, как /funding/spread в примере ниже. У ответа с фильтрами (coin, min_spread и другими) ETag нет, и каждый опрос стоит вызова: фильтры экономят трафик, ETag — квоту. Повторы и сжатие разобраны в статье о том, как опрашивать API экономно, и в инструкции об ответах и ошибках.

import os
import time

import requests

URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"]
etag, pause = None, 30

while True:
    headers = {"X-API-Key": KEY}
    if etag:
        headers["If-None-Match"] = etag
    r = requests.get(URL, headers=headers, timeout=15)
    if r.status_code in (429, 500, 503):
        wait = int(r.headers.get("Retry-After", "5"))
        if wait > 600:  # кончилась квота — останавливаемся
            raise SystemExit(f"Квота исчерпана, сброс через {wait} с")
        time.sleep(wait)
        continue
    r.raise_for_status()  # 401 и 403 повтором не исправить
    left = r.headers.get("X-Quota-Remaining")  # может не прийти
    if left is not None and int(left) < 10_000:
        print("Квота на исходе:", left)
    if r.status_code == 200:  # при 304 данные прежние
        etag = r.headers.get("ETag")
        body = r.json()
        pause = body["meta"].get("freshness_sec", pause)
        print(body["meta"]["count"], "монет в ответе")
    time.sleep(pause)

Смена и продление тарифа

Как получить и хранить ключ, разобрано в инструкции об API-ключе Genesis API.

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

Что будет, если квота кончится раньше срока?

Сервер ответит 429 rate_limited с Retry-After до сброса квоты, деньги не списываются. Дождитесь нового периода или оплатите тариф выше: он начнёт действовать сразу, с новой квотой.

Тратят ли лимит ответы 304 и ошибки?

Квоту — нет, её тратит только 200. Лимит запросов в секунду — да: ответы 304 и ошибки занимают место в секундном окне.

Как узнать остаток квоты, не тратя вызов?

Прочитайте X-Quota-Remaining в ответе с данными или вызовите /account/usage: этот запрос вызов не списывает. Расход показывает и строка «Использовано вызовов» в профиле.

Можно ли обойти лимит несколькими ключами?

Нет. На аккаунт выдаётся один ключ, лимиты считаются на ключ, и смена IP-адреса их не меняет. Несколько аккаунтов ради обхода лимитов — нарушение правил; нужно больше — переходите на тариф выше.