API reference

Overview

The base URL is https://api.donutapi.app. The data routes are read only GET requests that return JSON, and they can be called from a browser (CORS is open). Account linking and payments are the exceptions: they use POST and need a key.

Data comes from bots in the game that read the auction house and the buy orders every few minutes. Items are identified by their Minecraft ids, such as diamond or netherite_ingot. Fields named at are Unix time in milliseconds.

Auction house prices come from two sources. The bots search the most traded items one by one in the game, which gives their real lowest price. They also sweep the auction house page by page, cheapest first, up to a page cap: that sweep is partial, so an item that only has expensive listings can be missing from it. Orders snapshots are partial in the same way. Each response carries a snapshot object that says when the data was read, and snapshot.complete is false when a page cap was reached.

curl "https://api.donutapi.app/v1/ah/items"

What happened to the official DonutSMP API?

DonutSMP used to give API keys to its players through the in-game /api command. In 2026 that API was restricted, then disabled.

Source: archivePedro's comment on r/DonutSMP, in the thread "/api command doesn't work", and the same statements on the official DonutSMP Discord.

Some community guides, wikis and mods still tell players to run /api to get a key. That no longer works.

Donut API is an independent, unofficial replacement. It provides the same kind of data by reading it through bots in the game, and it is not affiliated with or endorsed by DonutSMP.

Keys and limits

Without a key, the API answers in keyless mode, limited per IP address: 10 calls per minute, 3,000 calls per month and 24 hours of history.

With a key, send it in one of these two headers. Keys start with dk_. You get a free one in the dashboard, by signing in with your Minecraft account. If you gave an email address when you signed in, you can come back later with a 6 digit code sent to that address. Email does not create an account. The full key is shown once, when it is created. Paid plans cannot be bought yet: they are on the pricing page.

curl "https://api.donutapi.app/v1/ah/items" \
  -H "Authorization: Bearer dk_your_key"

curl "https://api.donutapi.app/v1/ah/items" \
  -H "x-api-key: dk_your_key"

Every counted response tells you where you stand. /v1/status is never counted, and neither are 404 and 202 answers.

Errors

Errors are JSON objects with an error field.

Status

Tells you when the latest auction house and orders snapshots were taken, how large they were, the state of each bot, and whether the DonutSMP servers answer. Use it to check that the data is fresh. This route is not counted against your limits.

curl "https://api.donutapi.app/v1/status"

{
  "ah": { "id": 86, "type": "ah", "ts": 1794398309676,
    "pages": 80, "lignes": 3600, "complet": 0, "bot": "bot2" },
  "orders": { "id": 87, "type": "ordres", "ts": 1794398622280,
    "pages": 40, "lignes": 1800, "complet": 0, "bot": "bot1" },
  "bots": [
    { "name": "bot1", "online": true, "state": "online",
      "last_seen": 1794398705049, "task": "orders", "uptime_24h": null },
    { "name": "bot2", "online": true, "state": "online",
      "last_seen": 1794398705189, "task": "ah", "uptime_24h": null }
  ],
  "bots_summary": { "state": "operational", "online": 5, "total": 5,
    "percent_online": 100, "blocked": 0, "uptime_24h": null },
  "donutsmp": [
    { "id": "main", "name": "DonutSMP", "host": "java.donutsmp.net",
      "online": true, "players_online": 12777, "players_max": 50000,
      "latency_ms": 5, "checked_at": 1794398704774 },
    { "id": "eu", "name": "DonutSMP Europe", "host": "eujava.donutsmp.net",
      "online": true, "players_online": 12777, "players_max": 50000,
      "latency_ms": 4, "checked_at": 1794398704780 }
  ],
  "traffic": { "level": "normal", "requests_per_minute": 0,
    "usual_per_minute": null, "player_queue": 0 },
  "now": 1794398726750
}

The field names of this route are internal and may be renamed. A live view of it is on the status page.

Server history

How the DonutSMP addresses we ping behaved over a period: players online, latency, share of pings answered, and the outages we saw. The period is cut into equal slices, 300 at most, and each slice gives one point. The answer is cached for 30 seconds and is never counted in your quota.

We only know what our pings saw. A slice with no ping at all has no point, so a hole in points means our API was restarting or the history had not started yet, not that the server was offline. The history starts at logging_since and pings are kept for 31 days. Latency is measured from our server in Germany.

curl "https://api.donutapi.app/v1/status/history?hours=24"

{
  "from": 1794313227984,
  "to": 1794399627984,
  "step_minutes": 5,
  "logging_since": 1794399485265,
  "servers": [
    { "id": "main", "name": "DonutSMP", "host": "java.donutsmp.net",
      "uptime": 1,
      "points": [
        { "at": 1794399300000, "players": 13228, "latency_ms": 4, "online": true },
        { "at": 1794399600000, "players": 13292, "latency_ms": 5, "online": true }
      ],
      "outages": [] }
  ]
}

Auction house offers

Offers for one item, cheapest first. With item, the offers come from a search of that item in the game, so the first one is the real lowest price on the market. A search returns 45 offers at most.

The most traded items (ores, netherite, tridents, maces, totems, common blocks and more) are searched all the time: they answer at once from a cache, with data that is at most 20 minutes old. Any other item is searched in the game when you ask for it, which takes 4 to 9 seconds, and the answer is then cached for 5 minutes.

If the id is unknown or the search finds nothing, the route falls back to the page by page sweep: snapshot then has no source field, and listings can be empty.

curl "https://api.donutapi.app/v1/ah?item=netherite_ingot&limit=2"

{
  "snapshot": { "at": 1794395033684, "source": "search", "complete": true },
  "listings": [
    { "item": "netherite_ingot", "name": "Netherite Ingot", "count": 1,
      "price": 23200000, "unit_price": 23200000 },
    { "item": "netherite_ingot", "name": "Netherite Ingot", "count": 1,
      "price": 23300000, "unit_price": 23300000 }
  ]
}

Auction house items

One summary line per item: how many listings it has, the lowest unit price, and the total number of items on sale. Items are sorted by name.

An item with a priced_at field was priced by a search in the game: its lowest_unit_price is the real lowest price on the market, and its counts stop at 45, the size of a search. The other items come from the page by page sweep, which is partial, so their lowest price is less certain.

curl "https://api.donutapi.app/v1/ah/items"

{
  "snapshot": { "at": 1794394483102, "pages": 80, "complete": false },
  "items": [
    { "item": "acacia_button", "listings": 2,
      "lowest_unit_price": 5900, "total_count": 2 },
    { "item": "ancient_debris", "listings": 45,
      "lowest_unit_price": 9100000, "total_count": 45,
      "priced_at": 1794394584831 }
  ]
}

Buy orders

Open buy orders from the latest orders snapshot.

curl "https://api.donutapi.app/v1/orders?limit=2"

{
  "snapshot": { "at": 1794387262306, "pages": 40, "complete": false },
  "orders": [
    { "item": "gold_block", "name": "Blocks of Gold",
      "price_each": 37000, "delivered": 744000, "wanted": 1700000 },
    { "item": "pumpkin", "name": "Pumpkins",
      "price_each": 72.52, "delivered": 328000000, "wanted": 400000000 }
  ]
}

History

Points from past snapshots for one item, ready to chart. Each point has the time of the snapshot, the price and the number of listings. A snapshot in which the item did not appear gives no point. An item that is searched in the game gets a point at every search.

curl "https://api.donutapi.app/v1/history?item=ender_chest&type=ah&hours=24"

{
  "item": "ender_chest",
  "type": "ah",
  "points": [
    { "at": 1794383619041, "price": 18500, "listings": 201 },
    { "at": 1794387666192, "price": 13800, "listings": 1 }
  ]
}

Public chat

The public chat of the server, as the bots see it. Player names are never exposed: author is an anonymous id that stays the same for a given player. Messages are kept for 30 days.

Without after, you get the latest messages, oldest first. To follow the chat, call again with after set to the latest_id you received: you only get newer messages. One call every 10 to 15 seconds is enough.

To search, pass q: you get the latest messages that contain every word, oldest first, from the whole history that is kept. The search ignores case and matches the start of words, so raid finds "raid" and "raids" but not "unraid". Use up to 6 words of 2 to 32 characters. The answer repeats the words that were searched in a q field.

The text is written by players. Show it as plain text and never as HTML.

curl "https://api.donutapi.app/v1/chat?limit=2"

{
  "messages": [
    { "id": 692, "at": 1794388047324, "author": "u_83666249ba",
      "text": "i have a strategy to get many free glided blackstone come if you want" },
    { "id": 693, "at": 1794388047627, "author": "u_2044581161",
      "text": "TPA" }
  ],
  "latest_id": 693
}

Daily chat stats

Stats on one day of public chat: how many messages, the most said words, the most active chatter and the busiest hour. Without day you get the latest complete day. While no day is complete yet, you get the current day with partial set to true, recomputed every hour. A day with no data answers 404.

A word is counted once per message, and common words and insults are left out. The most active chatter is an anonymous id, the same as in /v1/chat, never a player name. Every field except day can be missing, so read them as optional.

curl "https://api.donutapi.app/v1/chat/daily"

{
  "day": "2026-11-11",
  "messages": 31727,
  "authors": 2575,
  "top_words": [
    { "word": "tpa", "count": 9340 },
    { "word": "money", "count": 4460 },
    { "word": "loot", "count": 4431 }
  ],
  "top_chatter": { "author": "u_5192bf6769", "messages": 2014,
    "head": "https://api.donutapi.app/v1/chat/daily/head?day=2026-11-11" },
  "busiest_hour": { "hour": 10, "messages": 14928 },
  "topics": [
    { "label": "Spam and Scam Offers", "share": 0.3 },
    { "label": "Pvp Duels Requests", "share": 0.25 }
  ],
  "summary": "Chat was dominated by teleport requests (tpa/tp) for PvP duels, loot drops, and base visits, along with a large volume of spam and scam attempts such as money-doubling offers, giveaways, and mystery box sales that should be treated with caution. Players also traded and asked about netherite gear, elytra, and spawners, while many messages were repetitive or meaningless. Overall the server saw very high activity with a peak around 10:00 UTC.",
  "summary_model": "claude-haiku-5-5",
  "generated_at": 1794396599940,
  "partial": true
}

Money leaderboard Beta

The richest players on the server, ranked by balance, from the in-game leaderboard. Amounts are rounded by the game to two or three significant digits.

curl "https://api.donutapi.app/v1/leaderboard/money?limit=2"

{
  "snapshot": { "at": 1794387284205 },
  "players": [
    { "rank": 1, "player": "Abuodee", "money": 5900000000000 },
    { "rank": 2, "player": "Wampiptiii01", "money": 3700000000000 }
  ]
}

Player stats Beta

Stats of one player, read from the player's stats page in the game and rounded the same way the game shows them. The name is a Java name, or a Bedrock name with its leading dot, 2 to 16 characters.

Answers come from a 10 minute cache. When a player is not in the cache, a bot asks the game, which takes two to six seconds. If the game does not answer in time, the route answers 202 and you retry after the delay it gives. A 202 answer is not counted against your limits. Lookups are served one at a time by each bot, so do not start more than two or three uncached lookups at once.

Numbers are rounded by the game to two or three significant digits. The last four fields come from the full profile: when the game only returns the short one, they are left out, so treat them as optional.

curl "https://api.donutapi.app/v1/player/Abuodee"

{
  "player": "Abuodee",
  "at": 1794389609645,
  "cached": false,
  "stats": {
    "money": 5900000000000,
    "kills": 8000,
    "deaths": 1500,
    "playtime": "180d 12h",
    "shards": 129000,
    "blocks_placed": 509000,
    "blocks_broken": 221000,
    "mobs_killed": 52500
  }
}

Staff Beta

The DonutSMP staff members our bots have seen in the player list of the game, where staff carry a marker in front of their name. The bots only read that list: they send no command and no message. It is refreshed every 30 seconds.

/v1/staff lists every staff member the bots have met so far, most recently seen first, and says who is online now. The list fills up as staff members connect. /v1/staff/online only returns the ones seen online right now.

Read it as "staff seen online", not as "all staff online". A staff member who is hidden does not appear, so a name that is missing or marked offline does not prove that person is offline. One call per minute is enough.

curl "https://api.donutapi.app/v1/staff"

{
  "staff": [
    { "player": "Napooo_", "uuid": "34ebe03c-c52a-4178-be69-b2d954ea6faf",
      "role": "Moderator", "last_seen": 1794396103768,
      "first_seen": 1794390567159, "online": true },
    { "player": "BobIsFound", "uuid": "b5e695a7-f81a-41e4-a31b-9e778be1855a",
      "role": "Moderator", "last_seen": 1794396103765,
      "first_seen": 1794390567155, "online": true }
  ]
}

curl "https://api.donutapi.app/v1/staff/online"

{
  "snapshot": { "at": 1794391171965 },
  "staff": [
    { "player": "BobIsFound", "role": "Moderator" },
    { "player": "Dough4", "role": "Moderator" },
    { "player": "Napooo_", "role": "Moderator" },
    { "player": "u_vv", "role": "Moderator" }
  ]
}

Staff activity Beta

When the staff members our bots see are online: number of sessions, time online, and how that time spreads over the hours of the day and the days of the week. Members are sorted by total time. Hours and days are in the time zone given by timezone. The answer is cached for 10 minutes.

Read the times as minimums. A member is only counted while one of the bots sees them in the player list, so time spent hidden or out of the bots' view is missing. The log starts at logging_since: until several days have passed, the hours and weekdays say little about anyone's habits.

curl "https://api.donutapi.app/v1/staff/activity?days=30"

{
  "logging_since": 1794396733747,
  "window_days": 30,
  "timezone": "Europe/Paris",
  "staff": [
    { "player": "CaptainMoose35", "role": "Moderator", "sessions": 1,
      "total_minutes": 3, "median_session_minutes": 3,
      "spectator_minutes": 0,
      "first_seen": 1794396733747, "last_seen": 1794396883982,
      "usual_hours": [12],
      "minutes_by_hour": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "minutes_by_weekday": { "sun": 0, "mon": 0, "tue": 0, "wed": 3,
        "thu": 0, "fri": 0, "sat": 0 } }
  ]
}

Account linking

A link proves that a visitor owns a Minecraft account, with no password, no mod and no message in the chat. Use it to tie a Discord account or an account on your site to a DonutSMP name. You create a link for a username, show the player a /pay command for a small amount to a player picked at random, and the link becomes verified once that account has made that payment in the game.

1. Create the link from your server. Keep its id on your server.
2. Wait until watching is true. The API needs a few seconds to get ready to see the payment. A payment made before that is not seen, so do not show the command yet.
3. The player runs command in the game. From the account named in username, exactly as it is.
4. The payment is seen and the link becomes verified. Read the link with GET, wait on it with ?wait=25, or receive a webhook.

The amount and the player to pay are picked at random for each link, and the payment itself is the proof. Nobody writes to the player or follows them, and the only name they see is the player to pay. What ties the proof to your visitor is the id, which only your server knows. So never accept a proof that comes from the player's browser. Read the link from your server, or check the signature of the webhook, before you link anything.

Your interface has to tell the player three things:

• The payment costs game money. amount is between 11 and 989, and DonutSMP adds its 2% tax to the payer. The money goes to the player named in pay_to, not to you and not to us.
• If the link is still pending a minute after the payment, they should ask for a new link. Another player is picked each time.
• The command stops working at expires_at. Show a countdown and let the player ask for a new link.

If watch_error shows up in the link, the player that was picked could not be watched. Create a new link to get another one.

curl -X POST "https://api.donutapi.app/v1/links" \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"username":"NotRyzn","reference":"demo"}'

{
  "id": "lnk_9e32189eb9d8b4a6441b9bbc1ea546b6",
  "status": "pending",
  "username": "NotRyzn",
  "reference": "demo",
  "created_at": 1794410550045,
  "expires_at": 1794411150045,
  "verified_at": null,
  "uuid": null,
  "method": "pay",
  "pay_to": "<player>",
  "amount": 353,
  "command": "/pay <player> 353",
  "watching": false,
  "same_region": false
}

Returns the link. Add ?wait=25 and the answer is held until the status changes, for 25 seconds at most. To catch watching turning true, read the link every few seconds without wait, then use ?wait=25 once the command is shown. A link can only be read with the key that created it: any other key gets 404.

curl "https://api.donutapi.app/v1/links/lnk_9e32189eb9d8b4a6441b9bbc1ea546b6?wait=25" \
  -H "Authorization: Bearer dk_your_key"

Link webhooks

When a link has a webhook_url, the API calls it as soon as the payment is seen, without anyone reading the link, and again if the link expires. Do what you want there, for example give a Discord role or send an email.

{
  "event": "link.verified",
  "link": { "id": "lnk_9e32189eb9d8b4a6441b9bbc1ea546b6", "status": "verified" }
}

event is link.verified or link.expired, and link is the whole link, as GET returns it. The delivery rules and the x-donut-signature header are the same as for payment webhooks: reply with a 2xx status within 5 seconds, 4 tries, private addresses refused, and a signature to check with your webhook_secret.

These routes are not the sign-in of the dashboard. A link you create never opens a dashboard session.

Payments

A payment tells you that a player really paid another player in the game. You create it with the recipient, show the payer the command to type, and the API tells you when the money has arrived. Use it when your project has to know that a /pay really happened, for example to sell something for in-game money.

No code yet? The dashboard has a form that creates a payment by hand, shows the command to give to the payer and tells you when it is paid. With a Discord webhook added under Integrations, your channel gets a message at that moment.

There are two modes, chosen with the mode field when you create the payment.

Direct mode

1. Once: the recipient follows the payment account. In the game, the recipient types the follow_command given by the recipients route and keeps "See Payment Activity" turned on for that account in /friends. The account follows back about a minute or two later. A recipient who unfollows is no longer eligible.
2. Create the payment. The answer carries command, the /pay command that sends the money straight to the recipient.
3. The payer types the command in the game. The game tells our payment account about it, and the payment becomes paid.
4. You learn about it. Read the payment with GET, wait on it with ?wait=25, or receive a webhook.

In a real test on November 11, 2026, a direct payment was seen less than a second after it was made. That is one measurement, not a promise.

Direct mode rests entirely on the notice the game sends to the payment account. If that account is out of the game at the moment the payer pays, the payment is not seen. Creating a payment already answers 503 while the account is out of the game.

A payment that matches nothing, from the wrong payer or for the wrong amount, is simply ignored: the money stays with the recipient.

Relay mode

1. Create the payment with "mode":"relay". command then pays pay_to, our payment account.
2. The payer types the command in the game. The payment account recognises the payment by its amount, and by the sender when you named a payer.
3. The account forwards the money to the recipient. The payment becomes paid. If the game refuses that transfer, the payer is refunded and the payment ends as refunded.

The recipient must have payments turned on in the /settings of the game. Otherwise the game refuses the transfer, the payer is refunded, and the payment ends as refunded with the reason in detail. Money that reaches the payment account and matches no pending payment (wrong amount, wrong payer, or sent after the expiry) goes back to its sender, minus the game tax.

Who pays what

DonutSMP takes a 2% tax on every /pay, charged to the sender on top of the amount sent. In direct mode the money moves once. In relay mode it moves twice, so the tax is taken twice.

The relay fee is provisional and can change, so read fee, game_tax and net_amount in the answer instead of computing them.

Check a recipient

Tells you whether a player can receive direct payments, and what to ask them to type if not. Read the name of the payment account from the answer instead of writing it in your code.

curl "https://api.donutapi.app/v1/payments/recipients/ZKR5" \
  -H "Authorization: Bearer dk_your_key"

{
  "username": "ZKR5",
  "direct_ready": false,
  "since": null,
  "payment_account": "<account>",
  "follow_command": "/follow <account>"
}

Create a payment

Send a JSON body of 4 KB at most. The answer is 201 with the payment, in status pending. Payment calls are counted against your limits like the other routes.

curl -X POST "https://api.donutapi.app/v1/payments" \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"recipient":"ZKR5","payer":"NotRyzn","reference":"verif-notryzn","expires_in":3600}'

{
  "id": "pay_c326970557141a1588d19847",
  "mode": "direct",
  "status": "paid",
  "amount": 15,
  "fee": 0,
  "game_tax": 0,
  "net_amount": 15,
  "recipient": "ZKR5",
  "payer": "NotRyzn",
  "reference": "verif-notryzn",
  "pay_to": "ZKR5",
  "command": "/pay ZKR5 15",
  "created_at": 1794414535733,
  "expires_at": 1794418135733,
  "received_at": 1794414563347,
  "paid_by": "NotRyzn",
  "paid_at": 1794414563347,
  "tx_id": "tx_9bbe5d52263ead748319",
  "track_url": "https://donutapi.app/tx/tx_9bbe5d52263ead748319"
}

{
  "id": "pay_8bba7b665c7ed61edd3eb39f",
  "status": "pending",
  "amount": 1000,
  "fee": 0,
  "game_tax": 20,
  "net_amount": 980,
  "recipient": "ZKR5",
  "payer": "NotRyzn",
  "reference": "test-2",
  "pay_to": "Ryuuwn",
  "command": "/pay Ryuuwn 1000",
  "created_at": 1794407605057,
  "expires_at": 1794411205057,
  "received_at": null,
  "paid_by": null,
  "paid_at": null
}

Follow or cancel a payment

Returns the payment, with the same fields as at creation except webhook_secret. Add ?wait=25 and the answer is held until the status changes, for 25 seconds at most: loop on it to know at once without a webhook.

curl "https://api.donutapi.app/v1/payments/pay_c326970557141a1588d19847?wait=25" \
  -H "Authorization: Bearer dk_your_key"

A direct payment goes from pending to paid, expired or cancelled. The other statuses only exist in relay mode, where the money passes through the payment account.

The two unconfirmed statuses mean the payment account sent a command and the game never said whether it went through. It never sends the command again blind, which could pay twice: a person on our side checks what happened. Treat these payments as unsettled until then.

Cancels a payment that is still pending.

Payment webhooks

When a payment has a webhook_url, the API sends it a POST with a JSON body each time the payment reaches one of these statuses: paid, expired and cancelled, plus in relay mode received, refunded, forward_unconfirmed and refund_unconfirmed.

{
  "event": "payment.paid",
  "payment": { "id": "pay_c326970557141a1588d19847", "status": "paid" }
}

event is payment. followed by the status, and payment is the whole payment, with the fields listed under Create a payment.

Check the signature on the raw body, before parsing it, and refuse a timestamp that is too old.

const crypto = require("crypto");

// rawBody: the request body as received, not re-serialised
function isFromDonutApi(rawBody, signatureHeader, webhookSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("="))
  );
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(parts.t + "." + rawBody)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 || "");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

Track a payment

Every payment has a public page, https://donutapi.app/tx/<tx_id>, that anyone can open without a key. A payment carries its id and the full link in tx_id and track_url. Give the link to your customer: the page shows where the payment stands, each step with its time, and it checks the hashes of the steps in the browser. It refreshes by itself while the payment is pending.

A tx_id is tx_ followed by 20 characters, digits and letters from a to f.

curl "https://api.donutapi.app/v1/tx/tx_9bbe5d52263ead748319"

{
  "id": "tx_9bbe5d52263ead748319",
  "status": "paid",
  "mode": "direct",
  "amount": 15,
  "recipient": "ZKR5",
  "payer": "NotRyzn",
  "created_at": 1794414535733,
  "expires_at": 1794418135733,
  "paid_at": 1794414563347,
  "events": [
    {
      "block": 13,
      "at": 1794414535736,
      "type": "created",
      "hash": "f2e71e643db349d80f6977974c5efaca13e44dd0d0d63ebc42664970e263754a",
      "prev": "74a96ba6a6400570703d3b07f6683b5680e9355933327cc8a4d801dfdf7043af",
      "payload": "{\"tx\":\"tx_9bbe5d52263ead748319\",\"type\":\"created\",\"at\":1794414535736,\"data\":{\"mode\":\"direct\",\"amount\":0,\"recipient\":\"ZKR5\",\"payer\":\"NotRyzn\",\"net_amount\":0},\"salt\":\"aea6acc5c37e9376\"}"
    },
    {
      "block": 14,
      "at": 1794414563350,
      "type": "paid",
      "hash": "b7f41e601a2312175c7a7d4e957adc740b44c0c1c15ab395d18858fd77833ae4",
      "prev": "f2e71e643db349d80f6977974c5efaca13e44dd0d0d63ebc42664970e263754a",
      "payload": "{\"tx\":\"tx_9bbe5d52263ead748319\",\"type\":\"paid\",\"at\":1794414563350,\"data\":{\"mode\":\"direct\",\"amount\":15,\"recipient\":\"ZKR5\",\"payer\":\"NotRyzn\",\"from\":\"NotRyzn\",\"to\":\"ZKR5\"},\"salt\":\"845c2fa605bd5ac3\"}"
    }
  ],
  "verify": "hash = sha256(block + \"\\n\" + prev + \"\\n\" + payload), and prev is the hash of the block before (all zeros for block 1)"
}

In the example above the payment was created without an amount, so the created step holds an amount of 0 and the paid step holds the sum that was paid. An unknown id answers 404 with {"error":"unknown transaction"}.

Check a hash yourself

The hash of a block is sha256(block + "\n" + prev + "\n" + payload), written in hexadecimal. Recompute it from the three fields, compare it with hash, then look for the same block number in /v1/chain and compare hash and prev. The tracking page does exactly that.

const crypto = require("crypto");

function stepIsValid(step) {
  const text = step.block + "\n" + step.prev + "\n" + step.payload;
  return crypto.createHash("sha256").update(text).digest("hex") === step.hash;
}

The public chain

Every step of every payment is one block of a single chain. A block holds the hash of the block before it, and block 1 points to 64 zeros, so an old step cannot be changed without breaking every block written after it. The blocks hold no name, no amount and no transaction id: only someone who has a tx_id sees the detail of a payment. The chain is kept by Donut API on its own server. It is a record that anyone can check, not a network of computers. You can browse it on the chain page.

curl "https://api.donutapi.app/v1/chain?limit=3"

{
  "height": 15,
  "verified": true,
  "checked_blocks": 15,
  "genesis_prev": "0000000000000000000000000000000000000000000000000000000000000000",
  "blocks": [
    {
      "block": 15,
      "at": 1794417947112,
      "type": "expired",
      "hash": "e97cb24b5e04de3ed71c38880ec35efb3a157e36ad4b33f7245e04f7d1c1fa13",
      "prev": "b7f41e601a2312175c7a7d4e957adc740b44c0c1c15ab395d18858fd77833ae4"
    },
    {
      "block": 14,
      "at": 1794414563350,
      "type": "paid",
      "hash": "b7f41e601a2312175c7a7d4e957adc740b44c0c1c15ab395d18858fd77833ae4",
      "prev": "f2e71e643db349d80f6977974c5efaca13e44dd0d0d63ebc42664970e263754a"
    },
    {
      "block": 13,
      "at": 1794414535736,
      "type": "created",
      "hash": "f2e71e643db349d80f6977974c5efaca13e44dd0d0d63ebc42664970e263754a",
      "prev": "74a96ba6a6400570703d3b07f6683b5680e9355933327cc8a4d801dfdf7043af"
    }
  ],
  "next_before": 13,
  "verify": "hash = sha256(block + \"\\n\" + prev + \"\\n\" + payload), and prev is the hash of the block before (all zeros for block 1)"
}

Account webhooks

An account webhook runs your own program when something happens on your account. You give an https address once, in the Integrations card of the dashboard, and Donut API calls it when a payment is paid or when an account link is verified. You do not have to pass a webhook_url with each payment any more, although that still works next to it.

An account can have up to 3 addresses. For each one you pick the events, you can pause it, replace its signing secret, send a test call, and see the latest calls with the answer of your server. The calls are kept for 30 days.

A new address starts with payment.paid and link.verified.

The address can be a Discord webhook. Donut API then posts a message in that channel instead of the JSON body below: what happened, the reference and the link to track the payment. There is nothing to code and no signature to check. A player name or a reference can never ping anyone in it.

{
  "id": "evt_1042",
  "event": "payment.paid",
  "created_at": 1794440000000,
  "payment": { "id": "pay_c326970557141a1588d19847", "status": "paid" }
}

payment is the whole payment, as GET /v1/payments/<id> returns it. For a link event the body carries link instead, the whole link as GET /v1/links/<id> returns it. id is unique per event: keep the ids you have handled if your program must not act twice.

const crypto = require("crypto");
const http = require("http");
const SECRET = process.env.DONUT_WEBHOOK_SECRET; // whsec_...

http.createServer((req, res) => {
  let raw = "";
  req.on("data", (chunk) => (raw += chunk));
  req.on("end", () => {
    // x-donut-signature: t=<seconds>,v1=<hex>
    const sig = Object.fromEntries(String(req.headers["x-donut-signature"] || "").split(",").map((p) => p.split("=")));
    const expected = crypto.createHmac("sha256", SECRET).update(sig.t + "." + raw).digest("hex");
    const a = Buffer.from(expected), b = Buffer.from(sig.v1 || "");
    const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
    if (!fresh || a.length !== b.length || !crypto.timingSafeEqual(a, b)) { res.writeHead(401).end(); return; }

    const body = JSON.parse(raw);
    if (body.event === "payment.paid") {
      // Run your program here. body.payment is the payment, body.id is unique per event.
    }
    res.writeHead(200).end(); // any 2xx answer means received
  });
}).listen(3000);

Player trackers are not part of these events. A tracker keeps its own webhook_url.

Player trackers

A tracker follows one player and gives you what the game announces about them: when they join and leave, the payments they send and receive, and what they buy, sell and list at the auction house. One of our accounts in the game subscribes to the player, and the API turns what that account sees into events that you read, wait on, or receive by webhook.

Know these limits before you build on a tracker:

• The player sees that an account subscribed to them.
• If the player turned off what subscribers can see, or turned on private transactions, nothing comes back.
• A tracker only sees what happens after it was created.
• Events are kept for 30 days.
• Staff members and protected accounts cannot be tracked, and Bedrock players are not supported yet.

Create and manage trackers

curl -X POST "https://api.donutapi.app/v1/trackers" \
  -H "Authorization: Bearer dk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"username":"ExamplePlayer","reference":"customer-42"}'

{
  "id": "trk_0123456789abcdef01234567",
  "username": "ExamplePlayer",
  "status": "pending",
  "created_at": 1794430000000,
  "stopped_at": null,
  "reference": "customer-42",
  "online": null,
  "last_seen_at": null,
  "last_24h": {
    "since": 1794343600000,
    "events": 0,
    "sessions": 0,
    "payments_sent": { "count": 0, "total": 0 },
    "payments_received": { "count": 0, "total": 0 },
    "purchases": { "count": 0, "total": 0 },
    "sales": { "count": 0, "total": 0 },
    "listings": { "count": 0, "total": 0 },
    "deaths": 0
  }
}

Asking again for a player that the same key already tracks answers 200 with the existing tracker.

Lists the trackers of your key, without last_24h, as {"trackers": [...], "max_active": n}. max_active is how many trackers your key can run at the same time.

Returns one tracker, with last_24h.

Stops the tracker. Its status becomes stopped.

Tracker events

curl "https://api.donutapi.app/v1/trackers/trk_0123456789abcdef01234567/events?after=EVENT_ID&wait=25" \
  -H "Authorization: Bearer dk_your_key"

{
  "tracker": "trk_0123456789abcdef01234567",
  "username": "ExamplePlayer",
  "events": [
    { "id": "<event id>", "at": 1794430100000, "type": "join" },
    { "id": "<event id>", "at": 1794430160000, "type": "payment_sent", "to": "OtherPlayer", "amount": 2500 },
    { "id": "<event id>", "at": 1794430200000, "type": "payment_received", "from": "OtherPlayer", "amount": 400 },
    { "id": "<event id>", "at": 1794430260000, "type": "purchase", "item": "Netherite Sword", "item_id": "netherite_sword", "quantity": 1, "amount": 13100000 },
    { "id": "<event id>", "at": 1794430400000, "type": "listing", "item": "Totem of Undying", "item_id": "totem_of_undying", "quantity": 1, "amount": 40000 },
    { "id": "<event id>", "at": 1794430700000, "type": "sale", "amount": 40700 },
    { "id": "<event id>", "at": 1794430900000, "type": "leave" }
  ],
  "next_after": "<event id>"
}

Events are listed oldest first. To follow a player, call again with after set to next_after.

Every event has an id, a time at and a type. item is the name the game shows, and item_id is that name in lower case with underscores, such as netherite_sword. For an ordinary item it matches the Minecraft id, so you can use it to find an icon. An item renamed by a player matches nothing.

Two more types are planned and have not been seen in a real test yet: death, and other, which carries the raw line of the game in text. Ignore the types you do not know.

Tracker activity

The habits of the tracked player, computed from the events of the tracker: when they are in the game, for how long, and how much money moves each day. It only covers what happened since the tracker was created, so a young tracker has little to say.

curl "https://api.donutapi.app/v1/trackers/trk_0123456789abcdef01234567/activity?days=7&tz=Europe/Paris" \
  -H "Authorization: Bearer dk_your_key"

{
  "totals": {
    "online_minutes": 1260,
    "sessions": 14,
    "average_session_minutes": 90,
    "longest_session_minutes": 240,
    "peak_hour": 20,
    "usual_login_hour": 17,
    "busiest_weekday": "sat"
  },
  "hours": [30, 0, 0, 0, "...24 numbers, one per hour of the day"],
  "logins_by_hour": [1, 0, 0, 0, "...24 numbers"],
  "weekdays": [{ "day": "mon", "online_minutes": 150 }, "...7 entries, Monday first"],
  "heatmap": [[0, 0, 0, "...24 numbers"], "...7 rows, Monday first"],
  "days": [
    { "date": "2026-11-11", "online_minutes": 210, "sessions": 2, "sent": 40000, "received": 13100000, "spent": 0, "earned": 250000 }
  ],
  "sessions": [
    { "start": 1794430100000, "end": 1794437300000, "minutes": 120 },
    { "start": 1794441000000, "end": null, "minutes": 35 }
  ],
  "since": 1793900000000,
  "until": 1794504800000,
  "timezone": "Europe/Paris"
}

With no session or a single one, the lists are mostly empty: show the totals and wait for more before drawing habits.

Tracker webhooks

When a tracker has a webhook_url, the API sends the events to it as they come, 50 at most per call.

{
  "event": "tracker.events",
  "tracker": { "id": "trk_0123456789abcdef01234567", "username": "ExamplePlayer", "reference": "customer-42" },
  "events": [
    { "id": "<event id>", "at": 1794430100000, "type": "join" }
  ]
}

The call is signed like a payment webhook: check the x-donut-signature header with your webhook_secret before you trust the body.