Genesis Arbitrage

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

Как опрашивать API крипторынка без превышения лимитов: ETag, gzip, фильтры и повторы после 429

Коротко

  • У API обычно три лимита: запросы в секунду, квота вызовов за период и объём скачивания. У Genesis API это от 1 до 15 запросов в секунду, от 500 тыс. до 10 млн вызовов за 30 дней и 60 МБ сжатых данных за 10 секунд на ключ.
  • Интервал опроса задаёт meta.freshness_sec: чаще приходит тот же снимок. If-None-Match превращает повтор в бесплатный ответ 304, gzip и фильтры сокращают трафик, а один полный набор вместо запросов по каждой монете экономит вызовы.
  • Ответы 429 и 503 повторяют через Retry-After секунд, а без этого заголовка — с экспоненциальной паузой и случайной добавкой. Ограничитель token bucket держит темп ниже лимита, а заголовки X-RateLimit-* и X-Quota-* показывают запас.

Чтобы опрашивать API без ошибки 429, запросы подстраивают сразу под три лимита: число запросов в секунду, квоту вызовов за период и объём скачанных данных. Работают пять приёмов: интервал не чаще обновления данных, условные запросы с ETag, сжатие gzip, фильтры вместо лишних выгрузок и повтор после паузы, которую назвал сервер. Числа и код ниже — для Genesis API, REST API с данными крипторынка, но приёмы подходят к любому HTTP API, включая API бирж.

Три лимита API: запросы в секунду, квота и объём

Лимит запросов в секунду ловит всплески — пачку запросов, отправленных разом. Квота ловит средний темп за весь период, а лимит объёма — тяжёлые выгрузки, даже когда запросов немного.

ЛимитЧто считаетGenesis APIСверх лимита
Запросы в секундуВсе запросы, включая 304 и ошибки1 на Trial, 2 на Start, 5 на Pro, 15 на Max429 rate_limited, Retry-After: 1
Квота за периодТолько ответы 200500 тыс., 2 млн, 5 млн, 10 млн вызовов за 30 дней429 rate_limited, Retry-After до сброса квоты
Объём скачиванияСжатые ответы от 64 КБ60 МБ за 10 секунд на ключ, на всех тарифах429 download_limited до конца окна

Запросы сверх лимитов Genesis API не тарифицируются: 429 квоту не тратит и денег не списывает. Все правила — в инструкции «Лимиты Genesis API» и в разделе документации «Тарифы и лимиты».

У API бирж схема бывает сложнее: Binance считает вес запросов по IP-адресу, и у каждого эндпоинта своя цена. Кто продолжает слать запросы после 429, получает автоматическую блокировку IP с кодом 418, а у повторных нарушителей срок растёт (документация Binance).

Интервал опроса: сколько вызовов уйдёт за 30 дней

Опрос чаще, чем обновляются данные, приносит только повторы. Ядро Genesis Arbitrage обновляет данные каждую секунду, а отдача API для тарифа обновляется раз в meta.freshness_sec секунд: 60 на Trial, 30 на Start, 10 на Pro и 5 на Max. Это свежесть данных тарифа и нижняя граница интервала опроса. WebSocket и вебхуков у Genesis API нет, данные забирают опросом по REST.

Условный пример: бот на тарифе Start — $50 в месяц, 2 млн вызовов, 2 запроса в секунду, свежесть 30 с — опрашивает четыре эндпоинта: /arbitrage/spot-spot, /arbitrage/spot-futures, /funding/spread и /market/open-interest.

ИнтервалВызовов за 30 днейДоля квоты StartПовторов одного снимка
60 с172 8008,64 %нет
30 с345 60017,28 %нет
10 с1 036 80051,84 %2 из 3
5 с2 073 600103,68 %5 из 6

При опросе раз в 5 секунд квота кончится на 29-й день: 4 × 86 400 / 5 = 69 120 вызовов в сутки, 2 000 000 / 69 120 ≈ 28,9 дня. Из шести ответов подряд пять повторяют один снимок с тем же meta.updated_at, и без If-None-Match каждый из них списывает вызов.

Средний темп при опросе раз в 30 секунд — 4 / 30 ≈ 0,13 запроса в секунду. Но четыре запроса, отправленные разом, попадут в одну секунду, и два из них получат 429. Если нужны данные свежее 30 секунд, решает тариф с меньшим freshness_sec: на Pro снимок обновляется раз в 10 секунд, на Max — раз в 5.

Условные запросы: ETag, If-None-Match и 304

ETag — метка версии ответа. Клиент сохраняет её и в следующем запросе к тому же адресу отправляет в заголовке If-None-Match; если версия не изменилась, сервер отвечает 304 Not Modified. По RFC 9110 ответ 304 заканчивается заголовками и тела не несёт, поэтому данные берут из своей копии.

В Genesis API ответ 304 не тратит квоту, но занимает место в лимите запросов в секунду. Метку получают только полные наборы без фильтров. Ответы на запросы с coin, exchange, min_spread и другими фильтрами, а также /orderbooks/book и /orderbooks/coin/{coin} собираются под запрос и приходят без ETag.

ETag экономит квоту там, где данные меняются реже, чем вы спрашиваете. Метка спредов меняется с каждым снимком, и при опросе раз в freshness_sec почти каждый ответ будет 200.

Условный пример на Pro: дневные суммы аналитики фандинга /funding/analytics/daily пересобираются раз в час, после накопления годовой истории полная секция весит около 12 МБ gzip, а без coin её отдают не чаще раза в 300 секунд. Опрос раз в 300 секунд — это 2 592 000 / 300 = 8 640 запросов за 30 дней. С If-None-Match секция скачается 30 × 24 = 720 раз, остальные 8 640 − 720 = 7 920 ответов придут как 304.

Итог — 720 вызовов вместо 8 640 и около 8,6 ГБ трафика вместо 104 ГБ. Ответы 304 под ограничение полной выгрузки не попадают.

Фильтры и coin: где экономятся вызовы, а где трафик

Фильтр уменьшает ответ, но не число вызовов: квота считает ответы, и запрос с coin=BTC стоит столько же, сколько полный набор. Поэтому выбор зависит от того, что кончается раньше — вызовы или трафик.

Условный пример на Start: бот следит за фандингом пяти монет. Пять запросов к /funding/rates с coin раз в 30 секунд — 5 × 86 400 = 432 000 вызовов за 30 дней и пять запросов за цикл при лимите 2 в секунду. Один полный /funding/rates с отбором монет в коде — 86 400 вызовов, в пять раз меньше, и к нему подходит ETag.

ЗадачаКак запрашиватьЧто экономится
Несколько монет одного набораПолный набор с If-None-Match, отбор в кодеВызовы: один запрос вместо нескольких
Одна монета тяжёлого разделаПараметр coinТрафик и лимит объёма
Строки выше порогаmin_spread, min_volumeТрафик, но каждый опрос — вызов
Медленный раздел целикомПолный набор с If-None-MatchВызовы и трафик

Тяжелее всего аналитика фандинга: полная сводка весит около 600 КБ gzip, выплаты за 7 дней — около 1 МБ, а дневные суммы доходят до 12 МБ («Эндпоинты фандинга»). Срез одной монеты с coin не попадает под лимит полной выгрузки: раз в 60 секунд для сводки и выплат и раз в 300 для дневных сумм.

Сжатие gzip

Сжатие уменьшает число байт, которые идут по сети. Клиент просит его заголовком Accept-Encoding: gzip, сервер отвечает сжатым телом и заголовком Content-Encoding: gzip. Библиотека requests в Python сама добавляет gzip в Accept-Encoding и распаковывает ответ, curl делает то же с флагом --compressed.

В Genesis API сжатие связано с лимитом: объём скачивания считается в сжатых данных, 60 МБ за 10 секунд на ключ, а ответы меньше 64 КБ в него не входят. Полные наборы и крупные ответы приходят в gzip, если клиент его запросил («Ответы и ошибки Genesis API»). Сколько байт тела пришло по сети, показывает переменная size_download в curl:

# байты тела по сети со сжатием и без; каждый запрос — вызов
URL="https://api.genesisarbitrage.com/v1/funding/rates"
curl -s -o /dev/null --compressed -w "gzip: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"
curl -s -o /dev/null -w "без сжатия: %{size_download}\n" \
  -H "X-API-Key: $GENESIS_API_KEY" "$URL"

Повтор после 429: Retry-After и пауза со случайной добавкой

Ошибка 429 Too Many Requests — ответ сервера на превышение лимита. По RFC 6585 такой ответ может нести заголовок Retry-After, а по RFC 9110 его значение — число секунд или дата. Genesis API присылает Retry-After с каждым 429 и 503, в секундах.

Повтор без паузы почти всегда возвращает ту же ошибку и снова занимает место в секундном окне. Есть Retry-After — ждите столько, сколько просит сервер. Нет — ждите экспоненциально дольше после каждой неудачи: до 1, 2, 4, 8 секунд.

Случайная добавка (jitter) нужна, когда клиентов много: без неё все, кто получил ошибку в одну секунду, повторят запрос тоже в одну секунду. Функция backoff берёт случайную паузу от нуля до текущей ступени, а к Retry-After добавляет долю секунды. fetch повторяет 429, 500 и 503, а при паузе длиннее 10 минут останавливается: так выглядит исчерпанная квота.

import os
import random
import time

import requests

BASE = "https://api.genesisarbitrage.com/v1"
api = requests.Session()  # держит TCP-соединение, gzip включён
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}  # путь -> (ETag, data): только полные наборы


def backoff(attempt, retry_after=None, cap=60.0):
    """Пауза перед повтором, секунды."""
    if retry_after and retry_after.isdigit():
        return int(retry_after) + random.uniform(0, 1)
    return random.uniform(0, min(cap, 2 ** attempt))


def fetch(path, params=None, tries=5):
    """GET к API: возвращает (data, заголовки ответа)."""
    for attempt in range(tries):
        tag = None if params else cache.get(path, (None,))[0]
        try:
            r = api.get(BASE + path, params=params, timeout=15,
                        headers={"If-None-Match": tag} if tag else {})
        except (requests.ConnectionError, requests.Timeout):
            time.sleep(backoff(attempt))
            continue
        if r.status_code == 304:  # снимок прежний, квота цела
            return cache[path][1], r.headers
        if r.status_code in (429, 500, 503):
            wait = backoff(attempt, r.headers.get("Retry-After"))
            if wait > 600:  # так выглядит исчерпанная квота
                raise RuntimeError(f"квота: сброс через {wait:.0f} с")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403, 404, 410: не повторять
        data = r.json()["data"]
        if not params and "ETag" in r.headers:
            cache[path] = (r.headers["ETag"], data)
        return data, r.headers
    raise RuntimeError(f"{path}: нет ответа за {tries} попыток")
ОтветПаузаПовторять
429 rate_limited за секундуRetry-After: 1 и доля секундыДа
429 rate_limited за квотуДо сброса квоты, бывает в дняхНет
429 download_limitedRetry-After до конца окнаДа, сузив запросы
503 snapshot_not_readyRetry-AfterДа
500, таймаут, обрыв связиЭкспоненциальная со случайной добавкойДа
400, 401, 403, 404, 410—Нет, исправить запрос

Исчерпанную квоту от секундного лимита отличают по Retry-After: секунда против часов и дней до сброса, а в теле ответа — Monthly call quota exceeded. Коды и тела ошибок — в разделе документации «Ошибки».

Ограничитель запросов на стороне клиента: token bucket

Повтор лечит 429, а ограничитель на стороне клиента его предупреждает. Token bucket («ведро жетонов») устроен так: жетоны прибывают со скоростью rate в секунду, каждый запрос забирает один, а пустое ведро заставляет ждать. Вместимость burst задаёт, сколько запросов уйдёт подряд без паузы.

import time


class TokenBucket:
    """Не больше rate запросов в секунду, подряд до burst."""

    def __init__(self, rate, burst=1):
        self.rate, self.burst = rate, burst
        self.tokens = float(burst)
        self.last = time.monotonic()

    def take(self):
        while True:
            now = time.monotonic()
            self.tokens = min(self.burst, self.tokens
                              + (now - self.last) * self.rate)
            self.last = now
            if self.tokens >= 1:
                self.tokens -= 1
                return
            time.sleep((1 - self.tokens) / self.rate)

Лимит берите из поля rps_limit ответа /account/usage (раздел «Использование») или из заголовка X-RateLimit-Limit. Скорость ставьте чуть ниже лимита, например 0.9 * rps_limit: из-за неровной задержки сети запросы, отправленные с интервалом в полсекунды, могут прийти на сервер плотнее.

Мониторинг: заголовки X-RateLimit-* и X-Quota-*

Ответ с данными несёт состояние лимитов: X-RateLimit-Remaining и X-RateLimit-Reset — остаток и время сброса секундного окна, X-Quota-Remaining, X-Quota-Limit и X-Quota-Reset — остаток, размер и unix-время обнуления квоты. Полезнее одного остатка темп: какая доля квоты ушла к этому моменту периода.

PERIOD = 30 * 86400  # квота Genesis API считается за 30 дней


def watch(h):
    """Проверяет запас лимитов по заголовкам ответа."""
    if h.get("X-RateLimit-Remaining") == "0":  # окно выбрано
        reset = float(h.get("X-RateLimit-Reset", 0))
        time.sleep(max(0.0, reset - time.time()))
    try:
        left = int(h["X-Quota-Remaining"])
        limit = int(h["X-Quota-Limit"])
        reset = int(h["X-Quota-Reset"])
    except (KeyError, ValueError):
        return  # у ответов 429 заголовков X-Quota-* нет
    used = 1 - left / limit
    passed = 1 - (reset - time.time()) / PERIOD
    if used > passed + 0.05:
        print(f"квота уходит быстрее срока: {used:.0%} квоты"
              f" за {passed:.0%} периода")

Функция ждёт сброса окна, если лимит в нём выбран, и предупреждает, когда расход квоты обгоняет время больше чем на 5 процентных пунктов. Условный пример: к 15-му дню ушло 70 % квоты — при том же темпе вызовы кончатся через 15 / 0,7 ≈ 21,4 дня от начала периода. Те же числа без заголовков даёт /account/usage: calls_used, calls_limit и period_resets_at.

Расписание для нескольких эндпоинтов

Когда эндпоинтов несколько, у каждого свой интервал, а первые запросы разнесены по времени, чтобы не уходить пачкой. Интервал — по задаче, но не меньше freshness_sec: спредам нужна частота тарифа, фандингу и открытому интересу для многих стратегий хватит минуты.

import heapq

usage, _ = fetch("/account/usage")  # вызов не списывает
fresh = usage["freshness_sec"]
bucket = TokenBucket(rate=0.9 * usage["rps_limit"])

JOBS = {  # путь -> интервал опроса, с
    "/arbitrage/spot-spot": fresh,
    "/funding/spread": max(fresh, 60),
    "/market/open-interest": max(fresh, 60),
}
t0 = time.monotonic()
queue = [(t0 + i * fresh / len(JOBS), path, every)
         for i, (path, every) in enumerate(JOBS.items())]
heapq.heapify(queue)

while True:
    due, path, every = heapq.heappop(queue)
    time.sleep(max(0.0, due - time.monotonic()))
    bucket.take()
    data, hdrs = fetch(path)
    watch(hdrs)
    print(path, len(data))
    heapq.heappush(queue, (due + every, path, every))

На Start это 86 400 + 43 200 + 43 200 = 172 800 вызовов за 30 дней, 8,64 % квоты: спреды раз в 30 секунд, фандинг и открытый интерес раз в 60. Первые запросы уходят с шагом 30 / 3 = 10 секунд, дальше каждый эндпоинт держит свой ритм, а bucket.take() страхует от совпадений. Бот с таким опросом и уведомлениями в Telegram собран в статье «Бот для арбитража криптовалют на Python».

Что делать при 503 и сбоях сервера

По RFC 9110 код 503 Service Unavailable означает временную перегрузку или обслуживание, и сервер может указать паузу в Retry-After. В Genesis API это 503 snapshot_not_ready: данные пересобираются или их источник перезапускается. Повторите запрос через Retry-After секунд: обычно пауза — несколько секунд.

Пока свежего ответа нет, у бота остаются данные прошлого опроса, и они стареют. Перед сигналом сравнивайте meta.updated_at с текущим временем: связка по снимку минутной давности на бирже могла уже закрыться. Другие риски — в уроке «Риски автоматизации».

500 internal_error, таймауты и обрывы связи повторяют с экспоненциальной паузой. Если ошибка держится, напишите в поддержку: значение X-Request-Id, время запроса в UTC, эндпоинт и код ответа. Ключ присылать не нужно.

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

Сколько запросов в секунду можно отправлять в Genesis API?

Столько, сколько разрешает тариф: 1 на Trial, 2 на Start, 5 на Pro и 15 на Max. Лимит считается на ключ, в него входят ответы 304 и ошибки. Значение тарифа — в заголовке X-RateLimit-Limit и в поле rps_limit ответа /account/usage.

Списываются ли ошибки и ответы 304?

Нет. Квоту тратит только ответ 200, а 304, 429, 503 и другие ошибки бесплатны и денег не списывают. Но они занимают место в лимите запросов в секунду, поэтому повторы без паузы сами вызывают новые 429.

Как не упереться в лимит 60 МБ за 10 секунд?

Включите gzip: лимит считает сжатые данные. Присылайте If-None-Match к полным наборам: 304 приходит без тела. Тяжёлые разделы вроде аналитики фандинга берите срезом с coin, а один полный набор не скачивайте чаще freshness_sec. Ответы меньше 64 КБ в лимит не входят, а опрос всех наборов с частотой тарифа, по документации, укладывается в него с запасом.

Что значит ошибка 429 Too Many Requests?

Сервер отклонил запрос, потому что клиент превысил лимит за отрезок времени. Ответ может нести Retry-After — сколько секунд ждать; без него паузу удваивают после каждой неудачи. В Genesis API 429 приходит с кодом rate_limited или download_limited.