topdiscordlist

Top Discord List SDK for Go

Hand out rewards when someone votes for your Discord server or bot on Top Discord List.

go get github.com/TopDiscordLists/go-sdk

Go 1.23 or newer. The API client and webhook verification use nothing but the standard library; the vote stream pulls in github.com/coder/websocket, since Go has no WebSocket client of its own.

Listen for votes

Your bot dials out, so this needs no public URL.

listener := topdiscordlist.NewListener(os.Getenv("TDL_TOKEN"))

err := listener.Run(context.Background(), func(vote topdiscordlist.VoteEvent) {
    log.Printf("%s voted, now at %d", vote.Username, vote.VoteCount)
    giveReward(vote.UserID)
})

Run blocks and reconnects on its own with backoff. Cancel the context to stop.

Receive webhooks

http.Handle("/vote", topdiscordlist.WebhookHandler(secret, func(p topdiscordlist.Payload) {
    if p.Vote.IsTest {
        return
    }
    giveReward(p.User.DiscordID)
}))
http.ListenAndServe(":3000", nil)

The handler checks the signature, replies 200, and only then runs your function, so a slow reward never turns into a retry.

Verifying by hand, if you already have a router you like:

ok := topdiscordlist.VerifySignature(secret, r.Header.Get("X-TDL-Signature"),
    string(rawBody), topdiscordlist.DefaultTolerance)

Read the body before anything unmarshals it. Re-serialized JSON will not match.

Call the API

client := topdiscordlist.New(os.Getenv("TDL_TOKEN"))
ctx := context.Background()

listing, err := client.Listing(ctx)
check, err := client.HasVoted(ctx, "123456789012345678")
voters, err := client.Votes(ctx, 50, 1)

err = client.PostStats(ctx, "my-bot", topdiscordlist.Stats{ServerCount: 1200})

Errors from the API come back as *topdiscordlist.APIError with the status on it:

var apiErr *topdiscordlist.APIError
if errors.As(err, &apiErr) && apiErr.Status == 403 {
    log.Fatal("token was revoked")
}

Test events

A test delivery is identical to a real one except Event is "test" and Vote.IsTest is true. Branch on it, or you will hand yourself free rewards every time you press the button.

Links

• Developer docs
• Raw HTTP and WebSocket reference
• SDKs in other languages

Contributing

go run ./conformance checks this package against the shared signature vectors, the same eight cases every other language SDK has to pass. CI runs it on every push. If the signature logic breaks, people quietly stop receiving votes, which is why that gate exists.

MIT licensed.