Genesis API для ИИ-агентов: OpenAPI, llms.txt и вызов функций
Коротко
- Для агентов опубликованы openapi.json (OpenAPI 3.1, 37 операций с тарифами), llms-full.txt, llms.txt и каталог API по RFC 9727.
- Модель выбирает инструмент и аргументы, а запрос с ключом делает ваш сервер и возвращает модели короткий JSON с временем данных.
- Genesis API только читает данные. Частоту запросов ограничивает ваш код, тексты из ответов модель читает как данные, сделки подтверждает человек.
Genesis API — REST API с данными крипторынка, который ИИ-агент вызывает как инструмент: модель решает, какие данные нужны, ваш сервер делает GET-запрос с ключом и возвращает ей короткий JSON. Для агентов и языковых моделей опубликовано машиночитаемое описание API: спецификация OpenAPI 3.1, полный справочник в Markdown и каталог API. Сами данные — те же, что показывает сайт: спреды CEX и DEX, стаканы, фандинг, ончейн и рынки предсказаний.
Машиночитаемые файлы
| Файл | Что внутри | Для чего |
|---|---|---|
| genesisarbitrage.com/openapi.json | OpenAPI 3.1: 37 операций, параметры, схемы ответов, тарифы в x-genesis-plans, заголовки лимитов | Импорт в API-клиент, генерация кода, инструменты агента |
| genesisarbitrage.com/llms-full.txt | Полный справочник одним Markdown-файлом: эндпоинты, параметры, поля, примеры, лимиты, ошибки | Контекст модели, которая пишет код или отвечает про API |
| genesisarbitrage.com/llms.txt | Обзор сайта: Genesis API, инструменты, Руководство, курс, глоссарий, блог | Первое знакомство модели с сайтом |
| genesisarbitrage.com/.well-known/api-catalog | Каталог API по RFC 9727: ссылки на спецификацию, документацию, тарифы и статус | Поиск API по домену |
Спецификация написана по стандарту OpenAPI 3.1, где схемы — надмножество JSON Schema 2020-12, поэтому параметры операций переносятся в описание инструмента почти без правок. llms.txt — формат, предложенный в 2024 году: Markdown-файл в корне сайта с кратким описанием и ссылками для языковых моделей. Каталог лежит по адресу, который задаёт RFC 9727.
На страницах документации, описания и тарифов Genesis API в <head> стоит <link rel="service-desc"> на openapi.json. Это тип связи из RFC 8631 для описания сервиса, которое читают машины. Фрагмент спецификации, сокращённый:
{
"openapi": "3.1.0",
"servers": [{ "url": "https://api.genesisarbitrage.com/v1" }],
"paths": {
"/arbitrage/spot-spot": {
"get": {
"operationId": "getArbitrageSpotSpot",
"x-genesis-plans": ["trial", "start", "pro", "max"],
"parameters": [
{ "name": "coin", "in": "query",
"schema": { "type": "string" } },
{ "name": "min_spread", "in": "query",
"schema": { "type": "number" } },
…
]
}
}
}
}
У каждой операции — operationId, параметры с типами, схема ответа 200, ответ 304, коды ошибок и заголовки X-RateLimit-*, X-Quota-*, X-Request-Id и ETag. Ключ описан схемой безопасности ApiKeyAuth: тип apiKey, заголовок X-API-Key.
Как подключить
Получите ключ и положите его на сервер
Ключ
gns_live_…выдаётся в профиле, в блоке Genesis API, и показывается один раз. Сохраните его в переменной окруженияGENESIS_API_KEYна сервере, где работает агент. Хранение и перевыпуск разобраны в инструкции «API-ключ».Импортируйте спецификацию
API-клиент или фреймворк агентов, который принимает OpenAPI, строит запросы и инструменты прямо из
openapi.json: базовый адрес берёт изservers, заголовок ключа — изApiKeyAuth. Как передаётся ключ, описано в разделе «Аутентификация».Оставьте нужные операции
Описание каждого инструмента занимает место в контексте модели, а выбирать проще из нескольких. Оставьте операции под задачу и уберите те, которых нет в вашем тарифе по
x-genesis-plans: они ответят403 plan_restricted.Дайте модели справочник
Если агент пишет код или отвечает на вопросы об API, добавьте в контекст
llms-full.txt: там параметры, поля и примеры каждого эндпоинта, лимиты и коды ошибок.Проверьте ключ первым вызовом
/account/usageвернёт тариф, использованную квоту, лимит запросов в секунду и свежесть данных.
Как модель вызывает Genesis API
Вызов функций (function calling) — механизм, в котором модель вместо текста возвращает имя инструмента и аргументы, а сам вызов выполняет ваш код. Цикл такой:
- Вместе с вопросом пользователя модель получает описания инструментов: имя, назначение и параметры в JSON Schema.
- Модель отвечает вызовом:
get_spreadsс аргументами{"coin": "TON", "min_spread": 0.5}. - Ваш сервер проверяет аргументы, делает GET с заголовком
X-API-Keyи урезает ответ до нужных полей. - Короткий JSON с временем данных уходит модели, и она отвечает пользователю.
Модель не ходит в сеть и не видит ключа: ей доступны только описание инструмента и результат. Описание инструмента get_spreads поверх эндпоинта Спот – Спот:
{
"name": "get_spreads",
"description": "Где купить монету дешевле и продать дороже (CEX)",
"parameters": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Тикер монеты, например BTC"
},
"min_spread": {
"type": "number",
"description": "Минимальный спред, %: 0.5 — это 0,5 %"
}
},
"additionalProperties": false
}
}
Поле со схемой параметров у провайдеров моделей называется по-разному, в MCP — inputSchema; внутри всегда JSON Schema. Свойства coin и min_spread взяты из параметров операции getArbitrageSpotSpot, а в description пишут, когда вызывать инструмент: модель выбирает по этому тексту.
Обработчик на Python вызывает /arbitrage/spot-spot и возвращает модели до 10 строк с нужными полями и meta.updated_at:
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot"
KEY = os.environ["GENESIS_API_KEY"] # ключ только на сервере
FIELDS = ("coin", "exchange_buy", "exchange_sell", "spread_pct",
"withdraw_enabled_buy", "deposit_enabled_sell")
cache = {} # параметры -> (время, ETag, тело ответа)
def get_spreads(coin=None, min_spread=None):
params = {"coin": coin, "min_spread": min_spread}
params = {k: v for k, v in params.items() if v is not None}
ck = tuple(sorted(params.items()))
ts, etag, body = cache.get(ck, (0, None, None))
if body and time.time() - ts < body["meta"]["freshness_sec"]:
return shorten(body) # раньше данные не обновятся
headers = {"X-API-Key": KEY}
if etag:
headers["If-None-Match"] = etag
for attempt in range(2): # 429 и 503: ждём Retry-After и повторяем
r = requests.get(API, headers=headers, params=params,
timeout=10)
if r.status_code not in (429, 503) or attempt:
break
time.sleep(min(int(r.headers.get("Retry-After", 5)), 30))
if r.status_code == 200:
body, etag = r.json(), r.headers.get("ETag")
elif r.status_code != 304:
return {"error": r.status_code} # модель увидит код ошибки
cache[ck] = (time.time(), etag, body)
return shorten(body)
def shorten(body):
rows = sorted(body["data"], key=lambda x: x["spread_pct"],
reverse=True)[:10]
t = body["meta"]["updated_at"]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": [{f: x.get(f) for f in FIELDS} for x in rows]}
Ответ живёт в кеше meta.freshness_sec секунд: раньше данные не обновятся. Затем обработчик шлёт прошлый ETag в If-None-Match, и ответ 304 квоту не тратит. На 429 и 503 он ждёт Retry-After, но не дольше 30 с, и повторяет запрос один раз, другие ошибки отдаёт модели кодом. Модели уходят 10 строк по 6 полей. Условный пример: полный ответ из 214 строк по 22 поля — это 214 × 22 = 4 708 значений, урезанный — 10 × 6 = 60.
Правила для агента
| Правило | Как выполнить |
|---|---|
| Ключ только на сервере | Переменная окружения обработчика; ключа нет в промпте, в браузере и в логах переписки |
| API только читает | Genesis API ордеров не ставит; сделку на бирже подтверждает человек |
| Частоту ограничивает ваш код | Кеш на freshness_sec, ETag и If-None-Match, очередь под лимит запросов в секунду |
| Фильтры вместо полного набора | coin, min_spread, exchange; модели — до 10 строк и нужные поля |
| Время данных в каждом ответе | updated_at и возраст в результате инструмента и в ответе пользователю |
| Внешние тексты — только данные | Названия рынков, исходы, имена трейдеров и тексты сигналов модель не исполняет |
Модель может запросить несколько инструментов сразу, а лимит считает все запросы ключа: на Trial это 1 запрос в секунду, на Max — 15. Ответы 304 и ошибки квоту не тратят, но в лимит в секунду входят — подробности в разделе «Тарифы и лимиты» и в инструкции о лимитах.
Поля title и outcome рынков предсказаний, name трейдеров, token_name ончейн-событий, message_ru и message_en сигналов Genesis AI+ приходят из внешних источников. Рынок могут назвать фразой «забудь прошлые инструкции и…» — это prompt injection, внедрение команд через данные. Передавайте такие поля только внутри результата инструмента, обрезайте длину и пропишите в системном промпте, что текст в результатах — данные.
MCP: свой сервер поверх REST API
MCP (Model Context Protocol) — открытый стандарт подключения ИИ-приложений к внешним системам. MCP-сервер даёт приложению инструменты, ресурсы и шаблоны промптов, обмен идёт сообщениями JSON-RPC 2.0: локально — через stdio, удалённо — через Streamable HTTP. Спецификация и SDK для разных языков — на modelcontextprotocol.io.
Официального MCP-сервера у Genesis API нет. Свой собирают из тех же обработчиков: инструмент MCP — это GET к эндпоинту Genesis API, параметры описаны JSON Schema в inputSchema, ключ лежит в переменной окружения сервера. Локальный сервер через stdio держит ключ на вашей машине. Удалённый закройте авторизацией (MCP рекомендует OAuth), иначе вашей квотой воспользуется любой, кто узнает адрес.
Как устроены агенты на данных крипторынка в целом, разобрано в статье «Данные крипторынка для ИИ-агентов», риски автоматизации — в пятом уроке курса.
Вопросы и ответы
Есть ли у Genesis API официальный MCP-сервер?
Нет. Для агентов опубликованы openapi.json, llms-full.txt и каталог API. MCP-сервер поверх REST API можно написать самому: каждый инструмент — GET-запрос с ключом из переменной окружения.
Может ли агент торговать через Genesis API?
Нет. Genesis API только читает данные и ордеров не ставит. Агент находит связки и присылает уведомления, сделку человек делает сам на бирже.
Какой тариф нужен агенту?
Подойдёт любой: Trial даёт 1 запрос в секунду и свежесть 60 с, Max — 15 запросов в секунду и 5 с. Состав эндпоинтов — в x-genesis-plans и на странице «Тарифы Genesis API».
Почему модель называет устаревшие цены?
Данные отстают на свежесть тарифа, а кеш обработчика добавляет до freshness_sec. Отдавайте модели updated_at и возраст данных и просите называть время в ответе.