Основы
Market Oracle — только источник рыночных данных. Он не открывает сделки и не управляет позициями. Между рынком и вашей стратегией — единый подготовленный слой: закрытые бары, индикаторы, факты стакана, макро-контекст и режим рынка.
closed: true). Каждый сигнал обрабатывается один раз, дедупликация по ключу symbol:ts.- Канонические свечи — спот USDT. Сверка mid —
GET /v1/quotes. CVD и минутный стакан смотрите по/health.cvd.status. - Один вызов
GET /v1/context/{symbol}отдаёт готовый снимок для решения вместо 8–10 запросов. - Live-уведомления о закрытых барах приходят через WebSocket (
wss://…/v1/stream), сами данные — через REST. HTTP-вебхуки не поддерживаются: нет входящегоPOSTна ваш URL. Держите сокет и reconnect с backoff (см. примеры). Без WS — опросGET /v1/latestраз в 30–60 с. - Цены и индикаторы в JSON — decimal-строки (без ошибок float). Для расчётов денег используйте decimal-библиотеку, в
numberпереводите только для графиков.
Быстрый старт
Пять минут до первого осмысленного ответа API:
1. Health
Сервис доступен, данные свежие.
2. Тариф
Ваши лимиты: запросы в день, RPM, число WS.
3. Символы
Брать только пары с ready=true.
4. Stream
Подписаться на закрытые бары.
5. Context
Снимок для решения: раз в 60–90 с и перед входом.
6. Сигнал
Один разбор на один закрытый бар.
Подключение
Два канала, две роли. REST — запрос данных (снимки, история, календарь). WebSocket — уведомления о том, что закрылся очередной бар. Торговый цикл всегда один: WS будит → REST забирает данные → решение → пауза. Вебхуки (POST на ваш endpoint) Oracle не шлёт.
Адрес и ключ
Каждый запрос к /v1/* (кроме публичных /health и /v1/health) несёт заголовок:
GET /healthиGET /v1/health— публичные, ключ не нужен (один и тот же JSON).GET /metricsтоже публичный.- Для WebSocket ключ передаётся тем же заголовком
Authorization, а если библиотека не умеет в WS-заголовки — один раз в URL:wss://api.market-oracle.pro/v1/stream?token=mo_…. Поддержка TLS включена: всегда используйтеhttps://иwss://. - Дневную квоту смотрите в заголовках
X-Quota-*после любого REST или в JSONGET /v1/me. При HTTP429читайтеretry_after_msв теле. - Free-ключ с сайта — бессрочный. Basic / Pro — на месяц, продление после оплаты.
Что откуда приходит
| Нужно | Канал | Откуда |
|---|---|---|
| Момент «бар закрылся» | WebSocket | bar_close (бар + индикаторы 1m) |
| Всё для решения одним ответом | REST | GET /v1/context/{symbol} |
| Себестоимость сделки и «дорого / нормально» | REST | поля trade_cost / cost_risk в context (в WS их нет) |
| Старший таймфрейм live | REST | поле htf в context (m15/h1/h4/d1; в WS его нет) |
| История свечей и индикаторов | REST | GET /v1/history / POST /v1/history/batch |
| Свежий стакан для проверки входа | REST | GET /v1/depth/{symbol}?seconds=3 |
| Минутная история стакана | REST или WS | GET /v1/microstructure или событие microstructure_close |
| Календарь событий, макро, режим рынка | REST | /v1/calendar, /v1/macro, /v1/market-regime |
Диалог с WebSocket
/v1/history, и только потом продолжайте live.Готовность пары
Не каждая пара из списка пригодна для анализа. Проверяйте связку флагов — это три секунды, которые спасают от торговли по «тёплой» истории:
| Поле | Где | Смысл |
|---|---|---|
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 |
last_closed_ts | symbols, status | время последнего закрытого бара (мс UTC) |
ready ≠ indicators_ready. Для стратегий на EMA200 нужны оба. Не торгуйте пару с 15 свечами так же, как BTC с сутками истории.GET /v1/context/{symbol}
Главный endpoint для бота и агента: один ответ вместо 8–10 вызовов. Берите его раз в 60–90 с на активную пару и обязательно перед входом.
| Блок | Что это простыми словами |
|---|---|
bar + indicators | последний закрытый 1m-бар — сигнал минутной стратегии. Для 5m/15m/1h берите native history / htf. Поле может быть null |
ticker | цена сейчас и статистика 24h (для отображения и расчёта размера, не для сигнала) |
depth | свежий стакан: спред, перекос bid/ask, крупные уровни |
trade_cost / cost_risk | во сколько обойдётся сделка и не «съедят» ли комиссии стоп (tradable: false = не входить). Есть только здесь, в WS их нет |
htf | старшие бары live: m15/h1/h4/d1 с индикаторами. Полей m5/m30/w1 нет — их только через history |
data_quality + freshness | можно ли доверять снимку: score 0…100 и свежесть каждого компонента |
macro_event_soon | true = через <60 мин важное событие (FOMC/CPI) — лучше пауза |
derivatives + liquidations | funding, open interest, каскады ликвидаций — фильтр, а не сигнал |
macro_snapshot | Fear&Greed, доминация BTC, стейблы, индекс доллара, доходность 10Y |
cross_exchange | сверка mid; divergence_warning = не входить без проверки |
market_regime / volatility_regime | фон рынка: связь с BTC, волатильность, breadth |
context_scope="live_snapshot", historical_safe=false — это текущий снимок, а не исторические данные для бэктеста. В бэктест его подмешивать нельзя.Свои комиссии можно передать query-параметрами — тогда tradable посчитается под вашу модель издержек: ?fee_buy=0.001&fee_sell=0.001&slippage=0.0002&k_sl=2&rr=2&tradable_c_r_max=0.45. Бэктест и live должны использовать одни и те же комиссии, иначе оценка «дорого / нормально» разъедется.
Как читать trade_cost / cost_risk: комиссии + половина спреда + проскальзывание = c_spot (доля от сделки, 0.0025 = 0.25% туда-обратно). Это делится на стоп (k_sl × ATR) → c_r. Значение 0.45 значит, что издержки съедят почти полстопа; p_be — доля прибыльных сделок, чтобы выйти в ноль при заданном RR. tradable: false — пара сейчас слишком дорогая для вашего стопа: шире стоп или пропуск.
Пример ответа (сокращённый, структура 1-в-1)
Полный JSON на ~80 полей с разбором каждого блока — в agents.md §7. Ниже — скелет, который придёт на GET /v1/context/BTCUSDT:
score ≥ 70 + tradable: true + macro_event_soon: false = снимку можно доверять. Сигнал 1m — из bar (closed: true); старший ТФ — htf / history. depth для cost свеж только при freshness.depth.fresh (смотри max_age_sec в ответе).История и таймфреймы
Oracle сам ведёт нативные свечи старших таймфреймов — склеивать 5m/15m из минуток на клиенте не нужно (иначе потеряете ADX, VWAP, CVD, OBV, MFI).
| Interval | Глубина | Индикаторы |
|---|---|---|
1m | ~60 дней | да |
5m | 60 дней | да |
15m | 90 дней | да |
30m | 120 дней | да |
1h | ~9 месяцев | да |
4h | 2 года | да |
1d | 3 года | да |
1w | 5 лет | да |
- WS присылает закрытие только 1m. Цикл 15m-стратегии: дождаться последней минуты 15m-бакета по WS → взять
history?interval=15m&limit=1(илиcontext.htf.m15для live-фильтра) → торговать только закрытый бар с дедупом по ключу старшего бара. - Для бэктеста старший бар присоединяется строго as-of: последний бар с
ts <= decisionBar.ts. Копировать live-htfна прошлые бары нельзя. POST /v1/history/batchбезfromберёт последние 7 суток (неlimit × interval). Для глубокого HTF передавайтеfrom/to.POST /v1/sync/bootstrap— холодный дамп только 1m (до 10080 баров на пару; явный список — до 50 символов). Вызывать, только если пара не прогрета; mid/HTF подтягивает фоновый sync.- Историю кэшируйте минимум на 5 минут — не дёргайте её каждую минуту.
limitпо умолчанию 1000 (макс. 10080).
Стакан: live и история
Две разные сущности — не путайте:
GET /v1/depth (live) | Microstructure (история) | |
|---|---|---|
| Что | текущий top-20, окно до 10 секунд | закрытая UTC-минута: spread, imbalance, стены, pressure |
| Зачем | проверка входа через 1–2 с после сигнала | бэктест и стаканные фильтры на истории |
| Где | только текущее окно, без истории | история + WS-событие microstructure_close |
| Вызов | /v1/depth/BTCUSDT?seconds=3 | /v1/microstructure/BTCUSDT / /latest |
sample_count ≥ 40, coverage_pct ≥ 66.7, quality.score ≥ 70, microstructure.ts == bar.ts, closed == true. Live-depth — это фильтр исполнения, он не меняет исторический сигнал закрытого бара.failover: true свечи могут оставаться валидными, но минутная microstructure может не писаться, а cvd.status стать down. Стаканным и CVD-стратегиям мало общего верхнего status (он бывает ok или degraded): проверяйте bars.status (свечи) и cvd.status (поток) в GET /health.Индикаторы
Один и тот же набор на 1m и на всех старших ТФ после прогрева. Во время прогрева отдельные поля — null (не подставляйте 0). Каждый индикатор ниже — это готовый вход для бота, сигнализатора или скринера: тренд, сила, импульс, волатильность, объём, якорь цены, качество свечи, уровни.
| Группа | Ключи | Что показывает и как применять |
|---|---|---|
| Тренд | ema20 / ema50 / ema200, ema50_slope_pct | Направление и скорость. Цена выше EMA200 — бычий фон; кросс ema20/ema50 — импульс; |slope| ≤ 0.1 — флет для сетки |
| Сила и направление | adx14, plus_di14 / minus_di14 / di_side | ADX — только сила (флет ≤25, тренд ≥30), DI — сторона (строки "1"/"-1"/"0"). Фильтр: трендовый бот только при ADX ≥ 25 |
| Импульс | rsi14, mfi14 | Перегрев 0–100 (>70 перекуплен, <30 перепродан). MFI — второй голос с объёмом. Не контртренд по одному RSI в тренде |
| Волатильность | atr14 / atr_pct, atr50 / atr_ratio_14_50, bb_mid / bb_upper / bb_lower / bb_width | Стоп = k×ATR; ratio <0.8 — squeeze (копится энергия), >1.2 — разгон; BB-width — squeeze-метр для пробоя |
| Объём и поток | vol_sma20, volume_usd / volume_rate, obv, cvd_delta | Вход подтверждать объёмом ≥1.5–2× нормы ($/мин сравним между ТФ). Накопительный CVD — сумма cvd_delta на клиенте; валиден только при cvd.status == ok |
| Якорь цены | vwap | Дневной VWAP (сброс 00:00 UTC): выше — день за покупателями. На 1w это не недельный VWAP |
| Форма свечи | body, wick_balance, close_pos, candle_q, range_ratio | Качество бара одним числом candle_q; close_pos > 0.7 — сильный лонг-бар; range_ratio << 1 — шум, пропускать |
| Уровни | swing_high / swing_low, last_swing_* | Фракталы strength=2 с лагом 2 бара: стопы за экстремум, цели, пробойные входы. swing_* — только на баре подтверждения |
Готовность ядра: indicators_ready = есть ema20+rsi14+atr14. Остальное подтягивается позже: ADX/DI примерно после 27 баров, EMA200 — после 200 баров этого интервала, Bollinger — после 20. Полный разбор каждого ключа (формула, пороги, применение в боте, ловушки) — в agents.md. Чего в Oracle нет и не будет: MACD, Stochastic, Supertrend, Ichimoku — это логика вашей стратегии.
Как комбинировать поля
Данные Oracle — входы, не готовый «покупай/продавай». Три рабочих связки для бота, сигнализатора и скринера:
Тренд + HTF
На bar_close 1m смотрите context.htf.h1: цена выше ema50, adx14 ≥ 25 и di_side == "1" — на младшем ТФ только лонги. Ниже EMA200 H1 — лонги только с пробойным подтверждением. Убирает входы против старшего тренда.
Mean-reversion
На своём ТФ: rsi14 вышел из зоны (>70 вниз или <30 вверх), цена вернулась к bb_mid / vwap, volume_rate не ниже нормы, tradable, до новостей >60 мин. Без quality-гейта такой сигнал пропускают.
Скринер + стакан
Раз в 5 мин сортируйте пары по volume_rate и atr_ratio_14_50 (squeeze + объём). На сигнале через 1–2 с — GET /v1/depth?seconds=3: спред в норме, imbalance в сторону входа, гейт microstructure. Нет — пропуск, да — лимит у стены.
cvd_delta по закрытым барам; бэктест — только history as-of, не live-context.Тарифы
Три клиентских тарифа: free, basic, pro. Цены — на сайте продажи ключей, здесь — лимиты, чтобы выбрать тариф под своего бота. Точные цифры вашего ключа всегда в GET /v1/me: если расходятся с таблицей — верьте /v1/me.
| Тариф | Запросов в день | RPM | Мин. пауза | Рек. пауза | Max WS | Кому |
|---|---|---|---|---|---|---|
free | 2 000 | 30 | 2000 мс | 2000 мс | 1 | знакомство с API, один бот |
basic | 5 000 | 60 | 200 мс | 1000 мс | 2 | live 24/7: 1–2 бота на ключ |
pro | 8 000 | 90 | 150 мс | 667 мс | 3 | live 24/7: до 3 ботов на одном ключе |
- 1 HTTP-запрос = 1 из дневного лимита — независимо от «тяжести» endpoint'а. Кадры WebSocket и служебные
/v1/me,/v1/symbols,/v1/meta/*,/v1/calendarлимит не тратят. - Два независимых тормоза на каждый REST: пауза
min_interval_msмежду любыми запросами и не большеrpmв скользящую минуту. Нарушение →429с паузойretry_after_ms. Не запускайте десятки запросов параллельно — очередь с паузой ≥ рек. значения. - Остаток дня парсите из
X-Quota-Remaining(после/v1/contextи т.д., отдельный запрос не нужен). Значениеunlimited— лимита нет;0— ждать unix-времяX-Quota-Reset(полночь UTC).X-Quota-Cost=1или0;X-Quota-Weight— нагрузка, не второй лимит. Не берите дневной остаток изX-RateLimit-*. - Несколько ботов на одном ключе делят одну REST-очередь, а WebSocket'ы у них независимые. Нужно больше процессов, чем Max WS, — берите второй ключ.
- Новые ключи с сайта по умолчанию —
freeбессрочно. Basic / Pro — месяц с продлением.
basic — context раз в 60–90 с на активную пару + обязательно перед входом; на free — ориентир раз в ~30 мин. latest для тикера — раз в 10–15 с, историю — с кэшем от 5 мин. Бот без WS, долбящий latest каждые 10 с, съедает ~8640 запросов в сутки — не влезет ни в один тариф: сначала переходите на WebSocket.Пример заголовков после платного GET /v1/context/BTCUSDT (имена без учёта регистра, в CORS проброшены):
GET /v1/me те же заголовки отдаёт, но дневную квоту не тратит. На 429 смотрите Retry-After и JSON retry_after_ms; на обычном 200 заголовка Retry-After нет. Полная таблица полей — в agents.md, раздел «Заголовки лимитов».
Все endpoint'ы
Служебные
| Метод | Путь | Описание |
|---|---|---|
| GET | /health | статус сервиса и свежесть баров (публичный) |
| GET | /v1/me | тариф ключа, остатки лимита, expires_at |
Символы и статус
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/symbols | активные пары + бары / ready / history |
| GET | /v1/status/{symbol} | lag, ready, индикаторы, quality одной пары |
| GET | /v1/meta/{symbol} | tick / step / minNotional для округления приказов |
История и синхронизация
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/history/{symbol} | ?interval=1m|5m|15m|30m|1h|4h|1d|1w, limit (до 10080), from/to в мс |
| POST | /v1/history/batch | до 20 пар за один запрос, тот же набор interval |
| POST | /v1/sync/bootstrap | холодный дамп только 1m (до 10080 баров на пару) |
| GET | /v1/latest?symbols= | последний закрытый бар + ticker (до 50 пар; ответ всегда через .symbols[ПАРА]) |
| GET | /v1/indicators/{symbol} | только индикаторы, только 1m (для старших ТФ — history) |
Срез рынка
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/context/{symbol} | полный снимок для решения |
| GET | /v1/depth/{symbol} | live top-20 (?seconds=0..10), фильтр исполнения |
| GET | /v1/derivatives/{symbol} | funding, OI, ликвидации |
| GET | /v1/calendar | макро-события: ?hours=, ?high_only=true, для бэктеста ?as_of=bar.ts&window_min=60 |
| GET | /v1/macro | Fear&Greed (+история ?fng_days=), доминация, стейблы, DXY/10Y |
| GET | /v1/quotes/{symbol} | сверка BBO |
| GET | /v1/market-regime | корреляции с BTC, волатильность, breadth рынка |
Microstructure
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/microstructure/{symbol} | закрытая минутная история стакана (interval=1m, до 10080) |
| GET | /v1/microstructure/{symbol}/latest | последняя закрытая минута |
Примеры кода
Два стартовых клиента — Python и Node.js. Адрес узла уже подставлен; остаётся ваш ключ mo_…. Язык переключается вкладками.
REST: первый запрос и гейт перед входом
WebSocket: слушать закрытые бары
Ошибки
Сначала смотрите HTTP-код ответа, затем машинное поле code (на ошибках равно status) в теле. Текст error не парсите.
| code / status | HTTP | Когда и что делать |
|---|---|---|
ok | 200 | успех |
key_missing / key_invalid / key_expired / key_revoked | 401 | проблема с ключом: остановить торговлю, запросить продление у оператора |
too_fast / rate_limited | 429 | слишком частые запросы: пауза retry_after_ms + jitter, дальше реже |
quota_exceeded | 429 | дневной лимит исчерпан: data-REST не ретраить до UTC midnight; WS и служебные endpoint'ы продолжают работать |
ws_limit | 429* | слишком много WS на ключ: смотреть поле code (поля status может не быть) |
unavailable | 503 | Oracle временно недоступен: backoff и повторить |
Полезные заголовки: дневной остаток — X-Quota-* (не X-RateLimit-*); на 429 — Retry-After и retry_after_ms в JSON. Неизвестный символ / кривой диапазон — 400, внутренняя ошибка — 5xx с ограниченным exponential backoff.
Чеклист для AI-агента / бота
GET /health→status == "ok"иbars.status == "ok"; для CVD-стратегий ещёcvd.status == "ok".GET /v1/me→ учесть тариф, остатки дня,rpm,min_interval_ms,expires_at.GET /v1/symbols→ толькоready == true, лучшеfull_day.- WS subscribe (для стакана —
microstructure: true); дедуп обоих событий поsymbol:ts. - На
bar_close— разбор один раз. Сигнал 5m/15m/1h — только по закрытому нативному бару своего ТФ. GET /v1/context/{symbol}по расписанию и перед входом; гейты:score ≥ 70,lag ≤ 120,cost_risk.tradable, безmacro_event_soonиdivergence_warning.- Через 1–2 с после сигнала — опционально
GET /v1/depth?seconds=3как фильтр исполнения. - После reconnect: пауза ≥ min_interval →
/v1/history(+ microstructure) → exact join поts. - Не считать EMA/RSI/ADX на клиенте, если Oracle уже отдал их в
bar.indicators. Не публикуйте ключmo_…в открытых репозиториях и фронтенде.