TradeAlmanac
Войти
Документы

Разработчикам

Как обратиться к данным TradeAlmanac программно: ключ, адреса, формат ответа.

Обновлено: 2 сентября 2026 года

У площадки два способа получить данные программно, и они не заменяют друг друга. Адреса, которыми пользуется сам сайт, открыты и не требуют ключа — их описание есть в интерактивной документации. Отдельный машинный контракт живёт по адресу /api/public/v1 и требует ключа: у него стабильный формат, предсказуемая форма ответа и суточная квота.

Ключ

Ключ выдаётся в личном кабинете любому, кто вошёл в продукт: подписка для этого не нужна. Секрет показывается один раз при создании — в базе хранится только его отпечаток, и восстановить строку нельзя. Потеряли — отзовите ключ и создайте новый. Условия, на которых можно пользоваться данными, описаны в отдельном документе.

  • Ключ работает только на чтение: любой метод, кроме GET, отвергается.
  • Ключ не открывает служебные разделы — прав у него нет вовсе, а не «мы их не выдали».
  • Превышение отвечает 429 с заголовком Retry-After, а не молчанием.

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

Тариф один и он бесплатный. Платного уровня доступа сегодня нет — не «скоро будет», а нет: обещать цену, которой не назначено, значит собирать заявки под то, чего не существует.

  • Цена — 0 ₽. Ключ выдаётся любому, кто вошёл в продукт.
  • Частота — 60 запросов в минуту на ключ, скользящее окно.
  • Суточная квота — 1000 запросов в сутки на ключ. Сутки — календарные по UTC.
  • Ключей на учётную запись — до 10 одновременно, отзыв в любой момент.
  • Размер страницы — до 200 записей за запрос, дальше — по курсору.
  • Отказ по лимиту — 429 и заголовок Retry-After с числом секунд до следующей попытки.

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

Запрос

Отбор бумаг: нефть и газ с дивидендной доходностью от 8 %
curl -H "Authorization: Bearer afk_…" \
  "https://tradealmanac.com/api/public/v1/screener?sector=oil-gas&dividend_yield_min=0.08&limit=20"
Календарь отсечек за период
curl -H "Authorization: Bearer afk_…" \
  "https://tradealmanac.com/api/public/v1/dividends?from=2026-09-01&to=2026-12-31&limit=50"

Ключ передаётся заголовком Authorization. Доходность задаётся долей, а не процентом: 0.08 — это 8 %, и это то же соглашение, что во внутреннем скринере. Выборка постраничная: параметр limit ограничен двумястами, а следующая страница берётся по cursor из ответа — смещением её брать нельзя, глубокая страница по смещению стоит базе всего, что она перепрыгнула.

Ответ

Форма ответа одинакова у всех адресов
{
  "data": [ … ],
  "disclaimer": "…",
  "source": "tradealmanac",
  "delay_minutes": 15
}

Одинаковая обёртка — то, чем контракт отличается от набора случайных ответов: разборщик пишется один раз. Отсутствующего значения не будет в ответе вовсе; нулём оно не подменяется никогда.

Что отдаётся

  • afgi и afgi/history — собственный индекс настроений и его история.
  • dividends — календарь отсечек, dividends/{ticker} — выплаты по бумаге со статусом объявления.
  • screener — отбор по уже посчитанным фундаментальным показателям.
  • versions — редакции договора с датами и списком того, что появилось в каждой.

Это собственные расчёты площадки. Рыночных данных бирж интерфейс не отдаёт: ни котировок, ни свечей, ни справочника инструментов — ни по российскому рынку, ни по мировым. Обещание касается данных, а не способа их передать: потокового соединения с ценами в договоре тоже нет.

Совместимость

Самоописание контракта: что доступно и какая версия действует
curl -H "Authorization: Bearer afk_…" "https://tradealmanac.com/api/public/v1/meta"

Адрес /meta отвечает машиночитаемо на вопросы «что здесь есть» и «что здесь не появится». Поле contract — версия договора, и она живёт отдельно от версии продукта: релизы выходят часто, обещание меняется редко. Ломающее изменение получит новый префикс, а не тихую правку /v1.

Редакции договора и что появилось в каждой
curl -H "Authorization: Bearer afk_…" "https://tradealmanac.com/api/public/v1/versions"

За редакцию можно закрепиться: пришлите её дату заголовком X-API-Version — сервер ответит тем же заголовком. Неизвестную дату он отвергнет кодом 400 со списком известных, а не подставит текущую молча: клиент, думающий, что закрепился, хуже клиента, знающего, что не вышло. Закрепление обещает, что адрес, отвечавший на названную дату, продолжит отвечать; воспроизведения прежнего поведения оно не обещает — расхождений между редакциями сегодня нет ни одного.

Описание контракта в формате OpenAPI — без ключа
curl "https://tradealmanac.com/api/public/v1/openapi.json"

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

Готовые клиенты

Клиенты для Python и TypeScript порождены из того же описания OpenAPI, которым отвечает контракт, — и потому не могут разойтись с сервером. Номер версии клиента равен дате договора: 2026.9.6 — это клиент договора от 6 сентября 2026 года. Зависимостей у обоих нет.

Python
pip install tradealmanac

from tradealmanac import TradeAlmanac
api = TradeAlmanac("afk_…")
print(api.dividends_by_ticker("SBER"))
print(api.screener(sector="oil-gas", dividend_yield_min=0.08, limit=20))
TypeScript и JavaScript
npm install tradealmanac

import { TradeAlmanac } from "tradealmanac";
const api = new TradeAlmanac("afk_…");
const dividends = await api.dividendsByTicker("SBER");

Вебхуки: события приходят сами

Опрашивать адрес по расписанию нужно не всегда. Правило из списка наблюдения умеет отправлять срабатывание на ваш адрес: в кабинете указывается адрес и форма тела — наш формат, бот Telegram, бот MAX, Slack или плоская строка для таблицы. Адрес обязан быть https и вести в публичную сеть; тело подписывается ключом, который показывается один раз.

Заголовки доставки
POST /ваш-адрес HTTP/1.1
Content-Type: application/json; charset=utf-8
X-TradeAlmanac-Event: alert.triggered
X-TradeAlmanac-Delivery: 0f2c…
X-TradeAlmanac-Timestamp: 1788700000
X-TradeAlmanac-Signature: sha256=9f86d081…

Подпись считается по строке «время.тело», а не по одному телу: так перехваченный запрос нельзя отправить повторно через сутки — время в подписи разойдётся с настоящим. Проверяйте и подпись, и свежесть отметки.

Проверка подписи на стороне получателя (Python)
import hmac, hashlib, time

def verify(secret: str, body: bytes, signature: str, timestamp: str) -> bool:
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False                      # старое сообщение: повтор перехваченного
    payload = timestamp.encode() + b"." + body
    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Таблицы: Google Sheets и Excel

Подписная ссылка отдаёт отбор, портфель или календарь без входа — по токену. Этого достаточно, чтобы таблица обновлялась сама, без программирования и без надстроек из магазина. Ссылка создаётся в кабинете, в разделе «Ссылки на данные».

Google Sheets: формула в ячейку A1
=IMPORTDATA("https://tradealmanac.com/api/v1/public/feeds/ВАШ_ТОКЕН.csv"; ";")
Excel: запрос Power Query
let
    Источник = Csv.Document(
        Web.Contents("https://tradealmanac.com/api/v1/public/feeds/ВАШ_ТОКЕН.csv"),
        [Delimiter=";", Encoding=65001, QuoteStyle=QuoteStyle.Csv]
    ),
    Заголовки = Table.PromoteHeaders(Источник, [PromoteAllScalars=true])
in
    Заголовки

Частота обновления ограничена по токену — шестьдесят обращений в час. Google Sheets обновляет IMPORTDATA примерно раз в час сам; Excel — по кнопке или по расписанию, которое вы зададите.

ИИ-агенты: сервер MCP

Те же данные доступны агентным средам — Claude Desktop, Cursor, Claude Code — через сервер MCP. Это обёртка над этим же договором: ваш ключ, ваша квота, никакой дополнительной нагрузки. Установка, готовые конфиги и сценарии — на странице «Подключение к ИИ-агентам».

Установка и проверка ключа
pip install tradealmanac-mcp

TRADEALMANAC_API_KEY=afk_… tradealmanac-mcp --check

Вопросы о доступе и просьбы о повышенных лимитах — через контакты.

Разработчикам — TradeAlmanac