Один ключ, один базовый URL, четыре формата доставки

Всё, что публикует Foreline, доступно по HTTPS с https://api.foreline.io и одним заголовком. Эта страница доводит вас до первого ответа; референс описывает каждый эндпоинт, параметр и поле.

Референс API → Самостоятельной регистрации нет: ключи выдаются по контракту. Напишите — сделаем тестовый.

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

От ключа до полной лестницы за три вызова

Быстрый старт Аутентификация Каденс и опрос Форматы доставки Эндпоинты по продуктам Ошибки Проверяемость Полный референс

Убедитесь, что вы аутентифицированы GET /v1/health — самый дешёвый вызов в API: подтверждает ключ, часы и состояние сервиса.

Прочитайте одно событие целиком GET /v1/surface?event_id=… возвращает главную линию, честную цену, измеренную маржу и каждую ступень лестницы с полосой.

Держитесь в синхроне GET /v1/surface?since=… возвращает всё, что изменилось с вашего курсора, и отдаёт next_since для следующего вызова. Это весь цикл — никакого состояния пагинации на вашей стороне.

# 1 — здоровье
curl -s "https://api.foreline.io/v1/health" \
  -H "X-Foreline-Key: $FORELINE_KEY"

{ "status": "ok", "server_ts": "2026-07-24T18:41:07Z", "version": "v1" }

# 2 — одно событие, полная лестница
curl -s "https://api.foreline.io/v1/surface?event_id=EVT_8F3A21" \
  -H "X-Foreline-Key: $FORELINE_KEY"

# 3 — bulk-дельта, дальше повторять с полученным next_since
curl -s "https://api.foreline.io/v1/surface?since=2026-07-24T18:40:00Z" \
  -H "X-Foreline-Key: $FORELINE_KEY"

Значения во всех примерах документации иллюстративные.

Аутентификация

Один заголовок, один ключ на окружение

Заголовок: X-Foreline-Key: <ваш ключ> в каждом запросе, включая SSE-стрим. Никаких OAuth-плясок и обмена токенов.
Транспорт: только HTTPS. Запросы без заголовка или с отозванным ключом возвращают 401.
Область ключа: ключ несёт продукты, виды спорта и глубину истории из вашего контракта. Вызов за пределы этой области возвращает 403, а не пустой результат: вы всегда отличите «не разрешено» от «здесь ничего нет».
Потребление: GET /v1/usage показывает расход против квот rpm и rpd на ключе — можно алертить на собственный запас, а не узнавать о нём из 429.

Каденс и опрос

Данные меняются раз в минуту — лимиты выстроены вокруг этого

Наши лимиты — не способ монетизации, а следствие того, как часто на самом деле меняются данные. Опрос чаще каденса вернёт те же байты с тем же updated_ts.

До стартового свистка	Каденс обновления	`data_cadence_s`
Меньше 24 ч	раз в 60 секунд	`60`
24–96 ч	раз в 5 минут	`300`
Дальше 96 ч	раз в 15 минут	`900`

В каждом ответе есть data_cadence_s — интервал, который действует для этого объекта прямо сейчас. Планируйте следующий вызов по этому полю, и ваш поллер останется корректным при переходе события через границу каденса, без отслеживания времени начала матчей.

Класс вызова	Лимит	Эндпоинты	Почему
bulk	4 / мин	`GET /v1/surface?since=`	Дельта полных поверхностей — тяжёлый объект; четыре прохода в минуту уже обгоняют 60-секундный каденс.
point	60 / мин	`/v1/surface` (сводка, событие, asof), `POST /v1/score`	Рассчитано на интерактив — трейдерский экран, риск-проверка в момент приёма ставки.
events	12 / мин	`/v1/line-events`, `/v1/alerts`	Догоняющий опрос. Для живой доставки берите SSE-стрим или вебхук, а не учащайте опрос.

Квоты — на клиента: потолок rpm (запросов в минуту) и rpd (запросов в сутки) на ключе, поверх классовых лимитов выше. Оба видны в GET /v1/usage. Превышение любого возвращает 429 с заголовком Retry-After — если его уважать, дальнейшего троттлинга не будет.

Форматы доставки

Четыре способа получить одни и те же факты

Большинство интеграций использует два: bulk-дельту, чтобы держать локальную копию тёплой, и стрим или вебхук — для моментов, которые действительно важны.

Точечное чтение

Один объект — сейчас или на прошлый момент времени: GET /v1/surface?event_id= и ?asof=. Для экранов, для риск-проверки при приёме ставки и для разбора спора о том, что и когда было опубликовано.

Bulk-дельта

Всё, что изменилось с вашего курсора, полными поверхностями: GET /v1/surface?since= и next_since в ответе. Основа локальной копии — логика диффов на вашей стороне не нужна.

Server-sent events

Удерживаемое соединение GET /v1/stream, отдающее event: line_change по мере обнаружения смен главной линии. При переподключении доберите пропуск через /v1/line-events?since= — перезапуск ничего не теряет.

Вебхук

Push-доставка алертов и событий линий на ваш эндпоинт, подписанная X-Foreline-Signature: sha256=… — HMAC по сырому телу с вашим общим секретом. Проверяйте до того, как действовать.

Эндпоинты по продуктам

Какой вызов какой продукт обслуживает

Продукт	Эндпоинты	Страница
Поверхность цен	`GET /v1/surface` — сводка, `?event_id=`, `?asof=`, `?since=`	Поверхность цен
Радар игроков	`POST /v1/score`	Радар игроков
Радар линий	`GET /v1/line-events`, `GET /v1/stream`, `GET /v1/alerts`, вебхук	Радар линий
Защита экспрессов	Маргиналы из `GET /v1/surface`; совместный прайсинг — сначала аудитом, затем фидом в объёме по контракту	Защита экспрессов
Все	`GET /v1/health`, `GET /v1/usage`	Референс

Ошибки

Три статуса, которые стоит обрабатывать

Статус	Значение	Что делать
`401`	Ключ отсутствует, повреждён или отозван	Починить заголовок. Ретраи не помогут.
`403`	Аутентификация прошла, но вызов вне области вашего контракта — вид спорта, продукт или глубина истории, которых у вас нет	Считать окончательным ответом для этого вызова; если область не та — напишите нам.
`429`	Превышен классовый лимит или квота аккаунта	Подождать `Retry-After` (в секундах) и продолжить. Не нужно отступать вслепую — заголовок называет точное время.

Полный референс ошибок →

Проверяемость

Проверьте данные до того, как их интегрировать

Слой доказательств публичен и не требует ни ключа, ни NDA — запись можно проверить, не написав ни строчки клиентского кода.

Хеш-цепочка и Merkle-коммиты. Каждая опубликованная строка в цепочке, каждый проход зафиксирован, дневные корни ежедневно якорятся в Биткоине через OpenTimestamps. Строки нельзя отредактировать или выборочно выбросить задним числом.
Публичный верификатор: github.com/foreline-io/foreline-proofs — python3 verify.py проверяет дневные корни, цепочку коммитов и биткоин-штампы.
Защита от подмены — с 23 июля 2026. История as-of уходит глубже: футбол с 2022 года; строки старше реестра отдаются как архив и помечены именно так.

Перейти к референсу API →

Доступ

Запросить тестовый ключ

Ключи выдаются по контракту — напишите, какие продукты, виды спорта и глубина истории вам нужны, и мы соберём область.

Напишите нам

contact@foreline.io

Обычно отвечаем в течение одного рабочего дня. Цены считаем под объём — напишите, и пришлём условия.

Запросить доступ