GitHunt
NU

null8626/node-sdk

An official module for interacting with the Top.gg API

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/sdk

Yarn

$ yarn add @top-gg/sdk

Setting 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);