API Metrand

Стратегии, проверки и бэктесты из вашего кода, скриптов и ИИ-агентов: ключи, лимиты, все эндпоинты и все ошибки.

Пишите стратегию, проверяйте её, тестируйте на годах истории биржи и читайте каждую сделку — из кода, скрипта или ИИ-агента. Всё описанное здесь есть и в документе OpenAPI, который напрямую читают генераторы кода и ИИ-ассистенты, а сама эта страница в виде Markdown лежит по адресу metrand.com/docs/api.md?lang=ru.

Базовый адрес: https://metrand.com/api/v1

Ключи

Создайте ключ в приложении: Аккаунт → API-ключи. Он показывается один раз — храните его как пароль. Передавайте его в каждом запросе:

Authorization: Bearer mtr_AbCdEfGhIjKl_…

Ключ действует от вашего имени в вашем рабочем пространстве, в пределах своих прав:

Право Разрешает
read стратегии, версии, бэктесты, сделки, каталог операций, шаблоны и правила рынков
research проверку графов и запуск бэктестов, которые расходуют дневной лимит бэктестов
strategies:write создание стратегий и сохранение версий

Ключ можно ограничить IP-адресами и сроком действия. Отзыв останавливает его сразу; смена пароля отзывает все ваши ключи.

Лимиты

Все ключи рабочего пространства расходуют одни и те же лимиты его тарифа:

Тариф Запросов в минуту Бэктестов одновременно Бэктестов в очереди Бэктестов в день Баров в бэктесте
Free 60 1 10 20 5 000
Pro 300 2 50 200 20 000
Expert 1 200 4 200 2 000 50 000

Дневные бэктесты и самое длинное окно — лимиты тарифа, общие с приложением; тариф Enterprise с большими лимитами оформляется с нами напрямую. Каждый ответ сообщает, сколько осталось в этой минуте (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset), а отказ — когда приходить снова (Retry-After). GET /me показывает лимиты и расход за сегодня.

Соглашения

  • JSON на входе и выходе, тело запроса до 1 МБ.
  • Время — RFC 3339 в UTC (2025-01-31T00:00:00Z); на входе принимаются и миллисекунды эпохи.
  • Деньги, цены и количества — десятичные строки, поэтому по пути ничего не округляется.
  • Каждый объект называет себя в поле object.
  • Список — это {"object": "list", "data": [...], "next_cursor": ...}. Передайте next_cursor как cursor, чтобы получить следующую страницу того же списка; null — последняя страница. limit — от 1 до 100, по умолчанию 25; сделки — до 1 000. Справочные списки (/markets, /templates) приходят целиком, next_cursor у них всегда null.
  • В каждом ответе есть X-Request-Id; укажите его, если что-то выглядит не так.
  • Версия 1 только растёт. Могут появляться новые поля, эндпоинты и значения; ничего не переименовывается и не удаляется. Незнакомые поля пропускайте.

Быстрый старт

С curl:

KEY=mtr_…
API=https://metrand.com/api/v1

# 1. Start a strategy from a template (GET /templates lists them, with their graphs).
curl -s -X POST $API/strategies -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"name": "Momentum test", "template": "momentum"}'
# → {"object":"strategy","id":"…","version":{"hash":"9f2c…"},…}

# 2. Backtest it on two years of hourly BTCUSDT, waiting up to 20 s for the result.
curl -s -X POST $API/backtests -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -H 'Prefer: wait=20' -H 'Idempotency-Key: momentum-btc-2y' \
  -d '{"strategy": {"id": "…", "version": "9f2c…"},
       "market": {"exchange": "binance", "symbol": "BTCUSDT", "interval": "1h"},
       "window": {"start": "2023-10-01T00:00:00Z", "end": "2025-10-01T00:00:00Z"},
       "costs": {"taker_bps": 5, "slippage_bps": 2}}'
# → 201 with "status":"succeeded" and the result, or 202 with "status":"queued": read it again

# 3. Read the backtest, its trades and its equity curve.
curl -s $API/backtests/<id> -H "Authorization: Bearer $KEY"
curl -s "$API/backtests/<id>/trades?limit=500" -H "Authorization: Bearer $KEY"
curl -s "$API/backtests/<id>/equity?points=300" -H "Authorization: Bearer $KEY"

То же на Python — с ожиданием, когда упираемся в лимит:

import time, uuid, requests

API = "https://metrand.com/api/v1"
s = requests.Session()
s.headers["Authorization"] = "Bearer mtr_…"

def call(method, path, **kw):
    r = s.request(method, API + path, timeout=90, **kw)
    if r.status_code == 429:                       # a limit: wait as told, then try again
        time.sleep(int(r.headers.get("Retry-After", "5")))
        return call(method, path, **kw)
    if r.status_code >= 400:
        raise RuntimeError(r.json())               # problem details: code, detail, errors
    return r.json()

strategy = call("POST", "/strategies", json={"name": "Momentum test", "template": "momentum"},
                headers={"Idempotency-Key": str(uuid.uuid4())})
bt = call("POST", "/backtests", headers={"Prefer": "wait=20"}, json={
    "strategy": {"id": strategy["id"], "version": strategy["version"]["hash"]},
    "market": {"symbol": "BTCUSDT", "interval": "4h"},
    "window": {"bars": 3000},
})
while bt["status"] in ("queued", "running"):
    time.sleep(2)
    bt = call("GET", f"/backtests/{bt['id']}")

print(bt["status"], bt["result"]["report"]["net_pnl"] if bt["result"] else bt["error"])

Эндпоинты

Эндпоинт Право Что делает
GET /me любой ключ Ключ, его пользователь и рабочее пространство, лимиты тарифа и расход за сегодня.
GET /catalog read Все операции, которые может содержать граф стратегии: вид, параметры, порты.
GET /templates read Шаблоны, с которых можно начать стратегию, с их графами и последним замером.
GET /markets read Все USDT-перпетуалы, которые торгуются на бирже (?exchange=binance или bybit).
GET /markets/{exchange}/{symbol} read Таймфреймы, правила лота, ступени плеча и стандартные комиссии одного рынка.
GET /strategies read Стратегии рабочего пространства (?archived=true — архивные).
POST /strategies strategies:write Новая стратегия из шаблона или из графа.
GET /strategies/{id} read Одна стратегия и её последняя версия.
GET /strategies/{id}/versions read Версии стратегии, новые первыми.
POST /strategies/{id}/versions strategies:write Сохранить граф как версию; тот же граф возвращает уже существующую версию.
GET /strategies/{id}/versions/{hash} read Одна версия с графом.
POST /strategies/validate research Скомпилирует ли движок граф — без сохранения.
GET /backtests read Бэктесты, запущенные здесь и в приложении (?strategy=, ?version=, ?status=).
POST /backtests research Заказать бэктест.
GET /backtests/{id} read Один бэктест, завершённый или нет.
POST /backtests/{id}/cancel research Отменить бэктест в очереди; списание возвращается.
GET /backtests/{id}/trades read Сделки завершённого бэктеста в порядке закрытия.
GET /backtests/{id}/equity read Кривая капитала завершённого бэктеста.
GET /openapi.json не нужно Документ OpenAPI 3.1 со всем этим.

Поля каждого запроса и ответа описаны в документе OpenAPI. Пути указаны от базового адреса: GET /me — это https://metrand.com/api/v1/me.

Стратегии

Стратегия — это название и список неизменяемых версий. Версия — это граф, названный по хешу содержимого: повторное сохранение того же графа возвращает уже существующую версию (200), поэтому сохранять перед каждым бэктестом безопасно.

  • POST /strategies принимает name и либо template (ключ из GET /templates), либо граф в поле dsl.
  • POST /strategies/{id}/versions и POST /strategies/validate принимают граф в поле dsl.

Каталог операций (GET /catalog) перечисляет все узлы, которые может содержать граф. Формат объяснён в гайде «Графы стратегий», а целиком он собран в одном файле — пакете формата стратегии, который можно передать ИИ-ассистенту. Графам сложнее того, что собирает Конструктор приложения, нужен тариф с редактором графов (plan_required).

Бэктесты

Бэктест — это задача. POST /backtests проверяет запрос, списывает один бэктест и сразу отвечает.

Поле Значение
strategy id и version (хеш или его уникальное начало не короче 6 символов)
market exchange (binance или bybit, по умолчанию binance), symbol (из списка GET /markets; любой другой отклоняется до списания), interval (по умолчанию 1h)
window либо bars — последние бары, закрытые к этому моменту, либо start и end; не больше баров в бэктесте по тарифу
costs taker_bps, maker_bps, slippage_bps, start_equity, leverage; не заданное берётся стандартным для биржи
Ответ Значит
202 в очереди или выполняется: прочитайте снова или спросите с Prefer: wait=N (до 20 секунд)
201 принят и завершился за время ожидания; смотрите status: succeeded или failed
200 + Backtest-Reused: true у такого же бэктеста уже есть результат; ничего не списано
202 + Backtest-Reused: true такой же бэктест уже идёт; ничего не списано, тот же id

Prefer: wait=N держит ответ до N секунд, не больше 20, и сообщает об этом заголовком Preference-Applied: wait=N. Ожидающий запрос занимает рабочий процесс сервера, поэтому у рабочего пространства одновременно ждут не больше двух запросов: третий — или пришедший, когда на сервере ждут уже многие, — получает ответ сразу, 202 без Preference-Applied, и бэктест читают снова, как любой другой.

Такой же — это та же стратегия и версия, рынок, итоговое окно, издержки и релиз движка. Окно заканчивается последним баром, закрытым к end (к текущему моменту, если не задан), поэтому «последние 500 баров» считаются заново, как только закрывается новый бар.

Состояния: queued → running → succeeded, failed или canceled. Бэктест в очереди можно отменить, и списание вернётся. Бэктест, упавший не из-за запроса — история биржи или движок недоступны, — запускается повторно, а если снова не выходит, списание тоже возвращается (error.code: market_data_unavailable, service_unavailable). Если же движок отклонил стратегию (backtest_failed: граф не может торговать в таком виде), списание остаётся — движок выполнил работу.

В результате — отчёт движка, бары, на которых он посчитан (result.measured_on), издержки и происхождение (provenance.fingerprint, provenance.release).

  • /trades: сделки в порядке закрытия, за вычетом комиссий и фандинга, до 1 000 на странице.
  • /equity: кривая капитала, прореженная до points точек, от 10 до 5 000 (по умолчанию 500). Каждый участок сохраняет свой минимум и максимум, поэтому просадки не теряются; total_points — сколько точек было.

Как движок исполняет ордера внутри бара и чего он не моделирует — в гайде «Как считается бэктест».

Ошибки

Ошибки приходят как problem details (application/problem+json) со стабильным code, по которому удобно ветвиться:

{
  "type": "https://metrand.com/docs/api#quota_exceeded",
  "title": "Quota exceeded",
  "status": 429,
  "code": "quota_exceeded",
  "detail": "Daily backtest limit reached (200) — upgrade for more.",
  "request_id": "6f0c2c1e-…"
}

type ведёт на описание кода ниже. Отклонённое поле названо в errors — по его пути в запросе. За 503 ничего не списывается. 429 повторяйте после Retry-After, 5xx — с нарастающей паузой.

unauthenticated · 401

Ключ не передан. Передайте его как Authorization: Bearer mtr_….

invalid_api_key · 401

Ключ неизвестен, отозван или истёк. Создайте новый.

forbidden · 403

Пользователю ключа это нельзя — например, наблюдателю рабочего пространства нельзя в него писать.

insufficient_scope · 403

У ключа нет нужного права; оно названо в detail. Создайте ключ с этим правом.

plan_required · 403

Тариф рабочего пространства этого не включает — например, операцию редактора графов.

ip_not_allowed · 403

Ключ ограничен другими IP-адресами.

not_found · 404

В этом рабочем пространстве нет ничего с таким id, или у API нет такого пути.

method_not_allowed · 405

Этот путь не принимает такой метод.

conflict · 409

Состояние ресурса этого не позволяет — например, отмена уже идущего бэктеста.

idempotency_in_progress · 409

Первый запрос с этим Idempotency-Key ещё обрабатывается. Повторите чуть позже.

payload_too_large · 413

Тело запроса больше 1 МБ.

unsupported_media_type · 415

Отправляйте JSON с Content-Type: application/json.

validation_failed · 422

Поле отклонено: errors называет каждое по пути (market.symbol, window.start). Исправьте запрос — тот же запрос снова не пройдёт.

idempotency_key_reused · 422

Этот Idempotency-Key уже использован с другим запросом. Для нового запроса нужен новый ключ.

rate_limited · 429

Слишком много запросов за минуту. Подождите Retry-After секунд.

quota_exceeded · 429

Бэктесты на сегодня израсходованы. Они обновляются в 00:00 UTC.

too_many_jobs · 429

В очереди уже столько бэктестов, сколько позволяет тариф. Дождитесь, пока часть завершится.

internal_error · 500

Сбой на нашей стороне. Укажите request_id, когда напишете нам.

market_data_unavailable · 503

Историю биржи сейчас не удалось прочитать; ничего не списано. Повторите после Retry-After.

service_unavailable · 503

Нужный сервис недоступен; ничего не списано. Повторяйте с нарастающей паузой.

Безопасные повторы

Передавайте Idempotency-Key (любая строка до 255 символов, своя для каждого действия) с каждым POST, который что-то создаёт или меняет: стратегию, версию, бэктест, отмену. Если ответ потерялся, отправьте тот же запрос с тем же ключом: в течение 24 часов вернётся первый ответ (Idempotent-Replayed: true), и ничего не создастся и не спишется дважды. Тот же ключ с другим телом отклоняется (idempotency_key_reused). Запоминаются только успехи и отказы самого запроса; после любого другого ответа (лимит, конфликт, сбой) повтор выполняется заново.

Для ИИ-агентов

Агенту, который работает каждый день, стоит смотреть ежедневно, а менять редко: дневная или 4-часовая стратегия получает от одного до шести баров в день, и ежедневная подгонка под них подгоняет шум. Читайте рынок и результаты каждый день; новую версию предлагайте по фиксированному, более редкому графику и оставляйте её, только если она выигрывает на данных, на которых её не подгоняли. Храните все версии: они дешёвые, неизменяемые, а их бэктесты показывают, что уже пробовали. Ставьте Idempotency-Key на каждый POST и используйте Prefer: wait вместо частых опросов.

Чего пока нет в версии 1

Вебхуков о завершении бэктеста; сравнений, периодов, корзин и перебора параметров как задач; бумажных запусков; живой торговли; MCP-сервера для ИИ-ассистентов. Сырые свечи не отдаются: это данные бирж.