Top.gg Node.js SDK
For more information, see the documentation here: https://topgg.js.org.
The community-maintained Node.js SDK for Top.gg.
Chapters
Installation
NPM
$ npm i @top-gg/sdkYarn
$ yarn add @top-gg/sdkSetting up
import Topgg from "@top-gg/sdk";
const client = new Topgg.Api(process.env.TOPGG_TOKEN);Usage
Getting your project's information
const project = await client.getSelf();
console.log(project);
// =>
// {
// id: '218109768489992192',
// name: 'Miki',
// type: 'bot',
// platform: 'discord',
// headline: 'A great bot with tons of features! language | admin | cards | fun | levels | roles | marriage | currency | custom commands!',
// tags: [
// 'anime',
// 'customizable-behavior',
// 'economy',
// 'fun',
// 'game',
// 'leveling',
// 'multifunctional',
// 'role-management',
// 'roleplay',
// 'social'
// ],
// votes: { current: 1120, total: 313389 },
// review: { score: 4.38, count: 62245 }
// }Getting your project's vote information of a user
Discord ID
const vote = await client.getVote("661200758510977084");Top.gg ID
const vote = await client.getVote("8226924471638491136", "topgg");Getting a cursor-based paginated list of votes for your project
const since = new Date("2026-01-01");
const firstPage = await client.getVotes(since);
console.log(firstPage.votes);
const secondPage = await firstPage.next();
console.log(secondPage.votes);Posting your bot's application commands list
Discord.js
const commands = (await bot.application.commands.fetch()).map(command => command.toJSON());
await client.postCommands(commands);Raw
// Array of application commands that
// can be serialized to Discord API's raw JSON format.
await client.postCommands([
{
options: [],
name: 'test',
name_localizations: null,
description: 'command description',
description_localizations: null,
contexts: [],
default_permission: null,
default_member_permissions: null,
dm_permission: false,
integration_types: [],
nsfw: false
}
]);Generating widget URLs
Large
const widgetUrl = Topgg.Widget.large("discord", "bot", "1026525568344264724");Votes
const widgetUrl = Topgg.Widget.votes("discord", "bot", "1026525568344264724");Owner
const widgetUrl = Topgg.Widget.owner("discord", "bot", "1026525568344264724");Social
const widgetUrl = Topgg.Widget.social("discord", "bot", "1026525568344264724");Webhooks
With express:
import { Webhook } from "@top-gg/sdk";
import express from "express";
const app = express();
const webhook = new Webhook(process.env.TOPGG_WEBHOOK_SECRET);
// POST /webhook
app.post("/webhook", webhook.listener((payload) => {
console.log(payload);
}));
app.listen(8080);