# CSPricebase Pricing API — Integration Guide

You are integrating the CSPricebase Pricing API: real-time CS2 (Counter-Strike 2)
skin prices across 13 marketplaces, served from a single endpoint.

## Quick facts
- Base URL: https://www.cspricebase.com
- Primary endpoint: GET /api/prices
- Auth: Bearer API key, sent in the Authorization header
- Format: JSON, ALWAYS brotli-compressed (Content-Encoding: br)
- Rate limit: 60 requests/minute per key
- Data refresh: roughly every 30 minutes

## Authentication
Send your key as a Bearer token on every request:

    Authorization: Bearer YOUR_API_KEY

Keys are available on the Trader plan and above, generated from the account
profile page. Never share a key or embed it in client-side / shipped code — keys
are seen-from-many-IPs flagged and can be revoked.

## IMPORTANT: responses are always brotli-compressed
The server returns Content-Encoding: br regardless of your Accept-Encoding
header. Use an HTTP client that decodes brotli automatically, or you will get
raw compressed bytes that fail to parse as JSON:
- curl: pass --compressed
- Node.js fetch (undici) and axios: automatic, nothing to do
- Python requests: install brotli support first (pip install brotli)

## GET /api/prices
Returns prices for the selected markets, keyed by exact item name.

### Query parameters
- markets : CSV, optional. Which markets to include. Omit for ALL markets.
- fields  : CSV, optional. Extra per-item fields. Default returns price only.
- min     : number, optional. Keep items whose cheapest selected price >= min (cents).
- max     : number, optional. Keep items whose cheapest selected price <= max (cents).

### Markets (values for markets=)
buff163, csfloat, youpin, dmarket, steam, gamerpay, marketcsgo, lisskins,
waxpeer, shadowpay, whitemarket, skins, csgoroll

All markets return a price as an INTEGER in cents (USD), except csgoroll, which
returns site coins. The merchant and cspricebase markets are internal and are
NOT exposed by this API — requesting them returns 400.

### Optional fields (values for fields=)
- avg_30      (per-market) 30-day average price, cents
- avg_7       (per-market) 7-day average price, cents
- count       (per-market) number of listings available
- is_inflated (per-market) boolean, price flagged as an outlier
- updated_at  (per-market) ISO timestamp of that market's last update
- link        (per-market) direct link to the item on that market
- liquidity   (item-level) liquidity score for the item

By default each selected market returns only price (or coins for csgoroll).

### Response shape
    {
      "updated_at": "2026-06-25T12:30:00.000Z",
      "markets": ["buff163", "csfloat", "skins"],
      "items": {
        "AK-47 | Redline (Field-Tested)": {
          "buff163": { "price": 1542 },
          "csfloat": { "price": 1610 },
          "skins":   { "price": 1599 }
        }
      }
    }

Item keys are the exact market hash name, e.g.
"AK-47 | Redline (Field-Tested)" or "★ Karambit | Doppler (Factory New)".
With fields=liquidity,count an item looks like:

    "AK-47 | Redline (Field-Tested)": {
      "buff163": { "price": 1542, "count": 84 },
      "csfloat": { "price": 1610, "count": 23 },
      "liquidity": 73
    }

csgoroll uses coins, not price:

    "AK-47 | Redline (Field-Tested)": { "csgoroll": { "coins": 18.42 } }

## Errors
- 400 Bad Request        unknown market/field, or non-numeric min/max
- 401 Unauthorized       missing or invalid Bearer key
- 429 Too Many Requests  over 60/min — honor the Retry-After header
- 503 Service Unavailable data momentarily unavailable; retry shortly

Error bodies are JSON: { "error": "..." }

## Recommended polling pattern (ETag / 304)
Every response includes an ETag. Send it back as If-None-Match on the next poll;
if nothing changed you get a body-less 304 Not Modified, which is cheap and
fast. Because data only changes about every 30 minutes, poll at most once per
minute and rely on 304s rather than re-downloading.

## Examples

### curl
    curl --compressed \
      -H "Authorization: Bearer YOUR_API_KEY" \
      "https://www.cspricebase.com/api/prices?markets=buff163,csfloat,skins&fields=liquidity,count"

### Node.js (fetch)
    let etag = null;
    async function fetchPrices() {
      const headers = { Authorization: "Bearer YOUR_API_KEY" };
      if (etag) headers["If-None-Match"] = etag;
      const res = await fetch(
        "https://www.cspricebase.com/api/prices?markets=buff163,csfloat&fields=liquidity",
        { headers }
      );
      if (res.status === 304) return null;            // unchanged since last poll
      if (!res.ok) throw new Error("API " + res.status);
      etag = res.headers.get("etag");
      return res.json();                              // fetch auto-decodes brotli
    }

### Python (requests)
    import requests  # needs brotli: pip install brotli

    etag = None
    def fetch_prices():
        global etag
        headers = {"Authorization": "Bearer YOUR_API_KEY"}
        if etag:
            headers["If-None-Match"] = etag
        r = requests.get(
            "https://www.cspricebase.com/api/prices",
            params={"markets": "buff163,csfloat", "fields": "liquidity"},
            headers=headers,
        )
        if r.status_code == 304:
            return None
        r.raise_for_status()
        etag = r.headers.get("ETag")
        return r.json()

## Migration note
The older endpoints /api/csgoroll-prices and /api/get-rollhelper-prices are
superseded by /api/prices (use markets=csgoroll for CSGORoll coins). Prefer
/api/prices for all new integrations.