Skip to content
DonutSMP API Logo
Sign In Register

DonutSMP Public API Reference & Developer Documentation

Integrate your tools, Discord bots, and analytics portals with DonutSMP using our high-availability, low-latency REST API gateway. Query real-time in-game economies, track auction house transactions, analyze buy orders, inspect live player stats, and access competitive leaderboards with millisecond responsiveness.

Authentication & Rate Limits

All requests to the DonutSMP API gateway must be executed over HTTPS to our base URL: https://api.donutapi.xyz. Authenticate by supplying your API token inside the standard Authorization HTTP header as a Bearer token: 

curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" https://api.donutapi.xyz/v1/stats/Notch
Base Gateway URL https://api.donutapi.xyz
Rate Limiting 60 requests / 5 minutes per key slot (stacks linearly with multi-key subscriptions)

High Performance In-Memory Caching

To minimize latency and protect server performance, our gateway utilizes an in-memory caching tier. Responses are fresh and synced according to the following TTL windows:

  • Auction House (/ah): Cached for 45 seconds per search keyword.
  • Buy Orders (/order): Cached for 45 seconds per search keyword.
  • Player Statistics (/stats): Cached for 90 seconds per Minecraft username.
  • Leaderboards (/leaderboards): Cached for 5 minutes per ranking category.

Marketplace Endpoints: Auction House & Buy Orders

Search and analyze the DonutSMP in-game marketplace, monitor prices, and build price trackers or automated sniper notifications.

GET /v1/auction/list/{page}

Search Active Auction House Listings

Fetch active player listings from the DonutSMP auction house. Results are automatically sorted from lowest to highest price.

Parameters

FieldTypeInDescription
page integer path Page number to retrieve (e.g., 1). optional
search string query / body Item name or keyword query (e.g. elytra, diamond). optional

Implementation Notes

  • Accepts parameters as a URL query string: ?search=elytra or via a JSON request body {"search": "elytra"}.
  • Always returns the cheapest active listings first.
  • Prices are delivered as raw, unformatted integers to avoid floating-point errors (e.g. 340M $ ightarrow$ 340000000).
cURL Request 
curl -X GET "https://api.donutapi.xyz/v1/auction/list/1?search=elytra" \
  -H "Authorization: Bearer dn_live_YOUR_TOKEN"
200 OK api.AhResponse 
{
  "status": 200,
  "result": [
    {
      "item": {
        "id": "minecraft:elytra",
        "count": 1,
        "display_name": "Elytra",
        "lore": [],
        "contents": [],
        "enchants": {
          "enchantments": {
            "levels": {
              "unbreaking": 3,
              "mending": 1
            }
          },
          "trim": null
        }
      },
      "price": 340000000,
      "seller": {
        "name": "DonutTrader",
        "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5"
      },
      "time_left": 86400
    }
  ]
}
GET /v1/orders/list/{page}

Search Active Buy Orders

List high-volume instant player buy orders placed across DonutSMP. Identify items offering the highest immediate payouts.

Parameters

FieldTypeInDescription
page integer path Page number of results (e.g., 1). optional
search string query / body Search by item ID or name (e.g. water_bucket, elytra). optional

Implementation Notes

  • Always sorted to return the highest payout per item first (Most Per Item).
  • Includes real-time delivery status: delivered, total, and remaining.
cURL Request 
curl -X GET "https://api.donutapi.xyz/v1/orders/list/1?search=water_bucket" \
  -H "Authorization: Bearer dn_live_YOUR_TOKEN"
200 OK api.OrderResponse 
{
  "status": 200,
  "result": [
    {
      "item": {
        "id": "minecraft:water_bucket",
        "count": 1,
        "display_name": "Water Buckets",
        "lore": [],
        "contents": [],
        "enchants": {
          "enchantments": {
            "levels": {}
          },
          "trim": null
        }
      },
      "price": 403.6,
      "delivered": 65300,
      "total": 150000,
      "remaining": 84700
    }
  ]
}

Player Profiling & In-Game Statistics

Query accurate, live player stats synchronized with DonutSMP in-game accounts.

GET /v1/stats/{user}

Get Player Statistics Matching /stats

Retrieves full gameplay statistics for a specific player, including in-game balance, blocks mined, player kills, deaths, and playtime.

Parameters

FieldTypeInDescription
user string path Target Minecraft username (case-insensitive). required
cURL Request 
curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" \
  https://api.donutapi.xyz/v1/stats/Notch
200 OK api.StatsResponse 
{
  "status": 200,
  "result": {
    "broken_blocks": "49201",
    "deaths": "14",
    "kills": "329",
    "mobs_killed": "1890",
    "money": "4502100",
    "money_made_from_sell": "0",
    "money_spent_on_shop": "0",
    "placed_blocks": "38921",
    "playtime": "7207200000",
    "shards": "540"
  }
}

Server Leaderboards & Rankings

Access top player rankings across all official DonutSMP metric categories.

GET /v1/leaderboards/{category}/{page}

Leaderboard Rankings by Category

Query the top players on DonutSMP by wealth, kills, broken blocks, and more. Paginated at 10 players per page.

Supported Categories

CategoryDescription
brokenblocksTotal blocks mined or broken in-game
deathsTotal player deaths recorded
mobskilledTotal mob entities slain
moneyCurrent player economy balance ($)
placedblocksTotal blocks placed
playtimeTotal tracked playtime (in milliseconds)

Parameters

FieldTypeInDescription
category string path One of the supported categories listed above. required
page integer path Leaderboard page index (10 players per page). required
cURL Request 
curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" \
  https://api.donutapi.xyz/v1/leaderboards/money/1
200 OK api.LeaderboardResponse 
{
  "status": 200,
  "result": [
    {
      "username": "PlayerOne",
      "uuid": "2e6840d5-39d0-4bf6-b519-798835824e88",
      "value": "9842100000"
    },
    {
      "username": "PvP_Master",
      "uuid": "4566e69f-c907-48ee-8d71-d7ba5aa00d20",
      "value": "8521000000"
    }
  ]
}

Error Handling & Response Codes

All failed requests return standard HTTP error status codes and a consistent JSON payload detailing the issue:

401 Unauthorized — Missing or Invalid API Key 
{
  "message": "Invalid or revoked API Key. Please verify your token on your dashboard at https://donutapi.xyz/dashboard",
  "reason": "Unauthorized",
  "status": 401
}
404 Not Found — Target Resource Does Not Exist 
{
  "message": "Could not handle your request. This may be because the specified user/page/item does not exist.",
  "reason": "Error handling request",
  "status": 404
}
429 Too Many Requests — Rate Limit Exceeded 
{
  "message": "Rate limit exceeded. Consider stacking additional keys to increase your requests per minute.",
  "reason": "Too Many Requests",
  "status": 429
}