Top.gg Python SDK

For more information, see the documentation here: https://topggpy.rtfd.io.

The community-maintained Python SDK for Top.gg.

Chapters

• Installation
• Setting up
• Usage
  • Getting your project's information
  • Getting your project's vote information of a user
  • Getting a cursor-based paginated list of votes for your project
  • Posting your bot's application commands list
  • Generating widget URLs
  • Webhooks

Installation

$ pip install topggpy

Setting up

importtopggimportostoken=os.getenv('TOPGG_TOKEN')
asserttokenisnotNone, 'Missing TOPGG_TOKEN environment variable.'client=topgg.Client(token)

Usage

Getting your project's information

project=awaitclient.get_self()

Getting your project's vote information of a user

Discord ID

vote=awaitclient.get_vote(topgg.UserSource.DISCORD, 661200758510977084)

Top.gg ID

vote=awaitclient.get_vote(topgg.UserSource.TOPGG, 8226924471638491136)

Getting a cursor-based paginated list of votes for your project

fromdatetimeimportdatetimefirst_page=awaitclient.get_votes(datetime(2026, 1, 1))
forvoteinfirst_page:
print(vote)
second_page=awaitfirst_page.next()
forvoteinsecond_page:
print(vote)
third_page=awaitsecond_page.next()

Posting your bot's application commands list

Discord.py

commands= [command.to_dict() forcommandinawaitbot.tree.fetch_commands()]
awaitclient.post_commands(commands)

Raw

# Array of application commands that# can be serialized to Discord API's raw JSON format.awaitclient.post_commands(
[
{
'id': '1',
'type': 1,
'application_id': '1',
'name': 'test',
'description': 'command description',
'default_member_permissions': '',
'version': '1',
}
]
)

Generating widget URLs

Large

widget_url=topgg.Widget.large(topgg.Platform.DISCORD, topgg.ProjectType.BOT, 1026525568344264724)

Votes

widget_url=topgg.Widget.votes(topgg.Platform.DISCORD, topgg.ProjectType.BOT, 1026525568344264724)

Owner

widget_url=topgg.Widget.owner(topgg.Platform.DISCORD, topgg.ProjectType.BOT, 1026525568344264724)

Social

widget_url=topgg.Widget.social(topgg.Platform.DISCORD, topgg.ProjectType.BOT, 1026525568344264724)

Webhooks

With express:

importtopggfromaiohttpimportwebimportossecret=os.getenv('TOPGG_WEBHOOK_SECRET')
assertsecretisnotNone, 'Missing TOPGG_WEBHOOK_SECRET environment variable.'# POST /webhookwebhooks=topgg.Webhooks('/webhook', secret)
@webhooks.on(topgg.PayloadType.TEST)asyncdeftest_listener(payload: topgg.TestPayload, trace: str) ->web.Response:
print(payload)
returnweb.Response(status=204)
awaitwebhooks.start()