Genesis Arbitrage

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

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.jsonOpenAPI 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.

Как подключить

  1. Получите ключ и положите его на сервер

    Ключ gns_live_… выдаётся в профиле, в блоке Genesis API, и показывается один раз. Сохраните его в переменной окружения GENESIS_API_KEY на сервере, где работает агент. Хранение и перевыпуск разобраны в инструкции «API-ключ».

  2. Импортируйте спецификацию

    API-клиент или фреймворк агентов, который принимает OpenAPI, строит запросы и инструменты прямо из openapi.json: базовый адрес берёт из servers, заголовок ключа — из ApiKeyAuth. Как передаётся ключ, описано в разделе «Аутентификация».

  3. Оставьте нужные операции

    Описание каждого инструмента занимает место в контексте модели, а выбирать проще из нескольких. Оставьте операции под задачу и уберите те, которых нет в вашем тарифе по x-genesis-plans: они ответят 403 plan_restricted.

  4. Дайте модели справочник

    Если агент пишет код или отвечает на вопросы об API, добавьте в контекст llms-full.txt: там параметры, поля и примеры каждого эндпоинта, лимиты и коды ошибок.

  5. Проверьте ключ первым вызовом

    /account/usage вернёт тариф, использованную квоту, лимит запросов в секунду и свежесть данных.

Как модель вызывает Genesis API

Вызов функций (function calling) — механизм, в котором модель вместо текста возвращает имя инструмента и аргументы, а сам вызов выполняет ваш код. Цикл такой:

  1. Вместе с вопросом пользователя модель получает описания инструментов: имя, назначение и параметры в JSON Schema.
  2. Модель отвечает вызовом: get_spreads с аргументами {"coin": "TON", "min_spread": 0.5}.
  3. Ваш сервер проверяет аргументы, делает GET с заголовком X-API-Key и урезает ответ до нужных полей.
  4. Короткий 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 и возраст данных и просите называть время в ответе.