API Libraries

Libraries developed by the community that interact with the BotBlock API

C# - BotListAPI

BotListAPI is a C# nuget package for the discord.net lib that provides an easy method to manually or automatically post your bot’s server count every 10 minutes with information for each bot list through the BotBlock API. It also supports sharded clients and .net framework or .net core.

Example Usage

ListClient = new ListClient(_Client, new ListConfig
    BotsOnDiscord = "dsag38_auth_token_fda6gs", // Add any other lists as needed
    BotListSpace = "qos56a_auth_token_gfd8g6"


Java - JavaBotBlockAPI

JavaBotBlockAPI is a Java Wrapper for the BotBlock API, which allows you to either GET or POST Bot information such as your bot’s guild count.
The Original library - BotBlock4J - that this wrapper originates from, was made by Nathan-Webb. Since then has it been recoded, improved and is now maintained by Andre601 under its new name.
The Java Wrapper covers the full API features offered by BotBlock, meaning you can GET either Bot or List information or POST Bot information to multiple Lists.
In addition does it offer a Javacord and JDA module which allows you to more easly provide the Guild count of your bot for POSTing.
Please take a look at the Usage Examples on the GitHub Repository for some of the methods this Wrapper offers!

Example Usage

// Create BotBlockAPI instance
BotBlockAPI api = new BotBlockAPI.Builder()
    .addAuthToken("bots.ondiscord.xyz", "dsag38_auth_token_fda6gs")
    .addAuthToken(Site.BOTLIST_SPACE, "qos56a_auth_token_gfd8g6")

// Create PostAction instance
PostAction postAction = new PostAction("botId");

// Post manually
postAction.postGuilds("botId", guilds, api);

// Post automatically
postAction.enableAutoPost("botId", guilds, api);

// Disable automatic posting
postAction.disableAutoPost(); // Disable with no delay
postAction.disableAutoPost(api); // Disable with BotBlockAPI#getUpdateDelay() delay
postAction.disableAutoPost(1, TimeUnit.MINUTES); // Disable with 1 Minute delay.

// ------------------------------

// Create an instance of GetBotAction for GETting bot info
GetBotAction getBot = new GetBotAction();

// Get complete Bot information.

// Create an instance of GetListAction for GETting list info
GetListAction getList = new GetListAction();

// Get all available lists.

Javascript - BLAPI

blapi is a library that makes use of the BotBlock API to post directly to BotBlock to forward your bot server/guild count on to all lists but also uses the lists endpoint to manually post to each bot list if you get ratelimited from the BotBlock post count API.

Example Usage

const Discord = require("discord.js");
const blapi = require("blapi");
const apiKeys = {
  "bots.ondiscord.xyz": "dsag38_auth_token_fda6gs", // Add other bot lists as needed
  "botlist.space": "qos56a_auth_token_gfd8g6"

let bot = new Discord.Client({ autoReconnect: true });
blapi.handle(bot, apiKeys, 60); // If interval is not passed (60), it will default to every 30 minutes

Javascript - BotList

BotList is a package that uses the BotBlock API lists endpoint to fetch all bot list information from BotBlock and then manually posts to each one from your bot instead of through the BotBlock API count endpoint.

Example Usage

const BotList = require('botlist');
const botID = 'xxx';
const client = new BotList.Client(botID, {
    tokens: {
        'bots.ondiscord.xyz': 'dsag38_auth_token_fda6gs', // Add other bot lists as needed
        'botlist.space': 'qos56a_auth_token_gfd8g6'
    interval: 1000 * 30

client.on('beforePost', () => {
    if (!bot.ready) return;
    const serverCount = bot.guilds.size;
    const shards = bot.shards.size;
    client.update(serverCount, shards);

client.on('afterPost', (successful, failed) => {
    console.log('Just finished posting to all bot lists, ' + successful + ' were successful, ' + failed + ' failed to post');

client.on('error', (error) => {
    console.warn('Something happened', error);


Python - discordlists.py

discordlists.py is available via pip and provides an easy to use Client class to automatically and manually post your server/guild count to the BotBlock API to forward it on to all BotBlock bot lists. This library also provides a way to get information about a bot from all lists on BotBlock through the GET bot API endpoint.

Example Usage

from discord.ext import commands

import discordlists

class DiscordListsPost(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        self.api = discordlists.Client(self.bot)  # Create a Client instance
        self.api.set_auth("bots.ondiscord.xyz", "dsag38_auth_token_fda6gs") # Set authorisation token for a bot list
        self.api.set_auth("botlist.space", "qos56a_auth_token_gfd8g6") # Set authorisation token for a bot list
        self.api.start_loop()  # Posts the server count automatically every 30 minutes

    async def post(self, ctx: commands.Context):
        Manually posts guild count using discordlists.py (BotBlock)
            result = await self.api.post_count()
        except Exception as e:
            await ctx.send("Request failed: `{}`".format(e))

        await ctx.send("Successfully manually posted server count ({:,}) to {:,} lists."
                       "\nFailed to post server count to {:,} lists.".format(self.api.server_count,

def setup(bot):