Skip to content
DonutStatsAPI
Sign up
Getting started

Quickstart

Get a key, make a request and read the answer. It takes about a minute.

Get an API key

  1. Create a free account with a username and a password.
  2. On your dashboard, press Create key.
  3. Copy the key straight away. It is shown once and looks like ds_ followed by 32 letters, digits, dashes and underscores.

Keep the key out of your code. Put it in an environment variable instead:

export DONUTSTATS_API_KEY=ds_your_key_here

Make your first request

GET /v1/status is a good first call. It returns how much data there is and how fresh each dataset is.

curl "https://api.donutstats.io/v1/status" \
  -H "x-api-key: $DONUTSTATS_API_KEY"
Response200
{
  "players": 458683,
  "playersWithStats": 138504,
  "boards": [
    {
      "id": "money",
      "label": "Money",
      "stat": "money",
      "source": "leaderboard",
      "updatedAt": 1792694462533,
      "entries": 89727
    },
    {
      "id": "deaths",
      "label": "Deaths",
      "stat": "deaths",
      "source": "leaderboard",
      "updatedAt": 1792722232417,
      "entries": 1125
    }
  ],
  "orders": {
    "open": 14033,
    "openValue": 2021066961598.28,
    "new24h": 385862,
    "closed24h": 383926,
    "filled24h": 11920827679,
    "paidOut24h": 2465690883952.89,
    "updatedAt": 1792724121936
  },
  "auction": {
    "open": 111050,
    "liquidValue": 82786430718.73,
    "new24h": 1848145,
    "closed24h": 1844025,
    "updatedAt": 1792724122973
  },
  "items": 2770,
  "server": {
    "online": 19551,
    "updatedAt": 1792724136015
  }
}

Read the response

Every response is JSON. A few rules hold everywhere:

  • Times are Unix timestamps in milliseconds, UTC.
  • Money is in DonutSMP dollars. Playtime is in seconds.
  • Lists come in a page envelope with page, limit, total, updatedAt and entries. History endpoints use a cursor instead. See pagination.
  • Errors always have an error string. See errors.

Check freshness

Lists carry updatedAt, the time that dataset last changed. Show it in your app so people know how live the numbers are.

Use it in code

Print the ten richest players with JavaScript (Node 18 or newer, or any modern runtime):

const response = await fetch("https://api.donutstats.io/v1/leaderboards/money?limit=10", {
  headers: { "x-api-key": process.env.DONUTSTATS_API_KEY },
});
if (!response.ok) throw new Error(`DonutStats API returned ${response.status}`);

const { entries } = await response.json();
for (const player of entries) {
  console.log(player.rank, player.username, player.value);
}

Or check what a diamond is worth with Python:

import os

import requests

response = requests.get(
    "https://api.donutstats.io/v1/items/diamond",
    headers={"x-api-key": os.environ["DONUTSTATS_API_KEY"]},
    timeout=20,
)
response.raise_for_status()

item = response.json()["item"]
print(item["name"], "sells for", item["prices"]["price"], "and orders pay", item["prices"]["bid"])

Next steps