ViceRoll Creator Leaderboard API
Show a live wager leaderboard of your viewers on your own website. Only players who signed up under your affiliate code count.
1. Get your API key
In the ViceRoll Discord, run /apikey. The bot sends you a key that starts with vr_. It's shown once. Running /apikey again makes a new key and the old one stops working.
Send the key in the x-api-key header on every request.
/apikey whenever you like.2. Your leaderboard
The ViceRoll team sets up your leaderboards: the title, start and end dates, and the prize for each place. You don't need to pass any dates: the API returns the right one automatically.
GEThttps://api.viceroll.gg/api/v1/affiliate/leaderboard
| Query | Default | What it does |
|---|---|---|
limit | 50 | How many players to return, 1 to 100. |
id | (none) | A specific leaderboard from the list below. Without it you get the current one: the live board, else the next upcoming one, else the last one that ended. |
from, to | (none) | Optional: any date range instead, as YYYY-MM-DD (UTC, inclusive, max 92 days). No prizes are returned in this mode. |
curl -H "x-api-key: vr_YOUR_KEY" "https://api.viceroll.gg/api/v1/affiliate/leaderboard?limit=10"
Response
{
"success": true,
"from": "2026-11-17",
"to": "2026-11-30",
"leaderboard": {
"id": "6738f0c2a1b2c3d4e5f60718",
"title": "$300 Launch Race",
"code": "nisqeli", // the affiliate code players must use to count
"from": "2026-11-17",
"to": "2026-11-30",
"status": "live", // upcoming | live | ended
"prizes": [
{ "rank": 1, "coins": 75000, "usd": 150 },
{ "rank": 2, "coins": 45000, "usd": 90 },
{ "rank": 3, "coins": 30000, "usd": 60 }
],
"prizePoolUsd": 300
},
"entries": [
{
"rank": 1,
"username": "Vi***e", // masked, or "Hidden" for anonymous players
"avatar": "https://...", // null for anonymous players
"wagered": 182340.5, // coins wagered in the date range
"wageredUsd": 364.68,
"earnedUsd": 1.82, // what this player earned you in affiliate commission
"prize": { "rank": 1, "coins": 75000, "usd": 150 } // null below the prize places
}
]
}
3. All your leaderboards
GEThttps://api.viceroll.gg/api/v1/affiliate/leaderboards
Every leaderboard set up for you, newest first, with the same leaderboard fields as above (no players). Use an id from here to show a past board.
{ "success": true, "leaderboards": [ { "id": "...", "title": "...", "code": "nisqeli", "from": "...", "to": "...", "status": "ended", "prizes": [ ... ], "prizePoolUsd": 300 } ] }
4. Drop-in widget
Paste this where the leaderboard should appear and replace vr_YOUR_KEY. It refreshes every minute and matches nothing on your site, so style it however you like.
<div id="viceroll-lb">Loading leaderboard…</div>
<script>
(async function load() {
const box = document.getElementById('viceroll-lb');
try {
const res = await fetch('https://api.viceroll.gg/api/v1/affiliate/leaderboard?limit=10',
{ headers: { 'x-api-key': 'vr_YOUR_KEY' } });
const data = await res.json();
if (!data.success) throw new Error(data.error.message);
const lb = data.leaderboard;
const usd = (n) => '$' + n.toLocaleString('en-US', { minimumFractionDigits: 2 });
box.innerHTML =
(lb ? `<h3>${lb.title} · ${usd(lb.prizePoolUsd)} prize pool</h3>
<p>Use code <b>${lb.code}</b> on ViceRoll · ${lb.from} to ${lb.to}</p>` : '') +
'<ol>' + data.entries.map((e) =>
`<li>${e.username} — ${usd(e.wageredUsd)} wagered${e.prize ? ' · wins ' + usd(e.prize.usd) : ''}</li>`
).join('') + '</ol>';
} catch (err) {
box.textContent = 'Leaderboard unavailable right now.';
}
setTimeout(load, 60000);
})();
</script>
Good to know
- Who counts: only players whose account is under your affiliate code. Wagers count per UTC day, from the start date through the end date.
- Freshness: responses are cached for up to 60 seconds. Don't poll more than once a minute.
- Limits: about 120 requests a minute per IP address.
- Errors:
401bad or missing key ·400bad date range ·404unknown leaderboard id ·500try again later. Every error looks like{ "success": false, "error": { "message": "..." } }. - Prizes are paid by the ViceRoll team after a leaderboard ends.