AI-доступ к данным TokenBel

Введение

Это руководство объясняет, как пользоваться открытым источником данных TokenBel в AI-клиентах. Он помогает получать справочную информацию по белорусским токенизированным бумагам, биржевым акциям и облигациям, компаниям и эмитентам, дивидендам, торговой статистике, показателям финансовой отчётности и курсам валют НБРБ.

Сервис предназначен только для чтения данных. Через него нельзя покупать бумаги, менять портфель, отправлять заявки, редактировать компании или обновлять справочники. Все запросы открыты и ничего не меняют в системе TokenBel.

Доступные действия

Действие Что возвращает Поиск биржевой бумаги по тикеру Список найденных акций и облигаций с тикером, типом бумаги, эмитентом, номиналом, валютой и признаком торгов сегодня. Поиск компании Список компаний по названию или УНП с типом записи, регистрационными данными и связью между эмитентом и компанией, если она известна. Карточка компании Подробные справочные данные одной компании: название, полное юридическое имя, УНП, отрасль, логотип, адрес и активность записи. Финансовые показатели компании Отчётные периоды компании или связанного эмитента с метриками баланса, капитала, активов, обязательств и рассчитанными финансовыми коэффициентами. Список токенов Подборку токенизированных корпоративных бумаг с платформой, статусом, ценой, ставкой, валютой, объёмом выпуска и данными компании. Карточка токена Подробные данные одного токена: платформа, статус, цена, ставка, объём, продажи, срок размещения и связанная компания. Статистика продаж токена Дневной ряд продаж токенов за период, итоговый объём продаж, число активных дней и текущий снимок выпуска. Список акций Подборку биржевых акций с тикером, эмитентом, видом акции, номиналом, валютой, лотом и признаком торгов сегодня. Карточка акции Подробные данные одной акции: тикер, эмитент, вид акции, номинал, валюта, лот, активность и дата допуска к торгам. Дивиденды и выплаты по акции Историю дивидендных событий по акции, даты решений и выплат, суммы на акцию, статусы событий и агрегированную сводку. Список облигаций Подборку биржевых облигаций с тикером, эмитентом, видом облигации, номиналом, валютой, ставкой, типом выплаты процентов и датой погашения. Карточка облигации Подробные данные одной облигации: тикер, эмитент, купонная ставка, порядок выплаты процентов, номинал, валюта, дата погашения и торговая активность. Торговая статистика акции или облигации Сводку торгов за последние 30 дней или выбранный период: оборот, сделки, цены, доходности и дневной ряд торгов. Курсы валют НБРБ Официальные курсы USD, EUR и RUB к BYN за дату, диапазон дат или сгруппированные недельные/месячные периоды.

Подключение сервиса

Источник данных подключается в совместимом AI-клиенте как удалённый сервер TokenBel Financial Data. Для подключения используется адрес:

https://mcp.tokenbel.info/mcp

После подключения AI-клиент может сам выбирать подходящее действие: найти бумагу, открыть карточку, показать список, получить статистику, посмотреть финансовые показатели или проверить курс валюты.

Что важно понимать

Доступ открытый: отдельный логин или ключ не нужен.
Данные только для чтения: запросы ничего не меняют в системе TokenBel.
Ответы возвращаются как данные: чаще всего AI-клиент показывает их в виде текста, таблицы или краткого объяснения.
Если сервис временно недоступен: повторите запрос позже или сузьте его, если он слишком общий.

Поиск бумаг и компаний

Поиск помогает начать работу, когда пользователь знает только тикер, название компании или УНП.

Поиск по тикеру

Поиск по тикеру относится к биржевым акциям и облигациям. Он подходит, если пользователь знает обозначение бумаги или его часть.

В результатах обычно видны:

тип найденной бумаги: акция или облигация;
тикер;
эмитент;
номинал и валюта;
признак, торговалась ли бумага сегодня;
дата допуска к торгам.

Токены в этом поиске не появляются, потому что у них нет биржевых тикеров.

Поиск по названию или УНП

Поиск по названию помогает найти компании и эмитентов. Это важно, потому что компания и эмитент ценной бумаги могут быть разными записями.

Каждый результат помечен типом, чтобы было понятно, что с ним делать дальше:

если результат относится к компании, по нему удобно смотреть общую справочную карточку или финансовые показатели;
если результат относится к эмитенту, его можно использовать, чтобы найти выпущенные им акции или облигации.

У эмитента может быть указана связанная компания — это помогает переходить от эмитента к справке об организации.

Токены

Раздел токенов показывает токенизированные корпоративные бумаги на финтех-платформах. Токены просматриваются через список, а не через тикер.

В списке можно ограничить выдачу по платформе и состоянию продажи или обращения.

Полезные фильтры

Платформа: помогает выбрать токены конкретной площадки — Fainex, Finstore, Bynex или Whitebird.
Статус: помогает отличить бумаги по этапу жизни:
- продажа ещё не началась;
- продажа идёт сейчас;
- продажа приостановлена;
- токены полностью распроданы;
- продажа завершена;
- обращение завершено;
- обязательства по токенам выполнены.
Лимит: ограничивает количество результатов в одном ответе.

Карточка токена

Карточка отдельного токена показывает название, платформу, текущий статус, ставку, цену, валюту, общее количество токенов, сколько уже продано, дату завершения эмиссии и связанную компанию.

Статистика продаж токена

Для токена можно посмотреть статистику первичных продаж за период. По умолчанию показываются последние 30 дней.

В статистике есть:

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

Даты можно задавать обеими границами. Если указать только начало, концом считается сегодняшний день. Если указать только конец, началом считается 30 дней до него.

Вторичные сделки (перепродажа токенов между владельцами) в этом источнике не учитываются — только первичные продажи.

Акции

Раздел акций помогает найти биржевые акции, посмотреть их справочные данные и историю дивидендов.

Список и карточка акции

Акции можно искать по тикеру или получать списком с фильтрами. В карточке акции обычно важны тикер, эмитент, вид акции (например, обычная или привилегированная), номинальная стоимость, валюта, размер лота, дата допуска к торгам и признак торгов сегодня.

Фильтр по эмитенту полезен, когда сначала найден эмитент по названию, а затем нужно посмотреть его акции.

Дивиденды и выплаты

Для акции доступна история дивидендов и сводка по выплатам.

Каждое событие выплаты может показывать:

период, за который принято решение (год, полугодие или квартал);
сумму на одну акцию;
дату решения;
дату фиксации владельцев;
дату выплаты;
источник значения;
статус события.

Статусы имеют такой смысл:

объявлено — выплата объявлена, ожидается или уже произведена в зависимости от дат;
без дивидендов — эмитент официально сообщил, что выплат по периоду не будет;
отменено — ранее объявленная выплата отозвана.

В сводке учитываются только объявленные выплаты. Если по периоду указано, что дивидендов не было, или выплата отменена, такие события остаются в истории, но не увеличивают денежные итоги.

Помимо общей суммы, сводка показывает минимальную, максимальную и среднюю выплату на акцию, а также даты первой и последней выплаты.

Показатель дивидендной доходности здесь рассчитывается как последняя объявленная выплата, отнесённая к номинальной стоимости акции. Его не следует читать как доходность к рыночной цене.

Облигации

Раздел облигаций помогает найти биржевые облигации и посмотреть их основные условия.

Облигации можно искать по тикеру или получать списком с фильтрами по эмитенту и признаку торгов сегодня.

В карточке облигации важны тикер, эмитент, вид облигации (например, корпоративная или государственная), текущая ставка (купон), тип выплат, дата погашения, номинал, валюта и признак торгов сегодня.

Отдельной истории купонных выплат в этом источнике нет. Для облигаций доступна торговая статистика, если по бумаге есть биржевые данные.

Компании и эмитенты

Раздел компаний помогает получить справочную информацию об организациях: название, полное название, УНП, отрасль, адрес, логотип и признак активной записи.

Важно различать компанию и эмитента. Компания описывает организацию в справочнике, а эмитент связан с биржевыми акциями и облигациями. Иногда они связаны между собой, но в поиске могут появляться отдельными строками.

Как выбирать результат

Если нужна справка об организации, выбирайте результат типа «компания».
Если нужно найти акции или облигации организации, выбирайте результат типа «эмитент» и используйте его для списка бумаг.
Если результаты похожи, сверяйте название, полное название и УНП.

Финансовые показатели компании

Для компании или эмитента можно посмотреть финансовые показатели за отчётные периоды. Это помогает сориентироваться в устойчивости и состоянии организации до того, как принимать решение по бумаге.

Запрос принимает как идентификатор компании, так и идентификатор эмитента — сервис сам определит, к какой организации они относятся.

Что показывается

Метрики отчётности за период: валюта баланса, собственный капитал, долгосрочные и краткосрочные активы и обязательства.
Расчётные коэффициенты: ликвидность, финансовая независимость, устойчивость, плечо финансового рычага, капитализация и обеспеченность собственными оборотными средствами.

Периоды выводятся от новых к старым. Можно ограничить количество периодов в ответе — по умолчанию их восемь.

Если по какому-то периоду нет расчётных коэффициентов, они для него просто не показываются, а метрики остаются.

Торговая статистика

Торговая статистика доступна для биржевых акций и облигаций. Она помогает понять, были ли сделки, как менялись цены и доходность и какой был оборот за период.

Есть два режима просмотра:

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

Даты нужно указывать обеими границами или не указывать вовсе. Только одна граница не принимается.

Дневной ряд

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

В итог за период входят количество торговых дней, общий оборот, число сделок и средневзвешенная цена.

Если выбран произвольный период, часть «последних» значений может быть пустой. Это нормальное ограничение такого режима.

Курсы валют

Раздел валют показывает официальные курсы НБРБ к белорусскому рублю. Доступны USD, EUR и RUB. Если валюту не выбирать, сервис вернёт все три.

Курс читается как количество BYN за 1 единицу иностранной валюты.

Варианты просмотра

Последние значения: если даты не указаны.
Одна дата: если нужно узнать курс на конкретный день.
Диапазон дат: если нужно получить ряд значений за период. Границы можно задавать частично — например, только начало периода.
По неделям или месяцам: если нужны средние, минимальные и максимальные значения за периоды.

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

Одна дата и диапазон дат несовместимы — их нельзя указывать одновременно.

Прямой доступ к карточкам и описаниям

Помимо обычных запросов, сервис предоставляет прямой доступ к карточкам объектов и их описаниям. AI-клиент использует это автоматически.

Карточка по идентификатору: токен, акция, облигация или компанию можно открыть напрямую по их идентификатору.
Описания объектов: для каждого типа данных есть краткое описание полей. AI-клиент может прочитать его заранее, чтобы точнее понимать, что означает каждое значение и какой запрос лучше сделать следующим.

Эти возможности дублируют обычные запросы и нужны в основном самому AI-клиенту, чтобы точнее работать с данными.

Списки и продолжение результатов

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

Если результатов много, попросите AI-клиент показать следующую часть или сузьте запрос фильтром.

Ошибки и пустые ответы

Если запрос не удаётся выполнить, сервис возвращает понятное сообщение об ошибке. Чаще всего это означает одну из следующих ситуаций:

Неверный идентификатор: проверьте, что выбран результат из поиска или списка.
Запись не найдена: бумага, компания или токен могут отсутствовать либо быть недоступными для этого запроса.
Неверный формат даты: используйте вид ГГГГ-ММ-ДД.
Неверный период: начальная дата не должна быть позже конечной.
Несовместимые параметры: например, одна дата и диапазон одновременно, или только одна граница периода для торговой статистики.
Слишком широкий запрос: уменьшите лимит, выберите валюту, платформу, статус или период.

Пустой список не всегда означает ошибку. Иногда это просто значит, что по выбранному фильтру или периоду данных нет.

Как блоки связаны

Лучше всего пользоваться сервисом по шагам: сначала найти объект, затем открыть его карточку, а после этого запросить связанные данные.

Такой порядок снижает риск ошибки: пользователь сначала получает правильный объект, а затем использует его для более точных запросов.

Краткий глоссарий

Токен — токенизированная корпоративная бумага на финтех-платформе, у которой нет биржевого тикера.
Акция — биржевая ценная бумага, по которой можно смотреть эмитента, номинал, торги и дивиденды.
Облигация — биржевая ценная бумага с условиями выплат и датой погашения.
Эмитент — организация, которая выпустила акцию или облигацию.
Тикер — короткое обозначение биржевой акции или облигации для поиска.
Дивиденды — выплаты владельцам акций за определённый период.
Финансовые коэффициенты — расчётные показатели устойчивости компании: ликвидность, независимость, плечо рычага и другие.
Курс НБРБ — официальный курс иностранной валюты к белорусскому рублю.