Genesis Arbitrage

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

Монитор спредов и фандинга на Python

Коротко

  • Монитор — консольная программа: раз в meta.freshness_sec секунд она забирает полные наборы /arbitrage/spot-spot и /funding/spread, отбирает строки по порогам, печатает таблицы и дописывает их в CSV.
  • Наборы запрашиваются без фильтров и поэтому приходят с ETag: повтор с If-None-Match до нового снимка вернёт 304 без списания квоты. При 429 и 503 клиент ждёт Retry-After секунд.
  • Остаток после условных комиссий тейкера 0,1 % на ногу — спред минус 0,2 п. п. На Pro и Max монитор пересчитывает три лучшие связки по стаканам на $1 000.
  • Верхняя оценка расхода — 86 400 вызовов за 30 дней на Trial, 17,28 % квоты, и 1 296 000 на Pro с проверкой стаканов, 25,92 %.

Монитор спредов и фандинга — программа, которая по кругу забирает спреды между биржами и спреды фандинга, оставляет строки выше порогов и печатает их таблицей в консоли. Монитор из этого урока — около 170 строк на Python: данные он берёт из Genesis API, историю пишет в CSV, сделок не открывает. Уведомлений он тоже не шлёт — бот с сообщениями в Telegram разобран в статье «Бот для арбитража криптовалют на Python».

План опроса: эндпоинты, частота и расход вызовов

ЗапросЧто даётКогда
/account/usageТариф, freshness_sec, rps_limitПри старте, квоту не тратит
/arbitrage/spot-spotСвязки Спот – СпотКаждый проход, полный набор
/funding/spreadЛучшие пары бирж по фандингуКаждый проход, полный набор
/orderbooks/spreads/spot-spot«Δ по ордерам» на $1 000Pro и Max, три связки за проход

Частоту задаёт meta.freshness_sec: тариф получает новый снимок раз в 60 секунд на Trial, 30 на Start, 10 на Pro и 5 на Max. Опрос чаще вернёт тот же снимок с тем же meta.updated_at. Поля обоих наборов — в документации Спот — Спот и «Спред фандинга».

Тариф и квотаПаузаЗапросов за проходВызовов за 30 дней
Trial, 500 тыс.60 с286 400
Start, 2 млн30 с2172 800
Pro, 5 млн10 с51 296 000
Max, 10 млн5 с52 592 000

На Trial: 2 × 86 400 / 60 × 30 = 86 400 вызовов, 17,28 % квоты. На Pro к двум наборам добавляются три проверки стакана: 5 × 86 400 / 10 × 30 = 1 296 000 вызовов, 25,92 % из 5 млн. Правила квоты — в инструкции «Лимиты Genesis API».

Лимит запросов в секунду монитор соблюдает паузой 1,1 / rps_limit секунды между запросами: 1,1 секунды на Trial, 0,22 — на Pro. Проход из пяти запросов на Pro укладывается примерно в секунду.

Настройки и клиент с ETag и Retry-After

Семь блоков кода в уроке — полный файл monitor.py: сохраните их подряд в одном файле. Пороги в настройках условные, подберите их под свои комиссии и суммы.

import csv
import os
import time
from datetime import datetime, timezone

import requests

API = "https://api.genesisarbitrage.com/v1"
MIN_SPREAD = 1.0     # спред строки от 1 %
MIN_VOLUME = 50_000  # объём за 24 ч на обеих биржах от $50 000
MIN_FUNDING = 0.05   # спред фандинга от 0,05 %
FEE = 0.1            # условная комиссия тейкера на ногу, %
TOP = 10             # строк в каждой таблице
BOOK_TOP = 3         # связок со стаканом за проход, Pro и Max
BOOK_USD = 1000      # объём проверки стакана, USD
CSV_FILE = "monitor.csv"

api = requests.Session()
api.headers["X-API-Key"] = os.environ["GENESIS_API_KEY"]
cache = {}                # запрос -> (ETag, тело ответа)
stats = {200: 0, 304: 0}  # сколько пришло ответов 200 и 304
pace = {"gap": 1.1, "last": 0.0}  # пауза между запросами, с

Ключ берётся из переменной окружения GENESIS_API_KEY и уходит в заголовке X-API-Key каждого запроса, в адрес его не вставляют. cache хранит ETag и тело последнего ответа на каждый запрос, stats считает ответы 200 и 304, pace помнит время последнего запроса.

def get(path, params=None):
    """GET к Genesis API: пауза, ETag и повтор по Retry-After."""
    key = (path, tuple(sorted((params or {}).items())))
    for _ in range(4):  # запрос и до трёх повторов
        wait = pace["last"] + pace["gap"] - time.monotonic()
        if wait > 0:
            time.sleep(wait)  # не больше rps_limit запросов в секунду
        pace["last"] = time.monotonic()
        hdr = {"If-None-Match": cache[key][0]} if key in cache else {}
        r = api.get(API + path, params=params, headers=hdr,
                    timeout=15)
        if r.status_code == 304:  # снимок не изменился
            stats[304] += 1
            return cache[key][1]
        if r.status_code in (429, 503):
            wait = int(r.headers.get("Retry-After", "5"))
            if wait > 60:  # так приходит исчерпанная квота
                raise SystemExit(f"Квота исчерпана: ждать {wait} с")
            time.sleep(wait)
            continue
        r.raise_for_status()  # 400, 401, 403: повтор не поможет
        stats[200] += 1
        body = r.json()
        if "ETag" in r.headers:  # есть только у полного набора
            cache[key] = (r.headers["ETag"], body)
        return body
    raise RuntimeError("API занят, повтор в следующем проходе")

ETag — метка версии снимка. get отправляет её обратно в заголовке If-None-Match, и пока снимок не обновился, сервер отвечает 304 без тела: квота не тратится, функция отдаёт прошлое тело. При 429 и 503 она ждёт Retry-After секунд и повторяет запрос, а пауза длиннее минуты значит, что кончилась квота периода, и монитор останавливается. Коды ошибок и правила повторов — в инструкции «Ответы и ошибки Genesis API».

Спреды и фандинг: загрузка, пороги и сортировка

def spot_rows():
    """Связки Спот – Спот выше порогов, монету можно перевести."""
    body = get("/arbitrage/spot-spot")  # без фильтров: есть ETag
    rows = []
    for x in body["data"]:
        vol = min(x["volume_24h_buy"] or 0, x["volume_24h_sell"] or 0)
        if (x["spread_pct"] >= MIN_SPREAD and vol >= MIN_VOLUME
                and x["withdraw_enabled_buy"]
                and x["deposit_enabled_sell"]):
            rows.append({**x, "net": net(x["spread_pct"])})
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]


def funding_rows():
    """Монеты с наибольшим спредом фандинга."""
    body = get("/funding/spread")  # без фильтров: есть ETag
    rows = [x for x in body["data"] if x["spread_pct"] >= MIN_FUNDING]
    rows.sort(key=lambda x: x["spread_pct"], reverse=True)
    return rows[:TOP], body["meta"]

Оба набора запрашиваются без параметров: ответ с min_spread, coin или другим фильтром собирается под запрос и приходит без ETag. Пороги монитор применяет у себя: спред от MIN_SPREAD, объём за 24 часа на обеих биржах от MIN_VOLUME, открытый вывод на бирже покупки и открытый ввод на бирже продажи. Объём null считается нулём, и такая строка не проходит.

Строки сортируются по spread_pct по убыванию, в таблицу идут первые TOP. В /funding/spread порог MIN_FUNDING сравнивается со spread_pct лучшей пары бирж.

Остаток после комиссий и проверка стакана

def net(spread_pct):
    """Остаток после двух комиссий тейкера, приближённо, %."""
    return round(spread_pct - 2 * FEE, 4)


def book_net(row):
    """Остаток после стакана на BOOK_USD и комиссий. Pro и Max."""
    body = get("/orderbooks/spreads/spot-spot",
               {"coin": row["coin"], "volume": BOOK_USD})
    pair = (row["exchange_buy"], row["exchange_sell"])
    for x in body["data"]:
        if (x["exchange_buy"], x["exchange_sell"]) != pair:
            continue
        od = x["order_delta"]
        if od["status"] != "ok":
            return od["status"]  # no_book или exhausted
        return net(od["spread_pct"])
    return "нет пары"  # связка пропала из набора

Условные комиссии тейкера 0,1 % на покупке и 0,1 % на продаже уменьшают спред примерно на 0,2 п. п.: связка с 1,62 % даёт 1,62 − 2 × 0,1 = 1,42 %. Подставьте в FEE комиссии своих бирж (мейкер и тейкер). Комиссии вывода в ответах API нет, и монитор её не учитывает.

На Pro и Max book_net пересчитывает три лучшие связки по стаканам: /orderbooks/spreads/spot-spot с монетой связки и volume=1000 возвращает её строки с объектом order_delta, и функция берёт строку с той же парой бирж («Δ по ордерам»). Если стакана нет или его не хватило, вместо числа приходит статус no_book или exhausted. Запрос с coin идёт без ETag и всегда стоит вызова, поэтому за проход проверок всего три — BOOK_TOP.

Таблица в консоли

def show(spot, s_meta, fund, f_meta):
    now = time.time()
    s_age = now - s_meta["updated_at"]
    f_age = now - f_meta["updated_at"]
    print(f"\nСпот – Спот, снимку {s_age:.0f} с")
    print(f"{'Монета':<8}{'Покупка → продажа':<20}"
          f"{'Спред':>7}{'−комис.':>9}{'Стакан':>11}")
    for x in spot:
        pair = f'{x["exchange_buy"]} → {x["exchange_sell"]}'
        book = x.get("book", "—")
        if isinstance(book, float):
            book = f"{book:.2f}"
        print(f'{x["coin"]:<8}{pair:<20}{x["spread_pct"]:>7.2f}'
              f'{x["net"]:>9.2f}{book:>11}')
    print(f"\nФандинг, снимку {f_age:.0f} с")
    for x in fund:
        b = x["best"]
        legs = (f'{b["exchange_1"]} {b["interval_1"] or "?"} / '
                f'{b["exchange_2"]} {b["interval_2"] or "?"}')
        print(f'{x["coin"]:<8}{legs:<27}{x["spread_pct"]:>8.4f} %')
    print(f"Ответов 200: {stats[200]}, 304: {stats[304]}")

В первой таблице — монета, пара бирж, spread_pct, остаток после комиссий и остаток после стакана; прочерк значит, что стакан не проверялся. Во второй — лучшая пара бирж по фандингу с интервалами начисления и spread_pct. Над таблицами — возраст снимка, текущее время минус meta.updated_at, внизу — сколько ответов 200 и 304 пришло с запуска.

История в CSV

def save(spot, fund):
    """Дописывает проход в CSV: время, набор, связка, спреды."""
    new = not os.path.exists(CSV_FILE)
    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")
    with open(CSV_FILE, "a", newline="", encoding="utf-8") as f:
        w = csv.writer(f)
        if new:
            w.writerow(["time_utc", "dataset", "coin", "leg_1",
                        "leg_2", "spread_pct", "net_pct", "book"])
        for x in spot:
            w.writerow([ts, "spot-spot", x["coin"], x["exchange_buy"],
                        x["exchange_sell"], x["spread_pct"], x["net"],
                        x.get("book")])  # None пишется пустой ячейкой
        for x in fund:
            b = x["best"]
            w.writerow([ts, "funding", x["coin"], b["exchange_1"],
                        b["exchange_2"], x["spread_pct"], None, None])

Таблица в консоли живёт до следующего прохода, а monitor.csv копит все проходы: по нему видно, сколько держится связка и в какие часы она появляется. Модуль csv входит в стандартную библиотеку Python. Файл открывают с newline="", как требует документация модуля, иначе в системах с переводом строки \r\n в файл попадёт лишний \r.

В колонке book — остаток после стакана в процентах или статус exhausted или no_book. None модуль пишет пустой ячейкой, поэтому у строк фандинга и непроверенных связок она пустая. Время записи — в UTC.

Главный цикл

def main():
    usage = get("/account/usage")["data"]  # квоту не тратит
    books = usage["plan"] in ("pro", "max")
    pace["gap"] = 1.1 / usage["rps_limit"]
    print("Тариф", usage["plan"], "| снимок раз в",
          usage["freshness_sec"], "с | стаканы:",
          "да" if books else "нет")
    pause = usage["freshness_sec"]
    while True:
        try:
            spot, s_meta = spot_rows()
            fund, f_meta = funding_rows()
            if books:
                for x in spot[:BOOK_TOP]:
                    x["book"] = book_net(x)
            show(spot, s_meta, fund, f_meta)
            save(spot, fund)
            pause = s_meta.get("freshness_sec", pause)
        except requests.HTTPError as e:
            if e.response.status_code < 500:
                raise  # ключ, тариф, параметры: повтор не поможет
            print("Сбой сервера, повтор:", e)
        except (requests.RequestException, RuntimeError) as e:
            print("Нет ответа, повтор:", e)
        time.sleep(pause)  # чаще freshness_sec — тот же снимок


if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nМонитор остановлен, история — в", CSV_FILE)

При старте монитор вызывает /account/usage: запрос квоту не тратит и возвращает тариф, freshness_sec и rps_limit («Использование»). По тарифу монитор решает, проверять ли стаканы, а по rps_limit — какую паузу держать между запросами. Сбои сети и ошибки 5xx он переживает до следующего прохода, а 4xx — неверный ключ, истёкшая подписка, тариф без эндпоинта — его останавливают.

Как запустить и читать вывод

python3 --version   # нужен Python 3.10 или новее
python3 -m pip install requests
export GENESIS_API_KEY="gns_live_XXXXXXXXXXXXXXXX"
python3 monitor.py

Вывод на тарифе Pro, условный пример:

Тариф pro | снимок раз в 10 с | стаканы: да

Спот – Спот, снимку 4 с
Монета  Покупка → продажа     Спред  −комис.     Стакан
KLM     ByBit → Gate           1.62     1.42       0.86
XYZ     MEXC → Gate            1.24     1.04  exhausted
ABC     BingX → HTX            1.12     0.92       0.31
QRS     Gate → OKX             1.05     0.85          —

Фандинг, снимку 4 с
XYZ     MEXC 4h / Bitget 8h          0.0600 %
ABC     Hyper 1h / CoinEx 8h         0.0500 %
Ответов 200: 6, 304: 0

KLM: спред строки 1,62 %, после двух комиссий — 1,42 %, после стакана на $1 000 и комиссий — 0,86 %. У XYZ стакана на $1 000 не хватило: сумму по такой связке уменьшают или связку пропускают. QRS — четвёртая строка, стакан для неё не запрашивался. В фандинге видно, как часто начисляет каждая биржа: Hyper (так в ответах называется Hyperliquid) — раз в час, CoinEx — раз в 8 часов. Остановить монитор — Ctrl+C.

Из четырёх пунктов проверки связки из урока 3 монитор сам закрывает разницу цен и перевод, стакан — на Pro и Max, а свежесть показывает над таблицей. Контракт и комиссию вывода сверяете вы.

Попробуйте

  1. Запустите монитор

    Первая строка вывода покажет тариф, шаг снимка и проверку стаканов — сверьте их с профилем.

  2. Сдвиньте порог

    Поставьте MIN_SPREAD = 0.5 и посмотрите, у скольких новых строк колонка «−комис.» остаётся выше нуля.

  3. Добавьте набор

    Скопируйте spot_rows для /arbitrage/futures-futures: формат строки тот же. Проверку ввода и вывода для фьючерсов уберите — монету между биржами там не переводят.

  4. Сверьте расход

    Через час вызовите /account/usage и сравните calls_used с оценкой: на Trial это до 2 × 60 = 120 вызовов в час.

  5. Найдите устойчивые связки

    Откройте monitor.csv в редакторе таблиц и посчитайте, сколько проходов подряд держалась каждая пара бирж.

Риски автоматизации — устаревшие данные, ошибки, ключи и ИИ-агенты — разобраны в уроке 5, экономный опрос с фильтрами, сжатием и ETag — в статье «Как опрашивать API без лимитов».

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

Чем монитор отличается от бота для арбитража?

Монитор печатает таблицу и пишет историю, бот присылает уведомления о новых связках и молчит о повторах. Запрос и отбор у них общие, бот с Telegram разобран в статье «Бот для арбитража криптовалют на Python».

Можно ли опрашивать чаще freshness_sec?

Новых данных это не даст: тариф получает снимок раз в freshness_sec секунд. Запрос без фильтров до нового снимка вернёт бесплатный 304, запрос с фильтрами спишет вызов за те же данные.

Почему в колонке «Стакан» прочерк?

«Δ по ордерам» есть только на Pro и Max, и монитор запрашивает его для трёх лучших связок (BOOK_TOP). На Trial и Start эндпоинт отвечает 403 plan_restricted, поэтому монитор его не вызывает.