DonutSMP Logo
Sign In Register

Authentication and Rate Limits

All requests must be made over HTTPS to the gateway base URL. Pass your active credential in the standard Authorization header: 

curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" https://api.donutapi.xyz/v1/lookup/PlayerOne
Base Host https://api.donutapi.xyz
Rate Limiting 250 req/min per Donut Key (scales linearly when stacked)

Auction House Endpoints

Query active listings and historical completed transactions on the server auction market.

GET /v1/auction/list/{page}

Sends all current Auction House entries

Process an auction request and return the result. Sends all current active Auction House listings.

Parameters

FieldTypeInDescription
page integer path Page index to retrieve. required
auction object body Search and sort options (ah.RequestBody). optional

Body Properties

  • search (string): Optional search text (e.g. "diamond").
  • sort (string): Options: lowest_price, highest_price, recently_listed, last_listed.
cURL Request 
curl -X GET https://api.donutapi.xyz/v1/auction/list/1 \
  -H "Authorization: Bearer dn_live_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"search":"diamond","sort":"lowest_price"}'
200 OK api.AhResponse 
{
  "status": 200,
  "result": [
    {
      "item": {
        "id": "minecraft:diamond_sword",
        "count": 1,
        "display_name": "Sharpness V Diamond Sword",
        "lore": [
          "Forged for combat",
          "DonutSMP Edition"
        ],
        "contents": [],
        "enchants": {
          "enchantments": {
            "levels": {
              "sharpness": 5,
              "unbreaking": 3
            }
          },
          "trim": {
            "material": "netherite",
            "pattern": "silence"
          }
        }
      },
      "price": 45000,
      "seller": {
        "name": "VortexTrader",
        "uuid": "d19bc294-b153-4882-95f3-c5b76cf6c981"
      },
      "time_left": 86400
    }
  ]
}
GET /v1/auction/transactions/{page}

Sends all current Auction House transaction data

Process an auction transaction history request. Sends closed and completed purchases ordered by date sold.

Parameters

FieldTypeInDescription
page integer path Page index. Max 10, Min 1, 100 items per page. required
cURL Request 
curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" \
  https://api.donutapi.xyz/v1/auction/transactions/1
200 OK api.TransactionHistoryResponse 
{
  "status": 200,
  "result": [
    {
      "item": {
        "id": "minecraft:enchanted_golden_apple",
        "count": 8,
        "display_name": "God Apple",
        "lore": [],
        "contents": [],
        "enchants": {
          "enchantments": {
            "levels": {}
          },
          "trim": {
            "material": "",
            "pattern": ""
          }
        }
      },
      "price": 120000,
      "seller": {
        "name": "KingDonut",
        "uuid": "e44c207b-8b5d-4f18-a6b1-4195a6ccda21"
      },
      "unixMillisDateSold": 1726000000000
    }
  ]
}

Player Profiling

Look up live server location, rank, and statistics matching in-game commands.

GET /v1/lookup/{user}

Sends player information matching /findplayer

Queries live player location and server rank as displayed via in-game /findplayer.

Parameters

FieldTypeInDescription
user string path Target Minecraft username. required
cURL Request 
curl -H "Authorization: Bearer dn_live_YOUR_TOKEN" \
  https://api.donutapi.xyz/v1/lookup/Notch
200 OK api.LookupResponse 
{
  "status": 200,
  "result": {
    "username": "Notch",
    "location": "Spawn - Market Hub",
    "rank": "Overlord"
  }
}
GET /v1/stats/{user}

Sends player profile matching /stats

Returns comprehensive tracking statistics for a player, including blocks, kills, deaths, playtime, and economy.

Parameters

FieldTypeInDescription
user string path Target Minecraft username. 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": "1200450",
    "money_spent_on_shop": "850000",
    "placed_blocks": "38921",
    "playtime": "1482900",
    "shards": "540"
  }
}

Server Leaderboards

Top player rankings across 10 official metric categories.

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

Leaderboard rankings by category

Returns top player positions for the selected metric. Replace {category} with any of the 10 supported paths below.

Supported Categories

CategoryDescription
brokenblocksTotal blocks mined or broken
deathsTotal player deaths
killsTotal PvP kills
mobskilledTotal mob entities slain
moneyCurrent player balance ($)
placedblocksTotal blocks placed
playtimeTotal playtime tracked for shards
sellTotal currency earned from /sell
shardsCurrent shards balance
shopTotal currency spent on /shop

Parameters

FieldTypeInDescription
category string path One of the 10 categories above. required
page integer path Leaderboard page index. 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": "00000000-0000-0000-0000-000000000001",
      "value": "984210"
    },
    {
      "username": "PvP_Master",
      "uuid": "00000000-0000-0000-0000-000000000002",
      "value": "852100"
    }
  ]
}

Error Codes and Responses

Failed requests return a structured JSON response schema:

401 Unauthorized (Invalid / Missing Client Key) 
{
  "message": "Invalid or revoked API Key. Please verify your token on your dashboard at https://donutapi.xyz/dashboard",
  "reason": "Unauthorized",
  "status": 401
}
500 Error (Invalid Target or Upstream Unreachable) 
{
  "message": "Could not handle your request. This may be because the specified user/page/item does not exist.",
  "reason": "Error handling request",
  "status": 500
}