API для агентов

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

Эндпойнт

POST /api/agent/search?q=<запрос>&limit=<n>&lang=<код>&kind=<тип>&min_users=<n>&max_users=<n>

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

Параметр	Обязательный	По умолчанию	Значение
`q`	да	—	Запрос. Ищем по смыслу, а не только по названию; `@username` вернёт этот канал и ближайшие к нему.
`limit`	нет	100	Сколько результатов нужно, от 1 до 1000. Больше 1000 обрезается — и оплачивается по обрезанному числу.
`lang`	нет	—	Код ISO 639-1, например `en`, `ru`.
`kind`	нет	—	`channel`, `group` или `bot`.
`min_users`	нет	—	Нижняя граница числа подписчиков или участников.
`max_users`	нет	—	Верхняя граница.

Оплата за запрос

Оплата идёт по протоколу x402 — HTTP 402, без ключей и без подписки.

Отправьте запрос без платёжного заголовка.
В ответ придёт 402 Payment Required и заголовок Payment-Required: base64 от JSON, в котором получатель, токен, сумма и сети, которые мы принимаем.
Подпишите платёж по одному из вариантов и повторите запрос с заголовком Payment-Signature. Авторизация действует пять минут.
При 200 платёж проводится в сети. При любой ошибке не списывается ничего.

Клиентская библиотека x402 делает все четыре шага за вас: x402-fetch для JavaScript, x402-reqwest для Rust.

Цена — по тарифу за каждую сотню запрошенных результатов, с округлением вверх, минимум один: ceil(limit / 100) × базовая цена, в USDC, в сетях Base и Solana. Базовую сумму называет сам 402, а не эта страница, чтобы агент читал ровно ту сумму, которую с него спишут. Она же есть в /.well-known/x402 и openapi.json — оба документа читаются бесплатно.

Ответ

200, application/json, массив в порядке ранжирования — тот же вид, что и у /api/search. Пустой результат — это [], а не null. Поля, в которых ничего нет, не отдаются вовсе.

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "kind": "channel",
    "username": "example_channel",
    "name": "Example Channel",
    "description": "An example Telegram channel",
    "avatar_url": "https://semagram.io/avatar/example_channel.jpg",
    "user_count": 15000
  }
]

Поле	Тип	Значение
`uuid`	string	Постоянный идентификатор. Переживает переименование, в отличие от `username`.
`kind`	string?	`channel`, `group` или `bot`.
`username`	string	Юзернейм в Telegram, без `@`.
`name`	string?	Отображаемое имя.
`bio`	string?	Краткое описание.
`description`	string?	Полное описание.
`avatar_url`	string?	Аватарка. Её раздаём мы, а не Telegram.
`user_count`	number?	Подписчики или участники на момент последнего обхода.

Ошибки

Код	Что означает
`400`	`q` отсутствует или пуст, либо `kind` не один из трёх.
`402`	Платежа не было или он не прошёл. Смотрите заголовок `Payment-Required`.
`502`	Поиск не отработал. Можно повторить; не списывается ничего.

Пример

import { wrapFetch } from "x402-fetch";

const fetch402 = wrapFetch(fetch, wallet);
const res = await fetch402(
  "https://semagram.io/api/agent/search?q=crypto+news&limit=200",
  { method: "POST" },
);
const results = await res.json();

Model Context Protocol

/mcp отдаёт тот же каталог одним инструментом search поверх streamable HTTP. Аргументы те же, что выше, но структурированным объектом, а не строкой запроса; строки в ответе те же.

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

claude mcp add --transport http --client-id semagram-mcp semagram https://mcp.semagram.io/mcp

Любой MCP-клиент подключается так же, отличается только написание флага. Если ваш не умеет задавать идентификатор клиента, подключиться пока не выйдет — напишите нам, какой это клиент.

Доступ выдаётся по запросу: в отличие от платного эндпойнта, самостоятельной регистрации здесь нет. Напишите на [email protected], укажите клиент и его client id, — и вам вышлют учётные данные.

Ещё

agent-api.md — эта же страница одним файлом Markdown, чтобы её читала модель.
openapi.json — описание в формате OpenAPI.
/.well-known/x402 — документ обнаружения для платёжных каталогов.
Документация x402 — сам протокол.