Документация API

action=services

Возвращает все сайты, на которых можно оформить заказ, с текущим тарифом и ограничениями. Используйте id `service` в вызовах add.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` указан в токенах за 1 000 действий. Для всех сервисов `min` равен 1, `max` — 50000.

action=add

Создаёт кампанию и сразу списывает её стоимость с баланса.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

{
  "order_id": 184223
}

action=status

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

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

При нескольких id ответ индексируется по id заказа, а неизвестные или чужие заказы возвращают запись об ошибке, не обрушивая весь запрос.

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`status` и `cancel` принимают не более 100 идентификаторов заказов за вызов. Группируйте вместо перебора: один вызов со 100 идентификаторами намного дешевле для обеих сторон, чем 100 вызовов.

action=balance

Возвращает остаток вашего баланса токенов.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

{
  "balance": 528.41,
  "currency": "USD"
}

action=cancel

Останавливает заказ и возвращает неизрасходованный остаток на баланс. Завершённые заказы отменить нельзя.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

Каталог и поиск#

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

• GET/orders/getAllWebsitesОткрытыйПолный каталог: каждый сайт с тарифами, лимитами и метаданными
• GET/orders/getAllBasicWebsitesDetailsОткрытый20 случайных названий сайтов — для виджетов и автодополнения
• POST/orders/getWebsiteDetailsByNameОткрытыйОдин сайт по точному названию
• POST/products/getSuggestionsОткрытыйСайты, связанные с набором идентификаторов
• GET/products/demand?days=30ОткрытыйСколько заказов было на каждый сайт в последнее время
• GET/products/tokensОткрытыйПакеты токенов, доступные к покупке
• POST/products/suggestAPI-ключПопросить добавить новый сайт
• GET/api/news/timelineОткрытыйИстория изменений продукта

curl "https://backend.toplistbot.com/orders/getAllWebsites"

Просите меньше

Полный каталог занимает около 665 КБ, и половину этого веса дают два поля, с которыми вы никогда не оформите заказ: JSON-блок популярности и маркетинговое описание. Оставьте только поля, которыми заказываете, отбросьте неактивные сайты — и останется около 40 КБ.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

Аккаунт и сессии#

Регистрация требует браузера: её защищает проверка Cloudflare. Зарегистрируйтесь один раз на app.toplistbot.com, а всё дальнейшее автоматизируйте.

• POST/api/auth/registerОткрытыйСоздать аккаунт — только из браузера, защищено капчей
• POST/api/auth/loginОткрытыйОбменять учётные данные на JWT
• POST/api/auth/refreshJWTВыдать новый JWT взамен истекающего
• POST/api/auth/logoutJWTАннулировать текущий JWT
• GET/api/auth/user-profileJWTТекущий аккаунт с балансом и API-ключом
• GET/api/userJWTТот же объект пользователя по более короткому пути
• GET/api/api_tokenAPI-ключОпределить владельца API-ключа — так проверяют ключ
• POST/api/auth/reset-api-keyJWTСменить API-ключ; старый умирает сразу
• POST/api/auth/fingerprintJWTЗаписать отпечаток браузера в аккаунт
• POST/api/auth/ipJWTЗаписать текущий IP аккаунта
• POST/api/auth/forgot-passwordОткрытыйОтправить ссылку на сброс пароля, действует 60 минут
• POST/api/auth/reset-passwordОткрытыйЗадать новый пароль по присланному токену

Двухфакторная защита и вход#

Двухфакторная защита прикрывает вход по паролю. На API-ключи она не распространяется — поэтому для работы без присмотра ключ подходит лучше.

• POST/api/2fa/enableJWTНачать привязку: вернёт секрет, ссылку на QR и коды восстановления
• POST/api/2fa/verifyJWTПодтвердить шестизначный код и включить двухфакторную защиту
• POST/api/2fa/disableJWTВыключить двухфакторную защиту
• POST/api/account/verification/requestJWTОтправить письмо с подтверждением на адрес аккаунта
• GET/api/account/verification/confirm?token=ОткрытыйПоказать страницу подтверждения — ничего не записывает
• POST/api/account/verification/confirmОткрытыйЗавершить подтверждение
• GET/api/auth/googleОткрытыйНачать вход через Google
• GET/api/auth/google/callbackОткрытыйВозврат после входа через Google
• GET/api/auth/discordОткрытыйНачать вход через Discord
• GET/api/auth/discord/callbackОткрытыйВозврат после входа через Discord

Настройки и оповещения#

Переключатели писем и уведомлений, ваш вебхук и лента оповещений аккаунта.

• GET/api/user/email-preferencesJWTСостояние подписки на маркетинговые письма
• POST/api/user/email-preferencesJWTИзменить его
• GET/api/user/notification-preferencesJWTНастройка всплывающих уведомлений о доставке
• POST/api/user/notification-preferencesJWTИзменить её: нужен настоящий булев тип JSON
• GET/api/user/alerts?limit=20JWTОповещения аккаунта, свежие первыми, с постраничностью по ?before
• POST/api/user/alerts/readJWTПометить оповещение прочитанным
• POST/api/user/alerts/dismissJWTСкрыть оповещение
• GET/api/user/webhooksJWTВаш вебхук: адрес, события и состояние доставки
• POST/api/user/webhooksJWTСохранить адрес, события и переключатель вкл/выкл
• POST/api/user/webhooks/testJWTСразу отправить одно тестовое событие и сообщить, что ответил ваш сервер
• GET/api/user/webhooks/deliveries?limit=25JWTЖурнал доставки вебхука, свежие первыми, с постраничностью по ?before
• GET/api/email/unsubscribe?token=ОткрытыйОтписка в один клик по присланному токену

Кампании#

Создавайте кампании, управляйте ими на ходу и завершайте их. Это ядро API платформы.

• GET/orders/getAllAPI-ключВаши кампании, свежие первыми, вместе с их сайтами
• GET/orders/get/{id}API-ключОдна кампания
• POST/orders/checkoutAPI-ключСоздать кампании и списать с баланса
• POST/orders/updateAPI-ключИзменить кампанию
• POST/orders/pauseAPI-ключПриостановить активную кампанию
• POST/orders/unpauseAPI-ключВозобновить приостановленную кампанию
• POST/orders/archiveAPI-ключАрхивировать кампанию
• POST/orders/unarchiveAPI-ключВернуть кампанию из архива
• PATCH/orders/updateLimitAPI-ключЗадать или снять дневной потолок действий

POST /orders/checkout

Тело запроса — это JSON-массив строк корзины на верхнем уровне, а не объект. Каждая строка — отдельная кампания. Вся корзина проверяется до любого списания, а списание и вставки идут одной транзакцией: заказ либо проходит целиком, либо не проходит вовсе.

Строка с фиксированным количеством

Обычный случай: заданное число действий для одного адреса.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

Строка подписки

Для сайтов, у которых признак `subscribeable` равен 1. Цена считается как subscription_price_1d сайта, умноженная на число дней и на скидку уровня: Weekly — 0,90, Monthly — 0,80, всё остальное — 1,00. Доставляемое количество выводится на сервере из собственного subscription_speed сайта, поэтому ничем из запроса его не изменить.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

Ответы

• 200Все строки созданы, с баланса списано. Тело ответа — обычный текст.
• 400Тело запроса не является корректным JSON.
• 402Не хватает токенов. В сообщении указана нужная сумма, списания не было.
• 422Одна или несколько строк некорректны. Списания не было.
• 429Та же корзина отправлялась в последние 60 секунд. Повторите после указанной паузы.

Ответ 422 указывает на проблемную строку: ошибки нумеруются как items.[index].[field], поэтому корзина с тремя плохими строками чинится за один заход, а не за три.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` обязателен; отправляйте только те поля, которые меняете. Заказы-подписки изменить нельзя.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

Дневной потолок

`type: "delete"` снимает потолок. Валидатор всё равно требует `max_votes_per_day` — отправьте любое целое число.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

Логи и аналитика#

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

• GET/orders/logs/{id}API-ключЛог доставки кампании по каждому действию
• GET/orders/graph/{id}API-ключВременной ряд одной кампании, готовый к отрисовке
• GET/api/orders/graph/summaryJWTОдин ряд по всем вашим кампаниям
• GET/orders/grouped/usernames/{id}API-ключДоставки, сгруппированные по имени пользователя
• POST/orders/averageAPI-ключСредняя доставка по нескольким кампаниям
• GET/api/logs/{id}/filtered-graphJWTОтфильтрованный временной ряд

Профили имён и прокси#

Профиль имён — это именованный список имён пользователей, которые использует кампания. Профиль прокси — именованный список разрешённых стран для используемых IP. Привяжите любой из них к кампании через username_profile_id или proxy_profile_id в /orders/update.

• GET/advanced/profile/getAPI-ключВаши профили имён
• GET/advanced/profile/get/{id}API-ключОдин профиль имён
• POST/advanced/profile/createAPI-ключСоздать профиль имён или перезаписать по идентификатору
• DELETE/advanced/profile/delete/{id}API-ключУдалить профиль имён
• GET/advanced/profile/proxy/getAPI-ключВаши профили прокси
• GET/advanced/profile/proxy/get/{id}API-ключОдин профиль прокси
• POST/advanced/profile/proxy/createAPI-ключСоздать профиль прокси или перезаписать по идентификатору
• DELETE/advanced/profile/proxy/delete/{id}API-ключУдалить профиль прокси

Токены Discord#

Для топов, которые требуют входа через Discord. Повторное добавление того же токена отклоняется как дубликат.

• GET/api/discord-tokensJWTВаши токены Discord
• POST/api/discord-tokensJWTДобавить токен
• GET/api/discord-tokens/statsJWTСтатистика использования ваших токенов
• GET/api/discord-tokens/{id}JWTОдин токен
• PATCH/api/discord-tokens/{id}JWTИзменить токен или его активность
• DELETE/api/discord-tokens/{id}JWTУдалить токен
• PUT/api/discord-tokens/{id}/toggleJWTПереключить токен между включённым и выключенным

Счета и платежи#

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

• GET/invoices/getAPI-ключИстория счетов
• GET/api/subscriptions/subscriptionsJWTАктивные подписки
• GET/products/tokensByUserAPI-ключПакеты токенов по ценам вашего аккаунта
• POST/company/getAPI-ключВаш платёжный адрес
• POST/company/createAPI-ключЗадать его: country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTСсылка Stripe Checkout для пакета токенов
• GET/api/stripe/subscription?plan=JWTСсылка Stripe Checkout для тарифа
• GET/api/stripe/portalJWTСсылка на платёжный портал Stripe
• GET/api/stripe/documentsJWTСчета и квитанции Stripe
• GET/coinpayments/checkoutAPI-ключСсылка на оплату криптовалютой

Сохранённая корзина#

Корзина панели, которая хранится на сервере и переживает смену устройства. Для оформления заказов она не нужна: /orders/checkout принимает корзину прямо в запросе.

• GET/api/cartJWTСохранённая корзина
• PUT/api/cartJWTЗаменить её
• POST/api/cartJWTЗаменить её — то же, что PUT
• DELETE/api/cartJWTОчистить её

Внутренние эндпоинты#

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

• POST/api/stripe/webhookСобытия оплаты Stripe, проверяются по подписи
• POST/api/jobs/tickЗапускает подошедшие задачи, доступ по общему секрету
• POST/api/internal/vote-eventsСобытия голосов от сервиса голосования — доступ по общему секрету
• POST/api/pow/challengeПроверка proof-of-work при регистрации
• POST/api/logs/updateУчёт активности в письмах
• POST/api/order/{email}Создаёт заказ на другом аккаунте — только для списка администраторов
• GET/reset-password/{token}Старая серверная страница сброса пароля, оставлена ради уже отправленных ссылок
• GET/ОткрытыйПроверка доступности

Объект сайта#

Возвращают /orders/getAllWebsites и /orders/getWebsiteDetailsByName; он же вложен в каждую кампанию под ключом `website`.

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

Объект кампании#

Возвращают /orders/getAll и /orders/get/:id. Обратите внимание на то, чего нет: поля статуса не существует.

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

Работает ли она? Закончилась ли?#

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

Прогресс и возвраты#

amount_to_do считает принятые действия, amount_done — отправленные. Принимается лишь accept_rate процентов отправленных, поэтому величины в разных единицах и вычитать одну из другой напрямую неверно.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED actions.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

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

Настройка вебхука#

Четыре шага в панели — и ничего не нужно устанавливать.

1. 1

   Откройте карточку «Webhook»

   В панели перейдите в раздел «Account» и откройте вкладку «Notifications».

2. 2

   Вставьте адрес

   URL эндпоинта на вашем сервере, который будет принимать события. Он должен начинаться с https:// и быть доступен из интернета.

3. 3

   Выберите события

   Прошедшие и непрошедшие голоса включены по умолчанию. Начало голоса (vote.started) выключено — включайте его, только если действительно на него реагируете.

4. 4

   Сохраните и отправьте тест

   Адрес проверяется при сохранении, и вы сразу узнаете, если его не удаётся найти или он указывает на частную сеть. Затем нажмите «Send test»: тестовое событие уйдёт немедленно, а карточка покажет, что ответил ваш сервер.

Через API

Те же настройки доступны через API платформы с JWT. API-ключом их изменить нельзя: ключ нужен для работы с кампаниями и не должен позволять перенаправить события вашего аккаунта куда-то ещё.

curl -X POST https://behind.toplistbot.com/api/user/webhooks \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/toplistbot/3f9c1a7e5b2d",
    "enabled": true,
    "events": ["vote.succeeded", "vote.failed"]
  }'

{
  "available": true,
  "webhook": {
    "url": "https://example.com/hooks/toplistbot/3f9c1a7e5b2d",
    "enabled": true,
    "events": ["vote.succeeded", "vote.failed"],
    "failing": false,
    "retry_at": null,
    "last_ok_at": null,
    "last_error": null,
    "last_error_at": null,
    "created_at": "2026-10-06T09:12:44.000000Z",
    "updated_at": "2026-10-06T09:12:44.000000Z"
  },
  "events": ["vote.started", "vote.succeeded", "vote.failed"],
  "default_events": ["vote.succeeded", "vote.failed"]
}

Тест отправляется ровно один раз и никогда не повторяется. Ответ сообщает, дошёл ли он и что ответил ваш сервер.

curl -X POST https://behind.toplistbot.com/api/user/webhooks/test \
  -H "Authorization: Bearer YOUR_JWT"

{
  "delivered": false,
  "http_status": 500,
  "error": "Your server had an error (HTTP 500).",
  "delivery": { "id": 1874, "event": "webhook.test", "status": "failed", "...": "..." }
}

События#

Каждый запрос несёт ровно одно событие.

Тело запроса и заголовки#

Каждое событие — это POST-запрос с небольшим JSON-телом.

POST /hooks/toplistbot/3f9c1a7e5b2d HTTP/1.1
Content-Type: application/json
User-Agent: Toplistbot-Webhooks/1.0 (+https://toplistbot.com)
X-Toplistbot-Event: vote.succeeded
X-Toplistbot-Delivery: 1873

{
  "id": 1873,
  "event": "vote.succeeded",
  "created_at": "2026-10-06T09:12:44.123Z",
  "order_id": 184223,
  "vote_job_id": "7f3c2a9e-1b4d-4c8e-9a2f-5d6e7f8a9b0c",
  "site": "https://arena-top100.com/index.php?a=in&u=yourserver",
  "username": "PlayerOne"
}

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

Приём событий и повторы#

Ответьте любым статусом 2xx в течение 5 секунд. Медленную работу — запись в базу данных или выдачу награды игроку — выполняйте уже после ответа или в собственной очереди.

• 2xxДоставлено. Больше ничего не происходит.
• 3xxРедиректы не отслеживаются. Событие считается недоставленным и не повторяется, поэтому сохраняйте сразу конечный адрес.
• 4xxОтказ. Событие помечается как недоставленное и не повторяется: повторная отправка получила бы тот же ответ. Исключения — 408, 425 и 429: их мы повторяем.
• 5xxПовторяется — как и тайм-ауты, отклонённые соединения и недействительные сертификаты.

Когда ваш сервер даёт сбой, мы сразу перестаём слать ему запросы, а не стучимся в закрытую дверь. Новые события ставятся в очередь, и мы пробуем снова через 1 минуту, затем через 2, 4, 8 и так далее — с интервалом до часа. Повторы запускаются раз в 5 минут, поэтому ожидание округляется вверх до ближайшего запуска. Как только ваш сервер снова отвечает, очередь отправляется начиная с самых старых событий. Если нажать «Send test» после исправления сервера, очередь отправится сразу.

Событие, которое не удалось доставить за 24 часа, помечается как недоставленное. Выключение вебхука удаляет всё, что ещё стоит в очереди.

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

import express from 'express'

const app = express()
const seen = new Set() // use your database in production

app.post('/hooks/toplistbot/3f9c1a7e5b2d', express.json(), (req, res) => {
  // 1. Answer straight away. Anything slower than 5 seconds is a failure.
  res.sendStatus(204)

  // 2. Skip duplicates. A retry carries the same id.
  const event = req.body
  if (seen.has(event.id)) return
  seen.add(event.id)

  // 3. Now do the work.
  if (event.event === 'vote.succeeded') {
    rewardPlayer(event.username, event.order_id)
  }
})

app.listen(3000)

Журнал доставки#

Каждое отправленное событие записывается в журнал вместе со статусом, которым ответил ваш сервер, а при неудаче — с причиной. В панели журнал отображается под карточкой «Webhook». Через API записи идут от новых к старым, по умолчанию 25 на страницу, максимум 100. Доставленные события хранятся 7 дней, недоставленные — 30.

curl "https://behind.toplistbot.com/api/user/webhooks/deliveries?limit=25" \
  -H "Authorization: Bearer YOUR_JWT"

# next page: pass the id of the last delivery you received
curl "https://behind.toplistbot.com/api/user/webhooks/deliveries?limit=25&before=1850" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "deliveries": [
    {
      "id": 1873,
      "event": "vote.succeeded",
      "order_id": 184223,
      "status": "delivered",
      "attempts": 1,
      "http_status": 204,
      "error": null,
      "created_at": "2026-10-06T09:12:44.000000Z",
      "delivered_at": "2026-10-06T09:12:44.000000Z",
      "payload": { "id": 1873, "event": "vote.succeeded", "...": "..." }
    }
  ],
  "has_more": true,
  "available": true
}

Безопасность#

• Только HTTPS. События никогда не отправляются по незашифрованному соединению.
• Адрес должен быть публичным. Адреса в частных или локальных сетях отклоняются при сохранении и повторно при каждой отправке — в том числе домен, который позже направили на такой адрес.
• Никаких логинов и паролей в адресе. Вместо этого используйте секретный путь.
• Сохранять можно не чаще 20 раз в минуту, а «Send test» — не чаще 5 раз в минуту.