Leaderboard API

A small, public, read-only API, so your server's economy can show up outside Discord: a game server, a stream overlay, your community site. A plain GET, no keys.

PRIVACY FIRSTIt's opt-in per server. A server that hasn't turned it on answers a plain 404, the same as a server that doesn't exist, so nothing can be scraped. No user ids, no avatars, no changes: a display name and public stats.

Turning it on

Dashboard → Config → Public leaderboard, or /admin → Economy → Public leaderboard.
It shows your board's address and the API address, with your server id in it (the guild below).
Turn it off any time and the API goes back to 404 for your server.

The same switch gives you a page anyone can open without signing in: sunbotapp.com/leaderboard?g=<server id>.

The endpoint

GET https://sunbotapp.com/api/leaderboard

No authentication and Access-Control-Allow-Origin: *, so a browser can call it directly. Answers are cached for 45 seconds and requests are rate-limited per IP.

Parameter	Values	Meaning
`guild` (required)	a server id	Your Discord server's id.
`type`	`money` · `level` · `activity`	What to sort by: net worth (the default), XP level, or this week's messages. `richest` and `cash` mean `money`; `weekly` means `activity`.
`limit`	`1` to `50`	How many players. `25` by default.

An example

curl "https://sunbotapp.com/api/leaderboard?guild=123456789012345678&type=money&limit=3"

{
  "guild": "123456789012345678",
  "type": "money",
  "updatedAt": 1724990000000,
  "count": 3,
  "entries": [
    { "rank": 1, "name": "Mike",  "net": 2340000, "level": 42, "activity": 1234, "streak": 14 },
    { "rank": 2, "name": "Elena", "net": 1980500, "level": 39, "activity":  980, "streak":  7 },
    { "rank": 3, "name": "Denis", "net": 1750000, "level": 44, "activity": 1510, "streak": 21 }
  ]
}

In type, activity comes back as weekly.

The fields

Field	Type	Meaning
`rank`	number	The place, from 1, for the `type` asked.
`name`	string	The display name, up to 32 characters. Never a user id.
`net`	number	Net worth: cash and bank.
`level`	number	XP level.
`activity`	number	Messages this week.
`streak`	number	The daily bonus streak.

Errors

Status	Body	When
`400`	`{"error":"missing_guild"}`	No `guild`.
`404`	`{"error":"not_found"}`	The server hasn't turned it on, or doesn't exist.
`429`	`{"error":"rate_limited"}`	Too many requests from your IP: wait and cache.

What people build with it

Rewards in a game server. Poll the board from Minecraft (or anything) and give your top Discord players a tag, a kit or a cosmetic there.
A stream or website widget. CORS is open, so a web page or an OBS browser source can fetch() it and draw a live top list. Refresh every minute or so.
A weekly shout-out. A small script fetches the activity board and posts the week's top chatters through a Discord webhook.

// in a browser or Node: the top 3 by net worth
const r = await fetch('https://sunbotapp.com/api/leaderboard?guild=YOUR_ID&limit=3');
if (r.ok) {
  const { entries } = await r.json();
  for (const e of entries) console.log(`#${e.rank} ${e.name}: ${e.net.toLocaleString()}`);
}

A write API?

Today it only reads. An API that changes balances from outside Discord, so a purchase in your game could spend SunBot coins, needs per-server keys, scoped permissions and the same care as every other money path, so it will be a deliberate step. If you'd use it, tell us what for: DM the bot or email iwannahelp@sunbotapp.com.