Skip to content

core-concepts.mdx

Latest commit

 

History

History
103 lines (72 loc) · 7.05 KB

core-concepts.mdx

File metadata and controls

103 lines (72 loc) · 7.05 KB
title Core Concepts: Data Model and Terminology
description Understand the CS2Cap data model: quotes, providers, minor units, item identity, data availability, and common integration pitfalls to avoid.

Before you start building with CS2Cap, it helps to understand a few core concepts that apply across every endpoint. This page explains the data model, clarifies terminology you'll encounter in API responses, and highlights the mistakes that most commonly trip up new integrations.

Terminology

Term Meaning Common fields Primary endpoints
Quote A current listing snapshot for one item on one provider. provider, item_id, lowest_ask, quantity, timestamp /prices
BuyOrderRecord A current highest-bid snapshot for one item on one provider. provider, item_id, highest_bid, num_bids, timestamp /bids
SaleRecord A completed transaction record. provider, item_id, price, date /sales
Provider A marketplace source such as steam, skinport, or buff163. provider key, fee data, operational status /providers
Phase A Doppler or Gamma Doppler variant label (e.g., "Phase 1", "Ruby"). phase /items, /prices, /bids, /sales
Wear The item's condition bucket, from Factory New to Battle-Scarred. item naming, float context /items, /sales
Liquidity Score A 0–100 score reflecting how tradable an item is. Formula explained here. liquidity metrics /market/items, /market/items/item_id
Arbitrage A cross-provider price edge calculated after marketplace fees. buy provider, sell provider, edge metrics /market/arbitrage
Technical Indicators Trading signals derived from composite candle data across providers. Includes RSI, MACD, SMA/EMA, Bollinger Bands, ATR, VWAP, and OBV. indicator values /market/indicators
FX Conversion On-the-fly currency conversion applied to returned price values via the currency query parameter. currency Most market-data endpoints, /fx

Data semantics

Prices use minor units

All price fields are returned as integers in the smallest unit of the requested currency — not decimal amounts.

  • For USD: the unit is cents. A value of 2550 means $25.50.
  • For EUR: the unit is euro cents.

This applies consistently to lowest_ask, highest_bid, price, and any other monetary field in the API.

Do not treat price integers as full currency amounts. Divide by 100 to convert to the standard decimal representation (e.g., `2550 / 100 = 25.50`).

Prices and bids are cached data

/prices and /bids return cached market data that is refreshed every 5–10 minutes. They do not query marketplaces in real time per request.

  • Responses are fast and consistent.
  • If the data source is temporarily unavailable, the API returns 503 with PRICES_INDEX_UNAVAILABLE or BIDS_INDEX_UNAVAILABLE. Retry after a short delay — there is no alternative fallback path for these endpoints.
Treat `PRICES_INDEX_UNAVAILABLE` and `BIDS_INDEX_UNAVAILABLE` as transient errors and implement exponential backoff with retry logic.

Provider keys, not display names

When a request parameter expects a provider, use the provider key — the lowercase machine identifier.

Provider key Marketplace
steam Steam Community Market
skinport Skinport
csfloat CSFloat
buff163 BUFF163

Do not use display names or human-readable labels in API parameters. You can query the full list from GET /providers or visit the Supported Marketplaces page.

Item identity

Most item lookup endpoints accept two ways to identify an item:

  • item_id — a stable numeric identifier assigned by CS2Cap. Use this for production integrations.
  • market_hash_name — the human-readable Steam item name (e.g., AK-47 | Redline (Field-Tested)). Use this for initial lookups or debugging.

Once your application has resolved an item_id for an item, prefer using it in subsequent requests. market_hash_name lookups are convenient but slightly less precise for items that have phase or wear variants.

Optional item attributes

Some metadata fields only apply to certain items. The following fields may be null when they are not relevant to a particular item:

  • phase — only present on Doppler and Gamma Doppler knives
  • wear_name — only present on items with float-based wear conditions
  • min_float / max_float — only present on floatable items

A null value means the field does not apply to that item — it is not an error.

Common pitfalls

Price fields like `lowest_ask` and `highest_bid` are in minor units (e.g., cents for USD). A value of `5000` means $50.00, not $5000. Always divide by 100 before displaying prices to users. The `providers` parameter expects machine-readable keys like `steam` or `csfloat`, not display names like "Steam" or "CS.Float". Passing a display name will result in no data being returned for that provider, or a validation error. The `phase` field is only populated for Doppler and Gamma Doppler knives. For all other items it is `null`. Do not use `null` to infer that an item is a knife — check the `item_id` or category metadata instead. API responses include both a `link` field (a tracked `cs2c.app/r/...` redirect) and a `url` field (the direct marketplace URL). Use `link` if you want to support click attribution; use `url` if you need the canonical marketplace page. A `503` on [`/prices`](/api-reference/prices) or [`/bids`](/api-reference/bids) means the data source is temporarily unavailable, not that the item doesn't exist. Retry after a short delay rather than switching to a different endpoint. Implement retry logic and surface the outage to your users if it persists.