Genesis Arbitrage

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

Первый запрос к API: HTTP, заголовки и JSON

Коротко

  • HTTP-запрос к API — метод, адрес из базового адреса, пути и параметров и заголовки. Ключ Genesis API передают только в заголовке X-API-Key.
  • Код ответа подсказывает следующий шаг: 200 — читать данные, 304 — данные прежние, 401 и 403 — проверить ключ и тариф, 429 и 503 — подождать Retry-After секунд.
  • Ответ Genesis API — конверт из success, data и meta. Проценты приходят числом (0.01 — это 0,01 %), время — в unix-секундах.
  • Частые ошибки новичка — ключ в адресе, пустая переменная окружения, опечатка в пути или в имени параметра. Опечатка в параметре ошибки не даёт: приходит полный набор вместо отфильтрованного.

Чтобы сделать запрос к API, программа отправляет HTTP-запрос — метод, адрес и заголовки, — а сервер возвращает код ответа, свои заголовки и тело, у Genesis API это JSON. Отправить запрос можно из терминала через curl или из кода на любом языке с HTTP-клиентом. Первый запрос — состояние ключа через /account/usage, второй — ставки фандинга BTC через /funding/rates. Что такое API и что через него автоматизируют, разобрано в уроке 1.

Из чего состоит запрос

Так выглядит запрос ставок фандинга BTC, который curl отправляет серверу, — его показывает флаг -v строками со знаком > (ключ заменён заглушкой):

> GET /v1/funding/rates?coin=BTC HTTP/1.1
> Host: api.genesisarbitrage.com
> User-Agent: curl/8.7.1
> Accept: */*
> X-API-Key: gns_live_XXXXXXXXXXXXXXXX
ЧастьВ примереЧто значит
МетодGETПрочитать данные; у Genesis API все эндпоинты — GET
Базовый адресhttps://api.genesisarbitrage.com/v1Сервер и версия API
Путь/funding/ratesЭндпоинт ставок фандинга
Параметры?coin=BTCФильтр: только BTC
ЗаголовокX-API-KeyКлюч, по которому сервер узнаёт аккаунт и тариф

Параметры идут после ? парами имя=значение, между парами ставят &: ?coin=BTC&exchange=Binance,OKX. Фильтры Genesis API необязательны — без coin тот же эндпоинт вернёт все монеты. Дробные числа пишут через точку: min_spread=0.5.

Заголовки — строки «имя: значение», которые уходят вместе с адресом. Регистр в именах не важен (RFC 9110, раздел 5.1): X-API-Key и x-api-key — один заголовок, а x-request-id строчными в выводе curl — тот же X-Request-Id. Ключ Genesis API принимает только в X-API-Key.

Коды ответа

Первая строка ответа — код статуса. По нему программа решает, что делать дальше:

КодЧто значитЧто делать
200Запрос выполнен, данные в телеЧитать data и meta
304Данные не изменились с прошлого ответаВзять прошлые данные
401Ключа нет, он неверен, отозван или подписка истеклаПроверить заголовок и подписку
403Эндпоинт не входит в тариф (plan_restricted)Сменить тариф или убрать запрос
429Превышен лимит запросов, объёма скачивания или квотаПодождать Retry-After секунд
503Данные пересобираются (snapshot_not_ready)Повторить через Retry-After секунд

Квоту тратит только 200: 304 и ошибки бесплатны, но учитываются в лимите запросов в секунду. 304 приходит лишь на запрос с заголовком If-None-Match — о нём и о кодах 400, 404, 410 и 500 подробно в инструкции «Ответы и ошибки Genesis API». Почему повтор после 429 делают с паузой, объясняет термин «Ошибка 429».

Первый запрос: /account/usage

/account/usage показывает состояние ключа: тариф, расход квоты и лимиты. Эндпоинт есть на всех тарифах и вызов не списывает, поэтому первый запрос — к нему. Сначала положите ключ в переменную окружения, затем отправьте запрос:

# вставьте ключ и нажмите Enter: на экране его не будет
read -s GENESIS_API_KEY
export GENESIS_API_KEY

curl -i "https://api.genesisarbitrage.com/v1/account/usage" \
  -H "X-API-Key: $GENESIS_API_KEY"

Флаг -i печатает строку статуса и заголовки перед телом. Тело ответа, условный пример для тарифа Trial:

{
  "success": true,
  "data": {
    "plan": "trial",
    "calls_used": 0,
    "calls_limit": 500000,
    "rps_limit": 1,
    "freshness_sec": 60,
    "period_resets_at": 1796463000
  },
  "meta": {
    "count": 1,
    "updated_at": 1794730811,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

plan — тариф, calls_used из calls_limit — расход квоты за 30-дневный период. В примере 0: других запросов ещё не было, а сам /account/usage вызов не списывает. rps_limit — запросов в секунду, freshness_sec — как часто обновляются данные тарифа, period_resets_at — когда обнулится квота. Поля описаны в разделе документации «Использование».

Среди заголовков найдите X-Request-Id — номер запроса, который присылают в поддержку вместо ключа, и X-RateLimit-Remaining — сколько запросов осталось в текущем окне лимита.

Тот же запрос на Python

Скрипт для Python 3.10+ с библиотекой requests берёт ключ из той же переменной окружения:

import os
from datetime import datetime, timezone

import requests

BASE = "https://api.genesisarbitrage.com/v1"
key = os.environ["GENESIS_API_KEY"]  # KeyError, если не задан

r = requests.get(
    BASE + "/account/usage",
    headers={"X-API-Key": key},
    timeout=10,  # без таймаута requests ждёт ответа бесконечно
)
body = r.json()
if r.status_code != 200 or not body.get("success"):
    err = body.get("error") or {}
    raise SystemExit(f"{r.status_code} {err.get('code')}")

usage = body["data"]
ts = usage["period_resets_at"]
resets = datetime.fromtimestamp(ts, timezone.utc)
print("тариф:", usage["plan"])
print("вызовов:", usage["calls_used"], "из", usage["calls_limit"])
print("сброс квоты:", resets.strftime("%d.%m.%Y %H:%M UTC"))
print("X-Request-Id:", r.headers.get("X-Request-Id"))

os.environ["GENESIS_API_KEY"] останавливает скрипт, если переменная не задана, — это лучше, чем запрос без ключа и ответ 401. r.headers не зависит от регистра, поэтому X-Request-Id найдётся, даже если сервер прислал x-request-id.

period_resets_at — unix-время: число секунд с 1 января 1970 года, 00:00 UTC. datetime.fromtimestamp(ts, timezone.utc) переводит его в дату: 1796463000 — это 5 декабря 2026 года, 09:30 UTC.

Второй запрос: ставки фандинга BTC

Фандинг — периодический платёж между лонгами и шортами бессрочного фьючерса, биржи начисляют его раз в 8, 4 или 1 час. /funding/rates отдаёт ставки по всем биржам, параметр coin оставляет одну монету. Ответ на GET /funding/rates?coin=BTC, условный пример с двумя биржами из списка:

{
  "success": true,
  "data": [
    {
      "coin": "BTC",
      "exchanges": [
        {
          "exchange": "Bitget",
          "funding_pct": 0.01,
          "funding_8h_pct": 0.01,
          "next_payout": "00:00",
          "interval": "8h",
          "price": 96021.5,
          "trade_url": "https://www.bitget.com/futures/usdt/BTCUSDT"
        },
        {
          "exchange": "Hyper",
          "funding_pct": 0.0013,
          "funding_8h_pct": 0.0104,
          "next_payout": null,
          "interval": "1h",
          "price": 96030.0,
          "trade_url": "https://app.hyperliquid.xyz/trade/BTC"
        },
        …
      ]
    }
  ],
  "meta": {
    "count": 1,
    "updated_at": 1794675861,
    "freshness_sec": 60,
    "plan": "trial"
  }
}

Как читать этот ответ:

Все поля — в разделе «Ставки фандинга». Блок ниже продолжает скрипт: BASE, key и импорты уже есть.

r = requests.get(
    BASE + "/funding/rates",
    headers={"X-API-Key": key},
    params={"coin": "BTC"},  # requests соберёт ?coin=BTC
    timeout=10,
)
r.raise_for_status()  # исключение на 4xx и 5xx
body = r.json()
if not body["data"]:
    raise SystemExit("монеты нет в данных: проверьте тикер")

ts = body["meta"]["updated_at"]
snap = datetime.fromtimestamp(ts, timezone.utc)
print("снимок от", snap.strftime("%d.%m.%Y %H:%M:%S UTC"))

rows = body["data"][0]["exchanges"]
rows.sort(key=lambda e: e["funding_8h_pct"], reverse=True)
for e in rows:
    print(f'{e["exchange"]:<8} {e["funding_pct"]:>7} % '
          f'за {e["interval"] or "?"}, '
          f'{e["funding_8h_pct"]:>7} % за 8 ч')

На ответе из примера скрипт напечатает:

снимок от 14.11.2026 17:04:21 UTC
Hyper     0.0013 % за 1h,  0.0104 % за 8 ч
Bitget      0.01 % за 8h,    0.01 % за 8 ч

Hyper оказался выше Bitget, хотя его ставка за интервал меньше в 0,01 / 0,0013 ≈ 7,7 раза. Без приведения к 8 часам такое сравнение ошибается.

Типичные ошибки новичка

ОшибкаЧто вернёт серверКак исправить
Ключ в адресе: ?api_key=…401 и «Missing X-API-Key header.»Ключ — только в заголовке X-API-Key
Пустая переменная с ключом401 с тем же текстом: curl не отправит пустой заголовокПроверить длину: echo ${#GENESIS_API_KEY}
Опечатка в пути: /v1/funding/rate или путь без /v1404Сверить путь с документацией
Опечатка в имени параметра: coins=BTC200 и все монеты: неизвестный параметр не применяетсяСверить meta.count: с coin=BTC он равен 1
Запятая в дроби: min_spread=0,5200, фильтр не применёнДробь через точку: 0.5
Пара вместо тикера: coin=BTCUSDT200, пустой data, meta.count равен 0Тикер монеты: BTC

Опечатка в параметре коварнее остальных: ошибки нет, а скрипт получает полный набор вместо одной монеты и тратит на него вызов. Поэтому после нового фильтра сверяйте meta.count с ожиданием.

Попробуйте

  1. Отправьте запрос без ключа

    curl -i "https://api.genesisarbitrage.com/v1/account/usage" вернёт 401, в теле — invalid_key и «Missing X-API-Key header.». Найдите среди заголовков x-request-id.

  2. Повторите запрос с ключом

    Задайте переменную через read -s и отправьте запрос из раздела про /account/usage. Придёт 200 и ваш тариф в data.plan.

  3. Сверьте дату сброса

    Запустите скрипт на Python и сравните дату сброса квоты со строкой «сброс …» в блоке «Genesis API» профиля. Пошаговое получение ключа — в быстром старте с Genesis API.

  4. Найдите самую высокую ставку

    Добавьте второй блок скрипта и найдите биржу с наибольшей funding_8h_pct. Пересчитайте её funding_pct к 8 часам вручную: ставка × 8 / интервал в часах.

  5. Сломайте запрос намеренно

    Замените coin на coins и сравните meta.count, затем уберите s в /funding/rates и посмотрите код ответа.

Какие эндпоинты нужны для решений по спредам, стаканам и фандингу, разбирает урок 3.

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

Можно ли отправить запрос к API из браузера?

Адрес без ключа — да: https://api.genesisarbitrage.com/health откроется в браузере и покажет {"ok":true}. Заголовок X-API-Key строка адреса не добавляет, поэтому запросы с ключом отправляют из curl, скрипта или формы «Проверить запрос» в документации. В код сайта или расширения ключ не встраивают: его увидит любой, кто откроет код страницы.

Чем флаг -i отличается от -v в curl?

-i печатает строку статуса и заголовки ответа перед телом. -v показывает ещё и сам запрос: строки с > — то, что ушло на сервер, строки с < — то, что пришло в ответ.

Как перевести unix-время в дату без Python?

В macOS — командой date -u -r 1796463000, в Linux — date -u -d @1796463000. Для этого числа обе покажут 5 декабря 2026 года, 09:30 UTC.