SunBot API — connect your server's economy to your community

SunBot exposes a small, public, read-only API so your server's economy doesn't have to stay locked inside Discord. Pull your leaderboard into a Minecraft server, a stream overlay, your community site, or a companion bot — with a plain GET and no keys.

Privacy first. It's opt-in per server (an admin enables the public leaderboard in /admin). A server that hasn't opted in returns a generic 404 — indistinguishable from a server that doesn't exist, so nothing is scrapable. No user IDs, no avatars, no auth, no mutations — just a display name and public stats.

🔓 Enable it

Run /admin on your server → open the economy/leaderboard section → turn Public leaderboard on.
SunBot replies with your board URL and the JSON endpoint (it includes your server ID — the guild value below).
Turn it off any time; the API immediately goes back to 404 for your server.

📡 Endpoint

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

No authentication. CORS: * (call it straight from a browser). Responses are cached ~45s and rate-limited per IP.

Query parameters

Param	Values	Description
`guild` required	`<server id>`	Your Discord server ID (from the enable step).
`type` optional	`money` · `level` · `activity`	Sort key. `money` = net worth (default), `level` = XP level, `activity` = weekly messages. (`richest`/`cash` alias money; `weekly` aliases activity.)
`limit` optional	`1`–`50`	How many players to return. Default `25`, clamped to 50.

Example request

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

Example response 200

{
  "guild": "123456789012345678",
  "type": "money",
  "updatedAt": 1724990000000,
  "count": 5,
  "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 }
  ]
}

Entry fields

Field	Type	Meaning
`rank`	number	1-based position for the requested `type`.
`name`	string	Display name (≤32 chars). No user ID is ever exposed.
`net`	number	Net worth — cash + bank.
`level`	number	XP level.
`activity`	number	Weekly message count.
`streak`	number	Current daily streak.

Errors

Status	Body	When
`400`	`{"error":"missing_guild"}`	No `guild` param.
`404`	`{"error":"not_found"}`	Server hasn't opted in (or doesn't exist).
`429`	`{"error":"rate_limited"}`	Too many requests from your IP — back off and cache.

💡 What you can build

🎮 In-game rewards (Minecraft & co.)

Poll the leaderboard from your game server and reward your top Discord earners in-game — a rank tag, a kit, currency, a cosmetic. Your Discord economy becomes a reason to play on your server, and vice-versa. (It's read-only, so it drives rewards, not spending — see the roadmap below.)

📺 Stream / website overlay

Because CORS is open, you can fetch() the board directly from a webpage or an OBS browser source and render a live "Top players" widget — no backend needed. Cache ~60s to stay friendly.

🤖 Companion bot / webhook

A tiny script on a timer can fetch the weekly activity board and post "🏆 This week's top chatters" to a channel via a Discord webhook — automated bragging rights.

// browser or Node — live 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();
  entries.forEach(e => console.log(`#${e.rank} ${e.name} — ${e.net.toLocaleString()}`));
}

🛣️ Roadmap: a write API?

Today the API is read-only. A write API — change a player's balance from outside Discord (the way UnbelievaBoat does), so a Minecraft purchase could spend SunBot coins — is something we're weighing. It needs per-server API keys, scoped auth and careful money-path safety, so it's a deliberate next step, not a quiet toggle.

Would you use it? Tell us what you'd wire up — DM the bot or email iwannahelp@sunbotapp.com. Real use cases decide what we build next.

Don't have SunBot yet? Invite it — setup takes 5 minutes with /setup. Questions? DM the bot — it reaches the founder directly.