Данные крипторынка для ИИ-агентов: API, вызов функций, MCP и llms.txt
Коротко
- Языковая модель знает рынок только до даты среза обучающих данных. Текущие цены, спреды и ставки фандинга она получает через инструменты: модель выбирает вызов и аргументы, а запрос к API делает ваш код.
- Инструмент поверх рыночного API делают узким: один эндпоинт, фильтры в параметрах, несколько строк с нужными полями и время данных в результате. Описания берут из спецификации OpenAPI, а MCP подключает те же инструменты к любому совместимому клиенту.
- Ключ хранится на сервере, текст из внешних данных модель получает только как результат инструмента, сделки подтверждает человек. Genesis API только читает данные и публикует для агентов openapi.json, llms-full.txt и каталог API.
ИИ-агент получает данные крипторынка через инструменты: модель решает, какие данные нужны, ваш код вызывает API криптовалют и возвращает ей короткий JSON с ценами, спредами и временем сборки данных. Подключают инструменты через вызов функций в API модели или через MCP-сервер, и оба способа работают поверх обычного REST API.
Примеры построены на Genesis API — REST API только для чтения с данными CEX, DEX, ончейна и рынков предсказаний. Как выбирать API криптовалют вообще — в статье «API криптовалют: какие бывают и как выбрать».
Почему модель не знает текущих цен
Языковую модель обучают на текстах, собранных до определённой даты, — даты среза знаний (knowledge cutoff). Листингов, ставок и цен после неё модель не знает, а цена BTC, названная по памяти, — число из обучающих текстов неизвестного дня. Текущего времени модель тоже не знает, если его не передали в запросе.
Для арбитража ответ по памяти бесполезен: спред между биржами живёт минуты, а ставка фандинга меняется каждый период начисления — раз в 8, 4 или 1 час. Живые числа приходят только из инструмента: справочник API в контексте учит модель путям и параметрам, но цен в нём нет.
| Что нужно модели | Откуда | Пример |
|---|---|---|
| Пути, параметры и поля API | Справочник в контексте | llms-full.txt, openapi.json |
| Цены, спреды, ставки | Вызов инструмента | GET /funding/spread?coin=TON |
| Время и возраст данных | Системный промпт и результат инструмента | updated_at, age_sec |
Как работает вызов функций
Вызов функций (function calling) — режим, в котором модель вместо текста возвращает имя инструмента и аргументы, а запрос выполняет ваш код. Условный пример: пользователь спрашивает, где сейчас самый большой спред фандинга по TON. Вызов и результат схематично:
{
"tool_call": {
"name": "get_funding",
"arguments": { "coin": "TON" }
},
"tool_result": {
"updated_at": 1794675860,
"age_sec": 12,
"rows": [
{
"coin": "TON",
"spread_pct": 0.04,
"pair": ["Bitget", "Bybit"],
"funding_pct": [0.05, 0.01],
"interval": ["8h", "8h"]
}
]
}
}
- Приложение отправляет модели вопрос и описания инструментов: имя, назначение и схему аргументов в JSON Schema.
- Модель возвращает вызов
get_fundingс аргументами{"coin": "TON"}. - Ваш код проверяет аргументы, делает
GET /funding/spread?coin=TONс заголовкомX-API-Keyи урезает ответ. - Результат уходит модели, и она отвечает: Bitget и Bybit, 0,05 % и 0,01 % за 8 часов, разница 0,04 %, данные 12-секундной давности.
- Если данных не хватает, модель вызывает следующий инструмент.
Модель не ходит в сеть и не видит API-ключ. Названия полей зависят от API модели: в Claude API схема лежит в input_schema, вызов приходит блоком tool_use, результат уходит блоком tool_result, а в MCP схема называется inputSchema. Внутри в обоих случаях JSON Schema.
Как проектировать инструменты поверх рыночного API
Один инструмент — одна задача
Модель выбирает инструмент по описанию, поэтому узкие инструменты надёжнее универсального call_api(path, params). Из пяти-семи инструментов под задачи агента выбрать проще, чем из 37 операций спецификации.
| Инструмент | Эндпоинт Genesis API | Тарифы |
|---|---|---|
get_spreads | /arbitrage/spot-spot | Все |
get_funding | /funding/spread | Все |
get_prediction_arbs | /predictions/arbitrage | Start, Pro, Max |
get_book | /orderbooks/book | Pro, Max |
В описании пишут, когда вызывать инструмент и в каких единицах числа: в Genesis API спреды и ставки — проценты, 0.92 значит 0,92 %.
Фильтры — в параметрах, проверка — в коде
Фильтры API — coin, exchange, min_spread — становятся параметрами инструмента. Модель заполняет их из вопроса, обработчик сверяет с белым списком параметров, типов и значений, а перечисления задаёт enum: у /orderbooks/book параметр market — только spot или futures. Путь запроса модель не собирает, лишние поля запрещает схема (additionalProperties: false).
Ответ с фильтром приходит без ETag, поэтому каждый повторный опрос с фильтром стоит вызова: бесплатного 304 не будет. Если агенту нужны десятки монет, выгоднее хранить полный набор без фильтров и опрашивать его с If-None-Match.
Компактный ответ
Условный пример: полный ответ /funding/spread без фильтров — 1 000 монет. У монеты на 10 биржах в строке 2 + 10 + 8 × 5 = 52 значения: монета, спред, 10 полей лучшей пары best и по 5 полей 8 остальных бирж в others. Весь ответ — 1 000 × 52 = 52 000 значений, а для ответа о лучших связках хватит 5 строк по 8 значений: 5 × 8 = 40.
Описания инструментов и результаты входят в контекст каждого шага: в Claude API они оплачиваются как входные токены.
Время данных и свежесть
Обработчик кладёт в результат updated_at — время сборки данных из meta.updated_at, unix-секунды, — и age_sec. Тогда модель напишет «данным 12 секунд» и не выдаст вчерашний спред за текущий.
Свежесть данных задаёт тариф: meta.freshness_sec — от 60 с на Trial до 5 с на Max. Раньше этого срока API вернёт тот же снимок, поэтому обработчик держит ответ в кеше freshness_sec секунд. У стаканов своё время: book_ts, age_sec и признак stale для книги старше 30 с.
Пример: инструмент get_funding
Описание в формате MCP; для Claude API то же содержимое кладут в input_schema. Параметр limit обработчик применяет сам: в API его нет.
{
"name": "get_funding",
"description": "Где фандинг монеты выше и ниже: лучшая пара бирж",
"inputSchema": {
"type": "object",
"properties": {
"coin": {
"type": "string",
"description": "Тикер монеты, например TON"
},
"min_spread": {
"type": "number",
"minimum": 0,
"description": "Минимальный спред, %: 0.05 — это 0,05 %"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 10,
"description": "Сколько строк вернуть, по умолчанию 5"
}
},
"additionalProperties": false
}
}
Обработчик на Python: кеш на freshness_sec, одна короткая пауза при 429 и 503, журнал без ключа и компактный результат с временем данных.
import logging
import os
import time
import requests
URL = "https://api.genesisarbitrage.com/v1/funding/spread"
KEY = os.environ["GENESIS_API_KEY"] # ключ живёт только на сервере
cache = {} # параметры запроса -> (время получения, тело ответа)
def get_funding(coin=None, min_spread=None, limit=5):
p = {"coin": coin and coin.upper(), "min_spread": min_spread}
p = {k: v for k, v in p.items() if v}
ck = tuple(sorted(p.items()))
got, body = cache.get(ck, (0, None))
if not body or time.time() - got >= body["meta"]["freshness_sec"]:
for attempt in range(2): # 429 и 503: короткую паузу ждём раз
r = requests.get(URL, params=p, timeout=10,
headers={"X-API-Key": KEY})
wait = int(r.headers.get("Retry-After", "0"))
if attempt or wait > 5 or r.status_code not in (429, 503):
break
time.sleep(wait)
logging.info("get_funding %s -> %s id=%s", p, r.status_code,
r.headers.get("X-Request-Id")) # журнал без ключа
if r.status_code != 200:
return {"error": r.status_code} # 401, 403, 429, 503
body = r.json()
cache[ck] = (time.time(), body)
t = body["meta"]["updated_at"]
top = sorted(body["data"], key=lambda x: -x["spread_pct"])
rows = [{"coin": x["coin"], "spread_pct": x["spread_pct"],
"pair": [x["best"]["exchange_1"], x["best"]["exchange_2"]],
"funding_pct": [x["best"]["funding_1_pct"],
x["best"]["funding_2_pct"]],
"interval": [x["best"]["interval_1"],
x["best"]["interval_2"]]}
for x in top[:min(max(int(limit), 1), 10)]]
return {"updated_at": t, "age_sec": int(time.time() - t),
"rows": rows}
Паузу дольше 5 секунд обработчик не ждёт: при исчерпанной квоте Retry-After тянется до сброса, иногда днями. Модель получает код и объясняет пользователю, что случилось: 403 — это plan_restricted, эндпоинт вне тарифа (ошибки Genesis API).
OpenAPI как источник описаний инструментов
OpenAPI — стандарт машиночитаемого описания HTTP API: операцию в нём описывают идентификатор operationId, краткое описание summary и параметры со схемой. В версии 3.1 схема — надмножество JSON Schema 2020-12 (спецификация OpenAPI 3.1), а inputSchema в MCP по умолчанию читается как JSON Schema 2020-12. Поэтому параметры переходят в инструмент без пересчёта.
Скрипт собирает инструменты из спецификации Genesis API: берёт нужные операции, пропускает не входящие в тариф по x-genesis-plans и переносит параметры query и path. Заголовки ставит обработчик.
import requests
SPEC = "https://genesisarbitrage.com/openapi.json"
def tools_from_spec(wanted, plan):
"""wanted: operationId -> имя инструмента; plan: trial … max."""
spec = requests.get(SPEC, timeout=15).json()
tools, routes = [], {}
for path, item in spec["paths"].items():
op = item.get("get", {})
name = wanted.get(op.get("operationId"))
if not name or plan not in op.get("x-genesis-plans", []):
continue # не нужна или вне тарифа (403 plan_restricted)
props, required = {}, []
for prm in op.get("parameters", []):
if "$ref" in prm or prm["in"] not in ("query", "path"):
continue # X-API-Key и If-None-Match ставит обработчик
props[prm["name"]] = {**prm["schema"],
"description": prm["description"]}
if prm.get("required"):
required.append(prm["name"])
tools.append({
"name": name,
"description": op["description"].split("\n\n")[0],
"inputSchema": {"type": "object", "properties": props,
"required": required,
"additionalProperties": False}})
routes[name] = path # имя инструмента -> путь эндпоинта
return tools, routes
tools, routes = tools_from_spec({"getFundingSpread": "get_funding",
"getArbitrageSpotSpot": "get_spreads"},
plan="trial")
Из getFundingSpread выйдет инструмент get_funding с параметрами coin и min_spread. Если передать все операции, на Trial останется 11 из 37, на Start — 16. Словарь routes хранит путь каждого инструмента.
MCP: свой сервер поверх REST API
MCP (Model Context Protocol) — открытый стандарт подключения ИИ-приложений к данным и инструментам. Anthropic открыла протокол 25 ноября 2024 года (анонс Anthropic), а 9 декабря 2025 года передала его в Agentic AI Foundation — фонд в составе Linux Foundation (блог MCP).
Приложение с моделью — хост — создаёт по MCP-клиенту на каждый сервер. Сервер отдаёт инструменты, ресурсы и шаблоны промптов по JSON-RPC 2.0: локальный — через stdio, удалённый — через Streamable HTTP, токены для которого MCP рекомендует получать по OAuth (архитектура MCP).
| Вызов функций | MCP | |
|---|---|---|
| Где описаны инструменты | В запросе к API модели | На сервере, клиент берёт их через tools/list |
| Кто выполняет вызов | Код вашего приложения | MCP-сервер по запросу tools/call |
| Где работает | В приложении, где написан цикл | В любом клиенте с поддержкой MCP |
Обёртка REST API в MCP-сервер — четыре шага:
Выберите операции
Возьмите 3–7 операций под задачу агента; имена, описания и параметры соберите из OpenAPI, как в скрипте выше.
Отдайте список на tools/list
Сервер возвращает
name,descriptionиinputSchemaкаждого инструмента.Выполняйте tools/call
Проверьте аргументы, сделайте GET с ключом из окружения сервера и верните компактный JSON в блоке
content. Ошибку API верните сisError: true: по ней модель поправит аргументы.Выберите транспорт
Через stdio сервер работает на вашей машине, и ключ её не покидает. Удалённый сервер на Streamable HTTP закройте авторизацией, иначе вашей квотой воспользуется любой, кто узнает адрес.
Официальные SDK MCP есть для 10 языков, от Python и TypeScript до Go и Rust (список SDK).
llms.txt и llms-full.txt
llms.txt — Markdown-файл по адресу /llms.txt, который помогает языковым моделям пользоваться сайтом. Формат предложил Джереми Ховард (Jeremy Howard) 3 сентября 2024 года (llmstxt.org): обязателен только заголовок H1, за ним идут цитата с кратким описанием и разделы со ссылками на Markdown-версии страниц.
Файла llms-full.txt в предложении нет: так называют всю документацию одним Markdown-файлом, его публикует, например, сайт документации MCP. Модели не нужно ходить по ссылкам: справочник целиком попадает в контекст.
Безопасность агента
Ключ держите в переменной окружения сервера: в промпте, браузере и журналах его быть не должно. Ключ Genesis API даёт только чтение — ордер не поставить, денег не вывести, утечка грозит расходом квоты. Утёкший ключ замените кнопкой Перевыпустить в профиле (хранение ключа).
Промпт-инъекция (prompt injection) — команда для модели, спрятанная в данных. Имя токена задаёт тот, кто его выпустил, имя трейдера — сам трейдер, и там может прийти «забудь прошлые инструкции». В Genesis API внешний текст приходит в полях title и outcome рынков предсказаний, name трейдеров, token_name ончейн-событий и message_ru, message_en сигналов Genesis AI+: пропишите в системном промпте, что результаты инструментов — только данные.
Спецификация MCP требует от сервера проверять входные данные, ограничивать частоту вызовов и очищать результаты, а клиенту советует подтверждать чувствительные операции и вести журнал (инструменты MCP). В журнал пишите X-Request-Id: по нему, времени UTC, эндпоинту и статусу поддержка найдёт запрос.
Риски автоматизации разобраны в пятом уроке курса «API криптовалют».
Расходы и лимиты
Квоту Genesis API тратит только ответ 200; 304 и ошибки бесплатны, но входят в лимит запросов в секунду. Сверх лимитов сервер отвечает 429 и денег не списывает.
| Тариф | Цена | Квота и лимит | Свежесть |
|---|---|---|---|
| Trial | $20 в месяц | 500 тыс. вызовов, 1 запрос/с | 60 с |
| Start | $50 в месяц | 2 млн вызовов, 2 запроса/с | 30 с |
| Pro | $100 в месяц | 5 млн вызовов, 5 запросов/с | 10 с |
| Max | $200 в месяц | 10 млн вызовов, 15 запросов/с | 5 с |
Условный пример: 500 вопросов в день по 3 вызова инструментов — это 500 × 3 = 1 500 вызовов в день и 1 500 × 30 = 45 000 за 30 дней, 9 % квоты Trial. Повторы с теми же параметрами в пределах freshness_sec закроет кеш, а предел вызовов на один ответ не даст циклу съесть квоту.
Опрос чаще meta.freshness_sec нового снимка не даст. Экономный опрос с ETag и повторами разобран в статье «Как опрашивать API без лимитов», лимиты — в инструкции «Лимиты Genesis API». Если агенту хватает правил без модели, проще бот для арбитража на Python.
Genesis API для ИИ-агентов
Genesis API — REST API с данными Genesis Arbitrage: спреды CEX и DEX, стаканы, фандинг, открытый интерес, кроссчейн, ончейн-потоки, рынки предсказаний, букмекерские вилки и AI-сигналы. Запросы — HTTP GET с заголовком X-API-Key, ответ — JSON с data и meta (формат ответа), SDK не нужен.
Для агентов опубликованы:
openapi.json— OpenAPI 3.1: 37 операций, схемы ответов и тарифы вx-genesis-plans;llms-full.txt— полный справочник одним Markdown-файлом;llms.txt— обзор сайта для языковых моделей;/.well-known/api-catalog— каталог по RFC 9727 со ссылками на спецификацию, документацию и статус.
Официального MCP-сервера, WebSocket и торговых эндпоинтов нет: агент читает данные, сделки остаются за человеком. Подключение по шагам — в инструкции «Genesis API для ИИ-агентов».
Вопросы и ответы
Может ли ИИ-агент торговать криптовалютой сам?
Только если дать ему торговый API биржи, и это ваш код и ваш риск. Через Genesis API нет: он только читает данные. Спецификация MCP советует, чтобы человек всегда мог отклонить вызов инструмента; для сделок это правило: каждый ордер подтверждает человек.
Какой тариф Genesis API нужен ИИ-агенту?
Для спредов CEX, фандинга и открытого интереса хватит Trial за $20 в месяц. Start добавляет акции, ончейн-разделы и арбитраж прогнозов в режимах exact и dutch, Pro и Max — всё, включая DEX и стаканы. Скорость задают лимит запросов в секунду и свежесть тарифа; состав тарифов — на странице «Тарифы Genesis API».
Где взять спецификацию Genesis API для агента?
OpenAPI 3.1 — по адресу genesisarbitrage.com/openapi.json, справочник для модели — genesisarbitrage.com/llms-full.txt. Агент найдёт оба файла и сам через каталог /.well-known/api-catalog.
Есть ли у Genesis API MCP-сервер?
Официального нет. Свой собирают из тех же обработчиков: инструмент MCP — GET-запрос к эндпоинту с ключом из окружения сервера. Минимальный пример на Python — в термине MCP.