Лимиты 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 000 | 1 | 60 с |
| Start, $50 в месяц | 2 000 000 | 2 | 30 с |
| Pro, $100 в месяц | 5 000 000 | 5 | 10 с |
| Max, $200 в месяц | 10 000 000 | 15 | 5 с |
Свежесть данных — шаг, с которым тариф получает новый снимок: на 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-Limit | 5 | Лимит запросов в секунду на тарифе |
X-RateLimit-Remaining | 4 | Сколько запросов осталось в текущем окне |
X-RateLimit-Reset | 1785200001 | Unix-время сброса окна |
X-Quota-Limit | 5000000 | Квота вызовов на 30-дневный период |
X-Quota-Remaining | 4815799 | Сколько вызовов осталось в периоде |
X-Quota-Reset | 1786492800 | Unix-время обнуления квоты |
Retry-After | 1 | Через сколько секунд повторить, при 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": { … }
}
| Поле | Тип | Что значит |
|---|---|---|
plan | string | Тариф: trial, start, pro или max |
calls_used | int | Вызовов израсходовано в текущем периоде |
calls_limit | int | Квота вызовов на период |
rps_limit | int | Лимит запросов в секунду |
freshness_sec | int | Задержка данных, секунды |
period_resets_at | int | Unix-время обнуления квоты |
Эндпоинт доступен на всех тарифах, описание — в разделе «Использование». Его удобно вызывать при старте бота: проверить тариф и остаток до начала опроса.
Ошибки 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
| Тариф | Что открыто |
|---|---|
| Trial | CEX-арбитраж (Спот – Спот, Спот – Фьючерсы, Фьючерсы – Фьючерсы), ставки и спред фандинга, 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 секунд круглосуточно.
- Запросы в секунду: в среднем 3 / 10 = 0,3. Если отправлять все три одновременно, они попадут в одну секунду, и на Trial и Start лишние получат
429. - Вызовы в сутки: 86 400 / 10 = 8 640 опросов, 8 640 × 3 = 25 920 вызовов.
- Вызовы за 30 дней: 25 920 × 30 = 777 600. Это больше квоты Trial в 500 000, у Start — 777 600 / 2 000 000 = 38,88 % квоты.
- Свежесть: на Start снимок обновляется раз в 30 секунд, то есть 86 400 / 30 = 2 880 раз в сутки. Новые данные принесут 2 880 × 3 × 30 = 259 200 вызовов, остальные 777 600 − 259 200 = 518 400 вернут то же самое.
Тот же бот при опросе с частотой свежести каждого тарифа:
| Свежесть и опрос | Вызовов за 30 дней | Тариф | Доля квоты |
|---|---|---|---|
| Раз в 60 с | 129 600 | Trial | 26 % |
| Раз в 30 с | 259 200 | Start | 13 % |
| Раз в 10 с | 777 600 | Pro | 16 % |
| Раз в 5 с | 1 555 200 | Max | 16 % |
Опрос раз в 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)
Смена и продление тарифа
- Новый тариф начинает действовать сразу после оплаты: новые лимиты и свежесть, квота с нуля, остаток прежнего тарифа сгорает. Перед оплатой сайт предупредит об этом.
- Продление того же тарифа добавляет дни к сроку и квоту не обнуляет: текущий 30-дневный период идёт дальше.
- Ключ при смене и продлении тарифа остаётся прежним: менять его в программах не нужно.
- Скидка за срок считается от месячной цены: Pro на 6 месяцев — $100 × 0,8 × 6 = $480 вместо $600, на 3 месяца — $100 × 0,9 × 3 = $270.
Как получить и хранить ключ, разобрано в инструкции об API-ключе Genesis API.
Вопросы и ответы
Что будет, если квота кончится раньше срока?
Сервер ответит 429 rate_limited с Retry-After до сброса квоты, деньги не списываются. Дождитесь нового периода или оплатите тариф выше: он начнёт действовать сразу, с новой квотой.
Тратят ли лимит ответы 304 и ошибки?
Квоту — нет, её тратит только 200. Лимит запросов в секунду — да: ответы 304 и ошибки занимают место в секундном окне.
Как узнать остаток квоты, не тратя вызов?
Прочитайте X-Quota-Remaining в ответе с данными или вызовите /account/usage: этот запрос вызов не списывает. Расход показывает и строка «Использовано вызовов» в профиле.
Можно ли обойти лимит несколькими ключами?
Нет. На аккаунт выдаётся один ключ, лимиты считаются на ключ, и смена IP-адреса их не меняет. Несколько аккаунтов ради обхода лимитов — нарушение правил; нужно больше — переходите на тариф выше.