API Echo

Публичный REST API и вебхуки: подключайте экономику, уровни и мониторинг сервера к своим сервисам — игровому серверу, сайту, боту или автоматизациям.

https://api.echo-assistants.tech

Авторизация Сервис Экономика Уровни Мониторинг Каталог Вебхуки Скоупы Лимиты и ошибки

Авторизация

Каждый запрос требует ключ в заголовке Authorization. Ключ выдаётся на сервер, а не на аккаунт. Создать его может только владелец сервера в дашборде → «Разработчикам»: до 3 ключей. Эндпоинты /catalog/* — публичные, ключ не нужен (лимит 60/мин по IP, ответы кешируются).

curl https://api.echo-assistants.tech/me \
  -H "Authorization: Bearer echo_ВАШ_КЛЮЧ"

Создать ключ в дашборде

Сервис

GET/meбез скоупа

Проверка ключа: возвращает сервер и его скоупы.

Ответ

{ "guildId": "1369...", "scopes": ["levels:read"] }

Экономика

GET/economy/balance?user=<id>economy:read

Баланс участника: кошелёк, банк, фишки.

Ответ

{ "user": "123...", "balance": 1500, "bank": 200, "chips": 0 }

POST/economy/balanceeconomy:write

Начислить или списать валюту. delta может быть отрицательным; баланс остаётся в диапазоне 0…2 000 000 000.

Тело запроса

{ "user": "123...", "delta": 250 }

Ответ

{ "ok": true, "user": "123...", "balance": 1750 }

GET/economy/leaderboard?limit=<n>economy:read

Топ участников по балансу (limit 1–100, по умолчанию 20).

Ответ

{ "guildId": "1369...", "leaderboard": [ { "rank": 1, "userId": "627...", "balance": 15000, "bank": 3000 } ] }

Уровни

GET/levels/leaderboard?limit=<n>levels:read

Топ участников по опыту (limit 1–100, по умолчанию 20).

Ответ

{ "guildId": "1369...", "leaderboard": [ { "rank": 1, "userId": "627...", "xp": 3965, "messages": 374, "voiceSeconds": 1273 } ] }

Мониторинг

GET/monitoring/servermonitoring:read

Карточка сервера в каталоге: Пламя за период, всего, место в топе и статусы.

Ответ

{ "guildId": "1369...", "slug": "my-server", "flames": 420, "flamesTotal": 9100, "published": true, "rank": 3, "official": false, "partner": true, "verified": true }

GET/monitoring/top?limit=<n>monitoring:read

Топ серверов каталога по Пламени (limit 1–100, по умолчанию 20).

Ответ

{ "top": [ { "rank": 1, "guildId": "1369...", "slug": "my-server", "flames": 980, "flamesTotal": 21000 } ] }

Каталог

GET/catalog/servers?search=&tag=&lang=&limit=публичный · без ключа

Поиск и список серверов в каталоге мониторинга. Всё публично — ключ не нужен.

Ответ

{ "count": 1, "servers": [ { "slug": "my-server", "name": "My Server", "memberCount": 5200, "flames": 980, "tags": ["Игры"], "language": "ru", "invite": "https://discord.gg/...", "badges": { "verified": true } } ] }

GET/catalog/top?limit=<n>публичный · без ключа

Топ каталога по Пламени.

Ответ

{ "top": [ { "rank": 1, "slug": "my-server", "name": "My Server", "flames": 980 } ] }

GET/catalog/server/<slug>публичный · без ключа

Публичная карточка сервера: описание, Пламя, место, теги, бейджи, инвайт, рейтинг.

Ответ

{ "slug": "my-server", "name": "My Server", "flames": 980, "rank": 3, "rating": { "avg": 8.7, "count": 42 }, "invite": "https://discord.gg/..." }

GET/catalog/reviews/<slug>?limit=<n>публичный · без ключа

Отзывы о сервере со средней оценкой.

Ответ

{ "slug": "my-server", "summary": { "avg": 8.7, "count": 42 }, "reviews": [ { "user": "Ник", "rating": 9, "comment": "Топ", "at": "..." } ] }

GET/catalog/tagsпубличный · без ключа

Теги/категории каталога с числом серверов.

Ответ

{ "tags": [ { "tag": "Игры", "count": 128 } ] }

Вебхуки

Echo сам присылает события на ваш URL в реальном времени. Настройте вебхук в дашборде → «Разработчикам». Каждый запрос подписан заголовком X-Echo-Signature (HMAC-SHA256 тела по вашему секрету), имя события — в X-Echo-Event.

flame.bump

Кто-то дал серверу Пламя (апнул) — в каталоге или командой /flame.

{
  "event": "flame.bump",
  "guildId": "1369...",
  "flames": 421,
  "flamesTotal": 9101,
  "amount": 1,
  "source": "web",
  "at": "2026-07-27T20:30:00.000Z"
}

test

Отправляется кнопкой «Отправить тест» — проверить, что приёмник работает.

{ "event": "test", "guildId": "1369...", "message": "Проверка вебхука Echo", "at": "..." }

Проверка подписи

import crypto from "node:crypto";

// body — сырой текст запроса, secret — из дашборда
const expected = "sha256=" +
  crypto.createHmac("sha256", secret).update(body).digest("hex");
const ok = req.headers["x-echo-signature"] === expected;

Скоупы

При создании ключа выбираются права — каждый эндпоинт требует свой скоуп.

guild:read

Данные сервера

Базовая информация о сервере.

economy:read

Чтение экономики

Балансы: кошелёк, банк, фишки.

economy:write

Запись экономики

Начисление и списание валюты.

levels:read

Чтение уровней

Опыт и лидерборд участников.

monitoring:read

Чтение мониторинга

Пламя, место в топе, статусы каталога.

Лимиты и ошибки

До 3 ключей на сервер, лимит — 40 запросов в минуту на каждый ключ. Ошибки приходят как JSON { "error": "..." } с соответствующим HTTP-кодом.

Код	error	Когда
400	bad_fields	Неверные или недостающие параметры запроса.
401	unauthorized	Ключ не передан, неверен или отозван.
403	insufficient_scope	У ключа нет нужного скоупа для этого запроса.
429	rate_limited	Превышен лимит 40 запросов в минуту.

Ключ виден целиком только один раз при создании — сохраните его. Администрация проекта может отключить ключ при злоупотреблении.