Документация API

Назначение

Market Oracle — только источник рыночных данных. Он не открывает сделки и не управляет позициями. Между биржами и клиентами — единый подготовленный слой: закрытые бары, индикаторы, стаканные факты, макро и режим рынка.

Главное правило: торговые решения — только по закрытому 1m-бару (closed: true, bar −1). Дедупликация сигнала: symbol:ts.

Канонические свечи: Binance Spot; Bybit — failover + независимый BBO; OKX — quote-only для consensus.
Один вызов GET /v1/context/{symbol} отдаёт снимок для решения.
Live-триггер: WS /v1/stream → событие bar_close.
Числа в JSON — decimal-строки (без float-ошибок).

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

1. Health

Проверить status=ok, Redis и WS-провайдер.

GET /health

2. Тариф

Лимиты daily / RPM / WS / expires_at.

GET /v1/me

3. Символы

Брать только ready=true.

GET /v1/symbols

4. Stream

Подписка на закрытые бары.

WS /v1/stream

5. Context

Снимок перед решением (60–90 с).

GET /v1/context/{symbol}

6. Сигнал

Один раз на закрытый бар.

dedupe symbol:ts

# Пример (подставьте свой BASE и ключ) curl.exe -s https://HOST/health curl.exe -s https://HOST/v1/me -H "Authorization: Bearer mo_…" curl.exe -s "https://HOST/v1/context/BTCUSDT" -H "Authorization: Bearer mo_…"

Авторизация

Для всех маршрутов /v1/* нужен заголовок:

Authorization: Bearer mo_…

GET /health и GET /metrics — публичные.
WebSocket: тот же Bearer или ?token=mo_… в URL.
Управление ключами (/v1/keys*) — только ORACLE_ADMIN_TOKEN.
Без expires_at при создании ключ живёт +30 дней (не бессрочный).

Готовность символа

Поле	Где	Смысл
`bars_1m` / `bar_count`	symbols, status	сколько 1m баров в Redis
`ready`	symbols, status, context	`true` при ≥ 200 баров (прогрев EMA200)
`history`	там же	`warming` / `ready` / `full_day` (≥1440)
`indicators_ready`	latest, status, context	есть базовый набор `ema20+rsi14+atr14`
`data_quality.score`	context, status	0…100; для входа требуйте ≥ 70
`lag_sec`	status, context	возраст закрытого бара; `>120` режет score до ≤69

Важно: ready ≠ indicators_ready. Для EMA200 нужны оба. Не торгуйте «тёплую» пару с 15 свечами как BTC с сутками истории.

GET /v1/context/{symbol}

Главный endpoint для бота/AI. Один ответ вместо 8–10 вызовов:

Блок	Для чего
`bar` + indicators	сигнал только по закрытому 1m
`ticker`	24h объём/изменение, best bid/ask
`depth`	spread, imbalance, стены (live-снимок)
`ready` / `history` / `lag_sec`	можно ли торговать пару
`macro_event_soon`	пауза перед FOMC/CPI (high impact <60 мин)
`derivatives` + liquidations	funding / OI / каскады
`macro_snapshot`	F&G, dominance, стейблы, DXY/10Y
`cross_exchange`	venue consensus, divergence
`market_regime`	corr к BTC, vol, breadth
`data_quality`	score + flags

Не входит в context (запрашивается отдельно): длинная история, календарь событий, live WS, /v1/meta, закрытая минутная microstructure-история.

Ограничение: context_scope="live_snapshot", historical_safe=false — это не point-in-time история для бэктеста.

WebSocket `/v1/stream`

ws(s)://HOST/v1/stream # или ws(s)://HOST/v1/stream?token=mo_…

После connect сервер шлёт {"type":"hello",…}
Клиент: {"op":"subscribe","symbols":["*"]} или список пар
Для стакана: "microstructure": true → доп. событие microstructure_close
Событие сигнала: {"type":"bar_close","symbol":"BTCUSDT","bar":{…},"interval":"1m"}
Ping: {"op":"ping"} → pong

Join bar_close и microstructure_close строго по symbol + ts, не по времени получения. Push по WS не списывает daily quota.

Тарифы и лимиты

Тариф	Запросов в день	RPM	Мин. пауза	Max WS
`free`	6 000	30	2 с (2000 мс)	1
`basic`	25 000	120	500 мс	2
`pro`	100 000	180	350 мс	3

Пауза между запросами ≈ 60 000 мс ÷ RPM (равномерный темп под минутный лимит). Тяжёлые endpoint'ы (context/history = вес 3) списывают больше из дневного лимита; /v1/me, /v1/symbols, /v1/meta/*, /v1/calendar — вес 0 по дню (RPM и пауза всё равно действуют). Push по WS не тратит дневной лимит.

При лимите: HTTP 429, заголовки X-RateLimit-*, Retry-After, X-Quota-*. Смотрите поле status/code в теле.

Практика: на basic — context раз в 60–90 с на активную пару; на free — реже (бюджет 6k/день). Не штормите параллельными десятками context.

Все endpoint'ы

Служебные

Метод	Путь	Описание
GET	`/health`, `/v1/health`	статус, Redis, active_provider, failover
GET	`/metrics`	Prometheus-текст
GET	`/v1/me`	тариф ключа, usage, weights, expires_at

Ключи (admin)

Метод	Путь	Описание
GET / POST	`/v1/keys`	список / создать (`name`, `tier`, `expires_at`)
PATCH / DELETE	`/v1/keys/{id}`	сменить tier/срок / отозвать

Символы и статус

Метод	Путь	Описание
GET	`/v1/symbols`	активные пары + bars / ready / history
POST	`/v1/symbols`	добавить пару → bootstrap + WS reload
DELETE	`/v1/symbols/{symbol}`	убрать из реестра
GET	`/v1/status/{symbol}`	lag, ready, indicators, quality
GET	`/v1/meta/{symbol}`	tick / step / minNotional

История и синхронизация

Метод	Путь	Описание
GET	`/v1/history/{symbol}`	`?interval=1m\|1h\|4h\|1d\|1w`, `limit`, `from`, `to`
POST	`/v1/history/batch`	до 20 пар; опционально `include_microstructure`
POST	`/v1/sync/bootstrap`	холодный дамп из Redis для клиента
GET	`/v1/latest?symbols=`	последний закрытый бар + ticker
GET	`/v1/indicators/{symbol}`	только индикаторы по истории

Interval	Глубина	Индикаторы
`1m`	21 день (live WS)	да
`1h`	~9 мес	нет (`null`)
`4h`	2 года	нет
`1d`	3 года	нет
`1w`	5 лет	нет

Срез рынка

Метод	Путь	Описание
GET	`/v1/context/{symbol}`	полный AI-снимок
GET	`/v1/depth/{symbol}`	live top-20 / recent seconds (execution filter)
GET	`/v1/derivatives/{symbol}`	funding, OI, ликвидации
GET	`/v1/calendar`	`?hours=`, `?high_only=true`
GET	`/v1/macro`	F&G (+history `?fng_days=`), dominance, стейблы, FRED
GET	`/v1/quotes/{symbol}`	BBO consensus Binance/Bybit/OKX
GET	`/v1/market-regime`	corr / vol / breadth из своих 1h

Microstructure

Метод	Путь	Описание
GET	`/v1/microstructure/{symbol}`	закрытая минутная история стакана
GET	`/v1/microstructure/{symbol}/latest`	последняя закрытая минута

Агрегация top-20 @ 1 Hz в UTC-минуту. Live depth в context и закрытая microstructure — разные сущности. Исторический depth с биржи задним числом не восстанавливается.

Индикаторы на 1m-баре

Инкрементальный расчёт, batch-reference тесты. Поля — decimal-строки; во время прогрева могут быть null.

ema20, ema50, ema200
rsi14, atr14, adx14 (Wilder seed)
vwap, obv, mfi14
cvd_delta — дельта бара (taker buy − sell); накопительный CVD — префикс-сумма на клиенте

Ошибки и статусы

status / code	HTTP	Когда
`ok`	200	успех
`key_missing` / `key_invalid` / `key_expired` / `key_revoked`	401	проблемы с ключом
`unauthorized`	401	неверный admin token
`rate_limited` / `quota_exceeded` / `too_fast` / `ws_limit`	429	лимиты тарифа
`unavailable`	503	auth/БД временно недоступны

Клиент: сначала смотрите status (или code), не парсите текст error. После 429 — sleep на retry_after_ms / Retry-After.

Чеклист для AI-агента / бота

GET /health → status == "ok", Redis ok, WS connected.
GET /v1/me → учесть tier, daily, RPM, min_interval_ms, expires_at.
GET /v1/symbols → фильтр ready == true (лучше full_day).
WS subscribe; для стакана — microstructure: true.
На bar_close — анализ один раз (дедуп symbol:ts).
Перед входом / по расписанию — GET /v1/context/{symbol}; gate: data_quality.score ≥ 70, ready, indicators_ready.
Опционально через 1–2 с после сигнала: GET /v1/depth/{symbol}?seconds=3 как execution-filter (не меняет исторический сигнал бара).
После reconnect: пауза ≥ min_interval → /v1/history (+ microstructure) → exact join.
Не хранить admin token в клиенте. Не публиковать mo_… в репозитории.

Источник истины в репозитории: docs/DOC.md, docs/AUTH.md, docs/agents.md. Эта страница — публичная выжимка той же спецификации.

Назначение

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

1. Health

2. Тариф

3. Символы

4. Stream

5. Context

6. Сигнал

Авторизация

Готовность символа

GET /v1/context/{symbol}

WebSocket /v1/stream

Тарифы и лимиты

Все endpoint'ы

Служебные

Ключи (admin)

Символы и статус

История и синхронизация

Срез рынка

Microstructure

Индикаторы на 1m-баре

Ошибки и статусы

Чеклист для AI-агента / бота

WebSocket `/v1/stream`