Official libraries

Everything on this site is plain HTTP and you never have to install anything. The libraries exist because four things — the autoposter’s interval, the retry on a 429, the constant-time signature check, and hashing the raw body rather than a re-serialised one — are the four things hand-written integrations get wrong, and each of them costs something: a rate limit, a missed vote, or a stranger claiming rewards.

Not published yet. Both clients are written and tested, and go to npm and PyPI under the names below shortly. Until then every guide here works with plain HTTP; the autoposting guide shows that form.

JavaScript

npm install discordbotlist-sdk — no dependencies, Node 18+.

Python

pip install discordbotlist — async, no hard dependencies.

On npm the package is discordbotlist-sdk, not discordbotlist. That name belongs to a different site (discordbotlist.com) and installing it here gets you a client for somebody else’s API.

The whole integration

import { Client, Events } from 'discord.js';
import { AutoPoster, DiscordBotListClient } from 'discordbotlist-sdk';

const client = new Client({ intents: [] });

const dbl = new DiscordBotListClient({
  token: process.env.DBL_TOKEN,
  botId: process.env.BOT_ID,
});

client.once(Events.ClientReady, () => {
  new AutoPoster(dbl, { serverCount: () => client.guilds.cache.size }).start();
});

import os
from discord.ext import commands
from discordbotlist import AutoPoster, DiscordBotListClient

bot = commands.Bot(command_prefix="!")
dbl = DiscordBotListClient(os.environ["DBL_TOKEN"], os.environ["BOT_ID"])

@bot.event
async def on_ready():
    AutoPoster(dbl, lambda: len(bot.guilds)).start()

The poster posts once on start and every 30 minutes after that. The floor is five minutes: the limit is 60 requests a minute and a server count does not move sixty times a minute.

Sharded bots post the total, not one shard’s slice. A shard posting its own count makes the listing show whichever shard checked in last — the number then jumps around and means nothing.

Vote rewards

const { hasVoted, nextVoteAt } = await dbl.hasVoted(userId);

vote = await dbl.has_voted(str(user_id))
# vote.has_voted, vote.next_vote_at

nextVoteAt / next_vote_at is the cooldown’s end, so your bot can say when to come back rather than “you have already voted”.

Verifying a webhook

Both libraries verify and parse in one call, and return nothing at all when the signature does not match — so there is no boolean to forget.

import { parseWebhook } from 'discordbotlist-sdk';

app.post('/webhooks/votes', express.raw({ type: 'application/json' }), (req, res) => {
  const vote = parseWebhook(
    req.body,
    req.header('X-Webhook-Signature-256'),
    process.env.DBL_WEBHOOK_SECRET
  );
  if (!vote) return res.status(401).end();

  grantReward(vote.user_id);
  res.status(204).end();
});

from discordbotlist import parse_webhook

@app.post("/webhooks/votes")
async def votes(request: Request):
    vote = parse_webhook(
        await request.body(),
        request.headers.get("x-webhook-signature-256"),
        os.environ["DBL_WEBHOOK_SECRET"],
    )
    if vote is None:
        return Response(status_code=401)

    await grant_reward(vote.user_id)
    return Response(status_code=204)

Both take the raw body. Parsing first and hashing the result is the common mistake: JSON.parse then JSON.stringify — or json.loads then json.dumps — produces different bytes, and the HMAC of different bytes never matches.

Errors you can branch on

One class per status, so nothing has to read a message to decide what to do.

Class	Status	What to do
`BadRequestError`	400	Fix the body. Retrying sends the same bytes.
`AuthError`	401	Fix the token.
`NotFoundError`	404	Wrong bot id, or the token is another listing’s.
`RateLimitError`	429	Wait `retryAfter` / `retry_after` seconds.
`ServerError`	5xx	Retry with backoff.

Both clients already retry a 429 or a 5xx once, waiting the interval the API asked for.

Using another library

Nothing here is required. The API reference is the contract, and the field names match what every other bot list uses — so a poster library you already run (blapi and friends) works by adding one host. The autoposting guide shows that form.

Getting started

API reference

Guides

JavaScript

Python

The whole integration

Vote rewards

Verifying a webhook

Errors you can branch on

Using another library

JavaScript

Python

​The whole integration

​Vote rewards

​Verifying a webhook

​Errors you can branch on

​Using another library

The whole integration

Vote rewards

Verifying a webhook

Errors you can branch on

Using another library