Items and prices

Get an item

One product in depth: prices, 7 days hourly, a year daily and the order book.

GET/v1/items/{key}

Everything about one product. hourly covers the last 7 days and daily the last 365, both oldest first. topOrders are the 10 best open buy orders and cheapestListings the 10 cheapest listings. For older prices, use price history.

The key is a product key, for example diamond or netherite_sword[sharpness:5,unbreaking:3]. URL encode it: brackets, commas and colons all need escaping.

Authentication

API key with the read scope

Cached for

1 min

Data updates

Prices every 5 minutes. Orders and listings as the market refreshes.

curl "https://api.donutstats.io/v1/items/diamond" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "item": {
    "key": "diamond",
    "item": "diamond",
    "name": "Diamond",
    "variant": "",
    "category": "valuables",
    "details": null,
    "prices": {
      "price": 6656.25,
      "low": 6234.375,
      "median": 14062.5,
      "bid": 6000,
      "listings": 607,
      "quantity": 26851,
      "orders": 1,
      "demand": 192,
      "orderValue": 1152000,
      "updatedAt": 1792723955534
    },
    "change1d": -0.09361702127659574,
    "change7d": 0.33962264150943394,
    "hourly": [
      {
        "t": 1792119600000,
        "price": 4671.875,
        "low": 4656.25,
        "median": 15000,
        "bid": 4400,
        "listings": 1096,
        "quantity": 43512
      },
      {
        "t": 1792123200000,
        "price": 4953.125,
        "low": 4953.125,
        "median": 14379.699248120301,
        "bid": 4300,
        "listings": 1036,
        "quantity": 42517
      }
    ],
    "daily": [
      {
        "t": 1791504000000,
        "price": 5296.875,
        "low": 4656.25,
        "median": 13687.5,
        "bid": 5000,
        "listings": 1230,
        "quantity": 47208
      },
      {
        "t": 1791590400000,
        "price": 5000,
        "low": 4375,
        "median": 14125,
        "bid": 5200,
        "listings": 1756,
        "quantity": 64730
      }
    ],
    "shardCost": null,
    "topOrders": [
      {
        "id": 3905468,
        "product": {
          "key": "diamond",
          "item": "diamond",
          "name": "Diamond",
          "variant": "",
          "category": "valuables",
          "details": null
        },
        "unitPrice": 6000,
        "amount": 192,
        "delivered": 0,
        "remaining": 192,
        "firstSeenAt": 1792723876396,
        "lastSeenAt": 1792723876396,
        "progressedAt": null,
        "marketPrice": 6656.25
      },
      {
        "id": 3795862,
        "product": {
          "key": "diamond",
          "item": "diamond",
          "name": "Diamond",
          "variant": "",
          "category": "valuables",
          "details": null
        },
        "unitPrice": 5000,
        "amount": 3,
        "delivered": 0,
        "remaining": 3,
        "firstSeenAt": 1792686670401,
        "lastSeenAt": 1792724056166,
        "progressedAt": null,
        "marketPrice": 6656.25
      }
    ],
    "cheapestListings": [
      {
        "id": 21968644,
        "product": {
          "key": "diamond",
          "item": "diamond",
          "name": "Diamond",
          "variant": "",
          "category": "valuables",
          "details": null
        },
        "count": 41,
        "price": 254000,
        "unitPrice": 6195.121951219512,
        "details": null,
        "firstSeenAt": 1792724107922,
        "lastSeenAt": 1792724107922,
        "marketPrice": 6656.25,
        "seller": null
      },
      {
        "id": 21970430,
        "product": {
          "key": "diamond",
          "item": "diamond",
          "name": "Diamond",
          "variant": "",
          "category": "valuables",
          "details": null
        },
        "count": 64,
        "price": 418000,
        "unitPrice": 6531.25,
        "details": null,
        "firstSeenAt": 1792724107922,
        "lastSeenAt": 1792724107922,
        "marketPrice": 6656.25,
        "seller": null
      }
    ],
    "filled24h": 470109,
    "paidOut24h": 2667647315
  }
}

Try itCounts towards your plan

Path parameters

keystringrequired
Product key. Find keys with GET /v1/items.

Response

The item.

itemobject
An Item with the extra detail fields below.
ShowHide16 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.
    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.
- pricesPrice | null
  Current market figures.
  ShowHide10 child fields
  - pricenumber | null
    Market price per item: the median unit price of the 5 cheapest open listings. null when nothing is listed.
  - lownumber | null
    Cheapest open listing, per item.
  - mediannumber | null
    Median unit price across every open listing of the product.
  - bidnumber | null
    Best open buy order, per item. Lowball orders under 25% of the market price are ignored unless they have already been filled for at least 1%.
  - listingsinteger
    Number of open auction listings.
  - quantityinteger
    Items for sale across those listings.
  - ordersinteger
    Number of open buy orders counted towards bid.
  - demandinteger
    Items those buy orders still want.
  - orderValuenumber
    Money those buy orders would still pay out: the sum of price times remaining amount.
  - updatedAttimestamp
    When these figures were computed.
- change1dnumber | null
  Price change since yesterday as a fraction: 0.05 is 5% up.
- change7dnumber | null
  Price change over 7 days as a fraction.
- shardCostinteger | null
  Price in the shard shop, when it is sold there.
- hourlyPricePoint[]
  Last 7 days, one point per hour.
  ShowHide9 child fields
  - ttimestamp
    Start of the hour or day this point covers, in UTC.
  - pricenumber | null
    Market price at the end of the period.
  - lownumber | null
    Cheapest listing at the end of the period.
  - mediannumber | null
    Median listing at the end of the period.
  - bidnumber | null
    Best buy order at the end of the period.
  - listingsinteger
    Open listings at the end of the period.
  - quantityinteger
    Items for sale at the end of the period.
  - ordersinteger
    Open buy orders at the end of the period. Only in the full price history.
  - demandinteger
    Items those buy orders still wanted. Only in the full price history.
- dailyPricePoint[]
  Last 365 days, one point per day.
  ShowHide9 child fields
  - ttimestamp
    Start of the hour or day this point covers, in UTC.
  - pricenumber | null
    Market price at the end of the period.
  - lownumber | null
    Cheapest listing at the end of the period.
  - mediannumber | null
    Median listing at the end of the period.
  - bidnumber | null
    Best buy order at the end of the period.
  - listingsinteger
    Open listings at the end of the period.
  - quantityinteger
    Items for sale at the end of the period.
  - ordersinteger
    Open buy orders at the end of the period. Only in the full price history.
  - demandinteger
    Items those buy orders still wanted. Only in the full price history.
- topOrdersOrder[]
  The 10 best open buy orders.
  ShowHide10 child fields
  - idinteger
    Stable id of the buy order.
  - productProduct
    What the order wants to buy.
    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.
  - unitPricenumber
    What the order pays per item delivered.
  - amountinteger
    Total number of items the order asks for.
  - deliveredinteger
    Items delivered so far.
  - remaininginteger
    Items still wanted: amount minus delivered.
  - firstSeenAttimestamp
    When the order first appeared.
  - lastSeenAttimestamp
    When the order was last confirmed open.
  - progressedAttimestamp | null
    When a delivery to this order was last recorded. null if none yet.
  - marketPricenumber | null
    Current market price of the product.
- cheapestListingsListing[]
  The 10 cheapest listings.
  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.
  - 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.
    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.
  - 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.
- filled24hinteger
  Items delivered to orders for this product in the last 24 hours.
- paidOut24hnumber
  Money paid out for those deliveries.

Status codes

Status	When
404Not Found	No product has this key.