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-сервера для ИИ-ассистентов. Сырые свечи не отдаются: это данные бирж.