# API Metrand

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

Пишите стратегию, проверяйте её, тестируйте на годах истории биржи и читайте каждую сделку — из кода, скрипта или
ИИ-агента. Всё описанное здесь есть и в [документе OpenAPI](https://metrand.com/api/v1/openapi.json), который напрямую
читают генераторы кода и ИИ-ассистенты, а сама эта страница в виде Markdown лежит по адресу
[metrand.com/docs/api.md?lang=ru](https://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:

```bash
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 — с ожиданием, когда упираемся в лимит:

```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](https://metrand.com/api/v1/openapi.json). Пути указаны от
базового адреса: `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`) перечисляет все узлы, которые может содержать граф. Формат объяснён в гайде
[«Графы стратегий»](https://metrand.com/guides/strategy-graphs?lang=ru), а целиком он собран в одном файле —
[пакете формата стратегии](https://metrand.com/api/guides/strategy-format.md), который можно передать ИИ-ассистенту.
Графам сложнее того, что собирает Конструктор приложения, нужен тариф с редактором графов (`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` — сколько точек было.

Как движок исполняет ордера внутри бара и чего он не моделирует — в гайде
[«Как считается бэктест»](https://metrand.com/guides/how-backtests-work?lang=ru).

## Ошибки

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

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