Home/PriceDB API

PriceDB API

Price history, item lookups, graphs, and bot-compatible endpoints for TF2 items.

General Information

Base URL:https://pricedb.io

REST API for TF2 item price history and market data. Pulls pricing from multiple community sources including Backpack.tf and the Steam Community Market.

Rate Limiting:Rate limits on/api/endpoints are enforced dynamically per IP.

Authentication:No authentication required for read endpoints. Bot endpoints require no key but are intended for TF2Autobot integrations. Abuse may result in IP blocking.

Error Codes:

  • •400— Invalid input or malformed request
  • •404— Item or SKU not found
  • •429— Rate limit exceeded
  • •500— Internal server error

WebSocket:Real-time price updates are broadcast over Socket.IO atws://ws.pricedb.io/. Subscribe to thepriceevent to receive live updates as{ sku, name, buy, sell, source, time }.

Health

GET/api/Health check

Returns the status of the API and database connectivity.

Response

API is healthy

GET/api/cache-statsCache statistics

Returns internal cache statistics (hit rate, size, evictions). Useful for monitoring API performance.

Response

Cache and database statistics

{
  "cache": {
    "size": 42,
    "maxSize": 1000,
    "activeTimers": 15
  },
  "database": {
    "totalPrices": 150000,
    "uniqueItems": 5000,
    "latestUpdate": 1748874425
  }
}

Items

GET/api/itemsList all items

Returns a list of all unique items (name and SKU) in the database.

Response

Array of all unique items

[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3"
  }
]
GET/api/item/{sku}Get latest price for SKU

Returns the latest price entry for a specific item SKU.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)

Response

Latest price record for the item

{
  "name": "Strange Professional Killstreak Backburner",
  "sku": "40;11;kt-3",
  "source": "bptf",
  "time": 1748874425,
  "buy": {
    "keys": 4,
    "metal": 11.33
  },
  "sell": {
    "keys": 4,
    "metal": 69.22
  }
}
GET/api/item/hatz/{hatz}Get latest price for a HATZ identifier

Resolves the URL-encoded HATZ identifier using the existing HAT pricing rules.
Returns the newest price across equivalent historical SKU aliases, preserving
its stored SKU and the existing price-record format. Blocked aliases return 404.

Parameters

NameInTypeDescription
hatzpathstringURL-encode the whole HATZ identifier as one path segment, including hash and slash characters

Response

Get latest price for a HATZ identifier

POST/api/items-bulkBulk price lookup

Supply exactly one array, skus or hatz, containing 1-100 identifiers. Existing SKU
requests are unchanged. HATZ values are raw JSON strings, not URL-encoded path
segments; the whole batch is rejected if any HATZ identifier is invalid.
HATZ lookups return the newest record across equivalent SKU aliases, once per
matched item, preserving the stored SKU and price-record array format.
Unpriced and blacklisted items are omitted; all misses return an empty array.
Normalized blacklist checks apply to all HATZ aliases. Existing body-size limits apply.

Request Body

{
  "skus": [
    "40;11;kt-3",
    "202;11;australium"
  ]
}

Response

Array of price records for each matched SKU

Prices

GET/api/latest-pricesLatest price entries

Returns the 10 most recent price entries from the database (not unique per SKU). For the latest price of each unique item use `/api/autob/items`.

Response

Array of recent price records

[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]
GET/api/pricesPaginated price history

Returns paginated price history with metadata. Use `limit` and `offset` for pagination.

Parameters

NameInTypeDescription
limitoptionalqueryintegerMaximum number of records to return (default 100, max 1000)Default: 100
offsetoptionalqueryintegerNumber of records to skip (default 0)Default: 0

Response

Paginated price records

GET/api/item-history/{sku}Full price history for SKU

Returns the complete price history for a specific item SKU as an array. Optionally filter by `start` and/or `end` unix timestamps.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)
startoptionalqueryintegerOnly include entries after this unix timestamp
endoptionalqueryintegerOnly include entries before this unix timestamp

Response

Array of price records in chronological order

GET/api/item-history/hatz/{hatz}Full price history for a HATZ identifier

Resolves a HATZ identifier to its TF2 SKU and supported historical aliases.
URL-encode the entire identifier as one path segment, including any hash or slash characters.
Returns the same price-record array as the SKU history endpoint, preserving stored SKUs
and keys/metal prices. Attachments are normalized using the existing HAT pricing rules.
Valid items without history return an empty array. Blacklisted items return 404.
Results are not paginated; use start and end to restrict the time range.

Parameters

NameInTypeDescription
hatzpathstringURL-encoded HATZ identifier
startoptionalqueryintegerOnly include entries at or after this unix timestamp
endoptionalqueryintegerOnly include entries at or before this unix timestamp

Response

Array of price records across equivalent SKUs in chronological order

GET/api/snapshot/{timestamp}Price snapshot at timestamp

Returns the most recent price for each SKU as of the given unix timestamp.

Parameters

NameInTypeDescription
timestamppathintegerUnix timestamp in seconds

Response

Array of price records as of the given timestamp

Analytics

GET/api/effects/{effectId}/pricesCurrent average item prices for an unusual effect

Computes an unweighted arithmetic mean across all catalogue items carrying the exact
effect ID, combining hats, weapons, taunts and other item types. Uses the latest-known
price per normalized market SKU, deduplicating supported historical aliases by time.
This is not an effect-only premium, completed-sale average or history-weighted price.
Blacklisted markets and malformed SKUs are excluded. No age cutoff is applied.
Both buy and sell totals use the latest catalogue key sell price in refined metal:
totalRefined = keys * keyRate.refinedPerKey + metal.
averageRefined and averageKeys express the same mean in different units; do not add them.
Negative, nonfinite and zero-total sides are excluded independently. An empty side has
null averages and count zero; itemCount includes matching markets without usable sides.
The existing catalogue normalizes missing numeric components to zero.
Results use the in-memory current-price catalogue, not a request-time history scan.
Price updates follow its publication window of up to 60 seconds; blacklist changes
invalidate results immediately. generatedAt is the snapshot time, not price freshness.

Parameters

NameInTypeDescription
effectIdpathintegerPositive integer unusual-effect ID from the SKU's u attribute

Response

Buy and sell averages across all matching current catalogue markets

GET/api/item-stats/{sku}Price statistics for SKU

Returns aggregated statistics (min, max, avg, count) for buy and sell prices of a specific item SKU.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)

Response

Price statistics for the item

{
  "buy": {
    "count": 12,
    "keys": {
      "min": 2,
      "max": 4,
      "avg": 3.1
    },
    "metal": {
      "min": 11.33,
      "max": 69.22,
      "avg": 40.12
    }
  },
  "sell": {
    "count": 12,
    "keys": {
      "min": 2,
      "max": 4,
      "avg": 3.1
    },
    "metal": {
      "min": 11.33,
      "max": 69.22,
      "avg": 40.12
    }
  }
}
GET/api/item-stats/hatz/{hatz}Price statistics for a HATZ identifier

Resolves the URL-encoded HATZ identifier and aggregates history across equivalent
SKU aliases without mixing normal and Strange skins. Preserves the SKU statistics
contract: per-side count and separate keys/metal min, max and average values.
Unlike effect averages, these are historical component statistics, not currency-
converted current-price totals. Blocked aliases and missing history return 404.

Parameters

NameInTypeDescription
hatzpathstringURL-encode the whole HATZ identifier as one path segment, including hash and slash characters

Response

Price statistics for a HATZ identifier

GET/api/graph/{sku}Price history chart

Returns an embeddable HTML page containing an interactive Chart.js price history graph for the item. Supports iframe embedding via `?header=false`.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)
headeroptionalquerybooleanSet to `false` to hide the chart header (useful for iframe embedding)Default: true
heightoptionalqueryintegerChart height in pixels (default 500 with header, 400 without)
widthoptionalquerystringChart width (default `100%`)

Response

HTML page with interactive price chart

GET/api/compare/{sku1}/{sku2}Compare two items

Returns the latest prices for two items side by side for easy comparison.

Parameters

NameInTypeDescription
sku1pathstringSKU of the first item
sku2pathstringSKU of the second item

Response

Side-by-side comparison with price differences and history

{
  "items": {
    "40;11;kt-3": {
      "name": "Strange Professional Killstreak Backburner",
      "sku": "40;11;kt-3",
      "buy": {
        "keys": 4,
        "metal": 11.33
      },
      "sell": {
        "keys": 4,
        "metal": 69.22
      }
    },
    "202;11;australium": {
      "name": "Australium Rocket Launcher",
      "sku": "202;11;australium",
      "buy": {
        "keys": 45,
        "metal": 0
      },
      "sell": {
        "keys": 50,
        "metal": 0
      }
    }
  },
  "comparison": {
    "buyDifference": {
      "keys": -41,
      "metal": 11.33
    },
    "sellDifference": {
      "keys": -46,
      "metal": 69.22
    }
  },
  "history": {
    "40;11;kt-3": [],
    "202;11;australium": []
  },
  "meta": {
    "compared": "2025-01-01T00:00:00.000Z",
    "historyDays": 30
  }
}

Search

Bot

GET/api/autob/itemsAll items (bot format)

Returns the full pricelist for TF2Autobot integration. Returns the latest price for each unique SKU.

Response

All current prices in bot format

{
  "success": true,
  "currency": "metal",
  "items": [
    {
      "name": "Strange Professional Killstreak Backburner",
      "sku": "40;11;kt-3",
      "source": "bptf",
      "time": 1748874425,
      "buy": {
        "keys": 4,
        "metal": 11.33
      },
      "sell": {
        "keys": 4,
        "metal": 69.22
      }
    }
  ]
}
GET/api/autob/items/{sku}Single item (bot format)

Returns the latest price for a single SKU in TF2Autobot-compatible format.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)

Response

Price record for the requested SKU

POST/api/autob/items/{sku}Price check (bot format)

Price check endpoint for TF2Autobot integration.

Parameters

NameInTypeDescription
skupathstringTF2 item SKU string (e.g. `5021;6` for Mann Co. Supply Crate Key)

Response

Price check accepted