Auction house

List auction listings

Every live listing on the auction house, filterable and sortable.

GET/v1/auction

Pages through every open listing on the auction house. Filter by search text, item, exact product, category or seller, and sort by price, age, stack total or discount to the market.

A listing leaves this list as soon as it is gone from the auction house, whether it sold, was cancelled or expired, and moves to auction history.

Authentication

API key with the read scope

Cached for

20 s

Data updates

New entries within about a minute, the busiest items every 5 minutes and everything else at least every 20 minutes.

curl "https://api.donutstats.io/v1/auction?limit=2" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "page": 1,
  "limit": 2,
  "total": 111050,
  "updatedAt": 1792724122973,
  "entries": [
    {
      "id": 21974747,
      "product": {
        "key": "smooth_quartz",
        "item": "smooth_quartz",
        "name": "Smooth Quartz Block",
        "variant": "",
        "category": "blocks",
        "details": null
      },
      "count": 64,
      "price": 968000,
      "unitPrice": 15125,
      "details": null,
      "firstSeenAt": 1792724122973,
      "lastSeenAt": 1792724122973,
      "marketPrice": 15359.375,
      "seller": null
    },
    {
      "id": 21974746,
      "product": {
        "key": "end_crystal",
        "item": "end_crystal",
        "name": "End Crystal",
        "variant": "",
        "category": "combat",
        "details": null
      },
      "count": 32,
      "price": 918000,
      "unitPrice": 28687.5,
      "details": null,
      "firstSeenAt": 1792724122973,
      "lastSeenAt": 1792724122973,
      "marketPrice": 24000,
      "seller": null
    }
  ]
}

Try itCounts towards your plan

Query parameters

qstringoptional
Search listings by product name or item id, for example totem.
1 to 64 characters
itemstringoptional
Exact item id such as diamond_sword. Matches every variant of the item.
productstringoptional
Exact product key such as diamond_sword[sharpness:5]. Matches that variant only. URL encode the brackets.
categorystringoptional
Only products in this category.
combattoolsvaluablesdropsfoodpotionsblocksmisc
sellerstringoptional
Only listings by this player. Same as GET /v1/players/{username}/listings.
dealsbooleanoptional
true: only listings at 60% or less of the lower of the market price and the best bid, for products with at least 5 listings and an open buy order.
truefalse
sortstringoptionaldefault newest
newest: most recently listed first. price: cheapest per item first. total: most expensive stack first. discount: furthest under market first, which also drops listings above market.
newestpricetotaldiscount
pageintegeroptionaldefault 1
Page to return, starting at 1.
1 to 100,000
limitintegeroptionaldefault 50
Entries per page.
1 to 200

Response

A page of listings. updatedAt is when the auction house was last refreshed.

pageinteger
The page you asked for, starting at 1.
limitinteger
Entries per page.
totalinteger
Entries across every page that match your filters.
updatedAttimestamp | null
When the underlying data last changed. null where it does not apply.
entriesListing[]
The entries on this page.
ShowHide10 child fields
- idinteger
  Stable id of the listing. It never changes or gets reused.
- productProduct
  What is being sold.
  ShowHide6 child fields
  - keystring
    Unique product key: the item id, plus the variant in square brackets when there is one. Examples: diamond, elytra[mending,unbreaking:3], potion[poison]. Use it with product= filters and /v1/items/{key}.
  - itemstring
    Minecraft item id without the minecraft: namespace, for example netherite_sword. Many products can share one item id.
  - namestring
    Display name, for example Potion of Poison.
  - variantstring
    What sets this product apart from the plain item. Empty for plain items. See variants for the rules.
  - categorystring | null
    One of combat, tools, valuables, drops, food, potions, blocks or misc.
  - detailsProductDetails | null
    Structured extras such as enchantments, shulker box contents or a custom name.
    ShowHide5 child fields
    enchantmentsEnchantment[]
    Enchantments on the item itself, sorted by id. Left out when there are none.
    storedEnchantmentsEnchantment[]
    Enchantments stored in an enchanted book. Left out for every other item.
    contentsContainerEntry[]
    What a shulker box holds, one entry per item id with counts added together, largest first.
    customNamestring
    The name shown in game when it differs from the default item name. DonutSMP renames some items, for example Dried Ghast on a skeleton skull.
    flightDurationinteger
    Flight duration of a firework rocket, from 1 to 3.
- countinteger
  Stack size, from 1 to 64.
- pricenumber
  Asking price for the whole stack.
- unitPricenumber
  Asking price per item: price divided by count.
- detailsProductDetails | null
  Details of this exact stack. They can carry more than the product does, such as the full contents of a shulker box.
  ShowHide5 child fields
  - enchantmentsEnchantment[]
    Enchantments on the item itself, sorted by id. Left out when there are none.
    ShowHide2 child fields
    idstring
    Enchantment id without the minecraft: namespace, for example sharpness.
    levelinteger
    Enchantment level, starting at 1.
  - storedEnchantmentsEnchantment[]
    Enchantments stored in an enchanted book. Left out for every other item.
    ShowHide2 child fields
    idstring
    Enchantment id without the minecraft: namespace, for example sharpness.
    levelinteger
    Enchantment level, starting at 1.
  - contentsContainerEntry[]
    What a shulker box holds, one entry per item id with counts added together, largest first.
    ShowHide2 child fields
    itemstring
    Item id, for example netherite_sword.
    countinteger
    Total number of that item in the box.
  - customNamestring
    The name shown in game when it differs from the default item name. DonutSMP renames some items, for example Dried Ghast on a skeleton skull.
  - flightDurationinteger
    Flight duration of a firework rocket, from 1 to 3.
- firstSeenAttimestamp
  When the listing first appeared.
- lastSeenAttimestamp
  When the listing was last confirmed on the auction house.
- marketPricenumber | null
  Current market price of the product, so you can compare the ask at a glance.
- sellerstring | null
  Username of the seller, once known. null until then.

Status codes

Status	When
400Bad Request	A filter is malformed or `category` is unknown.
404Not Found	`seller` is not a player on record.