Documentation

Learn how to add your server, vote securely, claim rewards via callbacks, and manage your toplist presence.

Platform features

Our toplist is built for RSPS server owners and players with features that support discovery, promotion, donations, and instant play.

Real-time voting leaderboard with weekly and overall rankings.
Featured and VIP promotions for servers that want extra visibility.
Donation store support using Apirone crypto checkout.
RSPS claim rewards so servers can grant in-game items after votes and donations.
Secure callback API with token authorization for votes and claims.
Launcher integration for instant server discovery and one-click play.

Listing your server

To add a server, log in and use the "Add Your Server" flow. Provide the server name, website URL, description, category, version, and any optional metadata like tags, banner image, and callback settings.

Server listings are reviewed automatically and appear in the toplist once created. You can edit your server details anytime from the profile/dashboard area.

Voting process

Players can vote for each server once every 12 hours from the same IP address. Votes are tracked with a lightweight anti-bot check to prevent automated submissions.

When a vote is successful, the server receives leaderboard credit and the vote is logged. Users should then claim rewards via the server's callback system if configured.

Callback rewards

Server owners can enable a callback URL and token when adding or editing a server. After each successful vote, our system sends a POST request to that URL with vote data.

The callback payload includes:

server_id — the ID of the server
vote_id — the vote record created
ip — voter IP
created_at — vote timestamp
callback_source — always "toplist"

A header called X-Toplist-Callback-Token is included when a token is configured.

Launcher integration

The launcher makes it easy for players to find servers and join instantly. It downloads the server jar automatically and launches the game without manual setup.

Once the launcher is installed, players can click a server listing to connect immediately, which makes discovery and onboarding much smoother.

Download packages are configured using environment variables: LAUNCHER_DOWNLOAD_URL_WINDOWS, LAUNCHER_DOWNLOAD_URL_MAC, and LAUNCHER_DOWNLOAD_URL_LINUX.

When a player donates through your store, a claim is created automatically. Your RSPS can retrieve pending claims and reward the player with items or currency by calling our donation API.

Use your server ID and the callback token from the donation settings page as the authentication token in the header X-Server-Token with the format {server_id}:{callback_token}.

GET /api/servers/{server}/donations/player/{player}/pending — check for unclaimed donations
POST /api/servers/{server}/donations/{claim}/claim — mark a claim as claimed after the reward is granted
POST /api/servers/{server}/donations/{claim}/deliver — mark the reward as delivered once the item has been handed out

A simple in-game command such as ::claim can call the pending endpoint, check the rewards, and award the items directly to the player.

Account and profile

Use the profile page to update your account details, email, and password. Your account also gives you access to the dashboard where you can manage your server listings.

Admins can manage the toplist including featured placements, VIP status, and news publications from the admin console.