Items

Item metadata, price history, and volatility endpoints

Items API

Endpoints for querying CS2 item data, price history, and volatility metrics.

These endpoints are part of the upcoming platform features. The API contracts below are finalized but the endpoints are not yet deployed. See the Roadmap for implementation timeline.

For details on the volatility computation pipeline, see the Volatility Engine vision doc. For data storage and continuous aggregates, see TimescaleDB.

GET /api/v1/items

List all tracked CS2 items with metadata.

curl http://localhost:8080/api/v1/items

Response:

[
  {
    "id": 1,
    "market_hash_name": "AK-47 | Redline (Field-Tested)",
    "weapon_type": "AK-47",
    "skin_name": "Redline",
    "rarity": "Classified",
    "stattrak": false,
    "image_url": "https://steamcdn-a.akamaihd.net/...",
    "created_at": "2025-01-01T00:00:00Z"
  }
]

---

GET /api/v1/items/:id

Get detailed metadata for a specific item.

curl http://localhost:8080/api/v1/items/1

Path Parameters:

Parameter	Type	Description
id	integer	Item ID

---

GET /api/v1/items/:id/history

Get price history for a specific item.

curl http://localhost:8080/api/v1/items/1/history?window=24h

Path Parameters:

Parameter	Type	Description
id	integer	Item ID

Query Parameters:

Parameter	Type	Default	Description
window	string	24h	Time window: 1h, 24h, 7d

Response:

[
  {
    "time": "2025-01-15T10:00:00Z",
    "price": 1250,
    "volume": 45,
    "source": "steam"
  }
]

Prices are stored in minor units (cents). Divide by 100 for dollar values.

---

GET /api/v1/items/:id/volatility

Get computed volatility metrics for a specific item.

curl http://localhost:8080/api/v1/items/1/volatility

Response:

{
  "item_id": 1,
  "rolling_stddev": 45.2,
  "percent_change": -2.3,
  "bollinger": {
    "upper": 1350,
    "middle": 1250,
    "lower": 1150
  },
  "coefficient_of_variation": 0.036,
  "trend_score": -0.5,
  "computed_at": "2025-01-15T10:05:00Z"
}

Field	Description
rolling_stddev	Standard deviation over the sliding window
percent_change	Percentage price change from previous period
bollinger.upper	Upper Bollinger band (SMA + 2σ)
bollinger.middle	Simple moving average
bollinger.lower	Lower Bollinger band (SMA - 2σ)
coefficient_of_variation	σ/μ — normalized volatility for cross-price comparison
trend_score	Linear regression slope (positive = uptrend, negative = downtrend)

---

GET /api/v1/rankings/volatile

Get the most volatile items ranked by volatility score.

curl http://localhost:8080/api/v1/rankings/volatile?limit=10

Query Parameters:

Parameter	Type	Default	Description
limit	integer	20	Number of items to return

Response:

[
  {
    "item_id": 42,
    "market_hash_name": "AWP | Dragon Lore (Factory New)",
    "volatility_score": 12.8,
    "percent_change": 8.5,
    "current_price": 1450000
  }
]