# Donut API

> Unofficial JSON API for market data from DonutSMP, a Minecraft server: auction house listings, buy orders and price history, collected by in-game bots every five minutes. Independent project, not affiliated with DonutSMP.

Use this file as context when writing code against the Donut API.

## Status

The public API is not open yet. The base URL will be published at launch. In every example, {BASE_URL} is a placeholder: do not guess or invent it, ask the user for it. API keys and per-plan quotas are planned; how to send a key is not documented yet, so do not invent a header name. Plans and quotas shown on https://donutapi.app/pricing are provisional.

## Conventions

- Every route is a read only GET request and returns JSON.
- Items are identified by Minecraft ids in lowercase with underscores, for example diamond, netherite_ingot, ender_chest.
- Fields named "at" are Unix time in milliseconds.
- Data comes from snapshots taken about every five minutes. When snapshot.complete is false, the bots did not read every page of the auction house (the read is capped and goes cheapest first), so treat the result as a partial view of the market.
- Only /v1/ah/items and /v1/leaderboard/money below show their exact response shape. For the other routes the field names are right but the wrapper key names may change before launch.

## Routes

### GET /v1/status

When the latest auction house and orders snapshots were taken, and how large they were. Use it to check that the data is fresh. Exact response shape not final.

### GET /v1/ah?item=<id>&limit=<n>

Auction house offers from the latest snapshot.

- item: Minecraft item id, filters the offers.
- limit: maximum number of offers to return.

Each offer has: item, name (display name), count (items in the offer), price (total price), unit_price (price per single item). The response also has snapshot: { at, pages, complete }.

### GET /v1/ah/items

One summary line per item in the latest snapshot. Exact shape:

    {
      "snapshot": { "at": 1794383619041, "pages": 80, "complete": false },
      "items": [
        { "item": "ender_chest", "listings": 201, "lowest_unit_price": 18500, "total_count": 201 }
      ]
    }

listings is the number of offers, lowest_unit_price the cheapest price per single item, total_count the number of items on sale. Items are sorted by name.

### GET /v1/orders?item=<id>&limit=<n>

Open buy orders from the latest orders snapshot. Each order has: item, name, price_each (price offered per item), delivered (items already delivered), wanted (items the order asks for).

### GET /v1/history?item=<id>&type=ah|orders&hours=<n>

Points from past snapshots for one item. type is "ah" for the auction house or "orders" for buy orders, hours is how far back to look. Each point has: at, price, listings.

### GET /v1/leaderboard/money?limit=<n> (beta)

Richest players ranked by balance. Exact shape:

    {
      "snapshot": { "at": 1794383619041 },
      "players": [
        { "rank": 1, "player": "PlayerName", "money": 5900000000000 }
      ]
    }

money is rounded the way the in-game menu shows it. This route is in beta: its data is not reliable yet, so say so if you use it.

## Not available yet

Per-player statistics and per-player balance lookups are planned but not built. Their format is not decided: do not invent routes for them.

## Links

- Reference: https://donutapi.app/docs
- Plans (provisional): https://donutapi.app/pricing