Documentation

API documentation

Two ways to integrate: a Perfect Panel compatible endpoint for SMM panels, and the platform REST API for everything else.

Get API KeyBrowse services

Overview

Toplistbot exposes two HTTP APIs. Both are JSON over HTTPS and both spend the same token balance — pick the one that matches how you are integrating.

SMM panel API

A single Perfect Panel compatible endpoint. If your panel already speaks the standard SMM protocol, point it here and it works with no code changes.

Platform API

The REST API behind the dashboard: browse the site catalog, sign in, and create and manage campaigns from your own application.

Base URL

Base URL
https://backend.toplistbot.com/api

Getting started

From a new account to a running campaign in five steps. Everything below uses the SMM endpoint, which is the quickest way in; the platform API works the same way once you have a JWT.

  1. Create an account

    Sign up and verify your email. Verification credits your balance with 100 free tokens, which is enough to run a real campaign before you spend anything.

  2. Copy your API key

    Open your dashboard and generate an API key. Treat it like a password — it spends your token balance. You can rotate it at any time, which immediately invalidates the old one.

  3. Find the service you want

    List every site you can order on. Each entry has a numeric service id and a rate in tokens per 1,000 actions. Note the id of the site you want to promote on.

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

  4. Place your first order

    Send the service id, the URL your campaign should run against, and how many actions to run. The cost is deducted immediately and the response gives you an order id.

    cURL
    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"

  5. Track delivery

    Poll the order id to see how much has been delivered. Once you are happy with the flow, wire the same calls into your own panel or scripts.

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

Connecting a Perfect Panel instance

If you run Perfect Panel or compatible SMM panel software, you do not need to write any code — add Toplistbot as a provider with these settings and import the service list.

API URL
https://backend.toplistbot.com/api/v2
API key
YOUR_API_KEY
HTTP method
POST

Start with a small quantity on one site to confirm your link format is accepted before scaling up. A wrong link still costs tokens.

Authentication

The two APIs authenticate differently. The SMM endpoint uses a long-lived API key; the platform API uses a JWT you obtain by logging in.

API key (SMM endpoint)

Send your key as a `key` field on every request — as a form field, a query parameter, or an `Authorization: Bearer` header. Generate and rotate it from your dashboard. A GET to the same endpoint returns a status of ok and is a cheap way to check a key is valid.

Health check
curl https://backend.toplistbot.com/api/v2?key=YOUR_API_KEY

JWT (platform API)

Log in to receive a token, then send it as a bearer token on authenticated routes. Tokens expire — call /auth/refresh to get a fresh one.

Login
curl -X POST https://backend.toplistbot.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"..."}'
Authenticated request
curl https://backend.toplistbot.com/api/orders/getAll \
  -H "Authorization: Bearer YOUR_JWT"

Your API key spends real token balance. Keep it server-side: anything shipped to a browser or committed to a repository should be treated as compromised and rotated from the dashboard.

Tokens & pricing

Campaigns are paid for in tokens, bought up front. Every site publishes a rate — the tokens it costs to run 1,000 campaign actions there — returned as `rate` by the services action.

Cost formula
cost_in_tokens = (rate * quantity) / 1000

A site with a rate of 13 costs 13 tokens for 1,000 actions, so an order of 500 costs 6.5 tokens. The cost is deducted when the order is accepted, and cancelling refunds the unspent remainder.

The balance and status responses report a currency field of USD for Perfect Panel compatibility, but the value is a token balance, not dollars. Treat the number as tokens.

SMM panel API

One endpoint handles everything. Send an `action` field with each POST to choose the operation; every request also carries your `key`.

POSThttps://backend.toplistbot.com/api/v2
ActionParameters
services—
addservice, link, quantity, interval?
statusorders
balance—
cancelorders

action=services

Lists every site you can order on, with its current rate and limits. Use the `service` id in your add calls.

cURL
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"
Response
[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` is tokens per 1,000 actions. `min` is 1 and `max` is 50000 for every service.

action=add

Creates a campaign and immediately deducts its cost from your balance.

ParameterTypeDescription
keyrequiredstringYour API key.
actionrequiredstringMust be `add`.
servicerequiredintegerService id from the services action.
linkrequiredurlThe URL the campaign runs against. Must be a valid URL.
quantityrequiredintegerNumber of actions to run, between 1 and 50000.
intervalintegerActions per hour. Defaults to 15, capped at 4000, and cannot exceed the site's own maximum.
cURL
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"
Response
{
  "order_id": 184223
}

action=status

Returns progress for one or more orders. Pass a single id for a flat object, or a comma-separated list.

cURL
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"
Response — single order
{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

With several ids the response is keyed by order id, and unknown or foreign orders return an error entry rather than failing the whole request.

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

action=balance

Returns your remaining token balance.

cURL
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"
Response
{
  "balance": 528.41,
  "currency": "USD"
}

action=cancel

Stops an order and refunds the unspent remainder to your balance. Completed orders cannot be cancelled.

cURL
curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"
Response
[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

Platform API

The same REST API the dashboard uses. Catalog endpoints are public; everything else needs a JWT.

Catalog

Public, no authentication. Useful for building your own directory or pricing page.

  • GET/orders/getAllWebsitesEvery listed site with rates and metadata
  • POST/orders/getWebsiteDetailsByNameOne site by exact name
  • GET/orders/getAllBasicWebsitesDetails20 random site names
  • POST/products/getSuggestionsRelated sites for a set of ids
  • GET/products/tokensAvailable token packages
  • POST/products/suggestSubmit a site for us to add
  • GET/news/timelineProduct changelog
cURL
curl https://backend.toplistbot.com/api/orders/getAllWebsites

Account

Registration, sessions and billing history.

  • POST/auth/registerCreate an account
  • POST/auth/loginExchange credentials for a JWT
  • POST/auth/refreshIssue a fresh JWT JWT
  • POST/auth/logoutInvalidate the current JWT JWT
  • GET/auth/user-profileCurrent user profile JWT
  • POST/auth/reset-api-keyRotate your API key JWT
  • GET/invoices/getBilling history JWT

Campaigns

Create and manage campaigns, and read their delivery logs.

  • GET/orders/getAllYour campaigns, newest first
  • POST/orders/checkoutCreate one or more campaigns
  • POST/orders/updateEdit a campaign
  • POST/orders/pausePause a running campaign
  • POST/orders/unpauseResume a paused campaign
  • POST/orders/archiveArchive a campaign
  • PATCH/orders/updateLimitChange the daily cap
  • GET/orders/logs/{id}Delivery log for a campaign
  • GET/orders/graph/{id}Time series for charting

Errors

Errors come back with a matching HTTP status. Validation failures return an `errors` object keyed by field name.

  • 400Invalid action, malformed parameters, or a service id that does not exist.
  • 401Missing or invalid credentials.
  • 403Authenticated, but your token balance is too low for the order.
  • 422The request was understood but failed validation.
Validation error
{
  "errors": {
    "quantity": ["The quantity must be at least 1."]
  }
}

Limits & notes

  • Order quantity must be between 1 and 50000 actions.
  • Interval defaults to 15 per hour and is capped at 4000. Requesting more than a site's own maximum is rejected with a 400 naming the limit.
  • The `refill` and `refill_status` actions are not implemented — create a new order instead.
  • The `status` field is not yet a live progress signal; use `remains` and `start_count` to track delivery.
  • Listing sites set their own rules and change them over time. You are responsible for making sure your use complies with the terms of any site you promote on. We do not promise any particular ranking or placement.
Ask us on Discord
Free to start

Start Promoting Now!

Verify your email and get 100 free tokens to try out our service. No strings attached.

Register now Join Discord Browse Supported Sites
No credit card
Cancel anytime
24/7 support