Первый запрос к 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"
}
}
Как читать этот ответ:
- конверт:
successравенtrue, данные — вdata, служебные поля — вmeta;meta.count— число элементовdata, сcoin=BTCэто одна монета, а внутри неё массивexchangesпо биржам; - проценты приходят числом:
"funding_pct": 0.01— это 0,01 % за интервал, а не 1 %; на позицию $10 000 одна выплата по такой ставке — 10 000 × 0,01 / 100 = $1; funding_8h_pctприводит ставку к 8 часам, чтобы сравнивать биржи с разными интервалами: у Hyper интервал 1 час, и 0,0013 × 8 = 0,0104 % за 8 часов;next_payout— время следующей выплаты по UTC строкой «ЧЧ:ММ»,null— данных нет, это не ноль;meta.updated_at— unix-время сборки снимка: 1794675861 — это 14 ноября 2026 года, 17:04:21 UTC; на Trial снимок обновляется раз в 60 секунд.
Все поля — в разделе «Ставки фандинга». Блок ниже продолжает скрипт: 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 или путь без /v1 | 404 | Сверить путь с документацией |
Опечатка в имени параметра: coins=BTC | 200 и все монеты: неизвестный параметр не применяется | Сверить meta.count: с coin=BTC он равен 1 |
Запятая в дроби: min_spread=0,5 | 200, фильтр не применён | Дробь через точку: 0.5 |
Пара вместо тикера: coin=BTCUSDT | 200, пустой data, meta.count равен 0 | Тикер монеты: BTC |
Опечатка в параметре коварнее остальных: ошибки нет, а скрипт получает полный набор вместо одной монеты и тратит на него вызов. Поэтому после нового фильтра сверяйте meta.count с ожиданием.
Попробуйте
Отправьте запрос без ключа
curl -i "https://api.genesisarbitrage.com/v1/account/usage"вернёт401, в теле —invalid_keyи «Missing X-API-Key header.». Найдите среди заголовковx-request-id.Повторите запрос с ключом
Задайте переменную через
read -sи отправьте запрос из раздела про/account/usage. Придёт200и ваш тариф вdata.plan.Сверьте дату сброса
Запустите скрипт на Python и сравните дату сброса квоты со строкой «сброс …» в блоке «Genesis API» профиля. Пошаговое получение ключа — в быстром старте с Genesis API.
Найдите самую высокую ставку
Добавьте второй блок скрипта и найдите биржу с наибольшей
funding_8h_pct. Пересчитайте еёfunding_pctк 8 часам вручную: ставка × 8 / интервал в часах.Сломайте запрос намеренно
Замените
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.