# Skintick

> REST API for Counter-Strike 2 skin prices, normalized across eight marketplaces with cross-market outlier flags, listings-based confidence, and explicit freshness on every price row.

Skintick collects price snapshots from Skinport, CSFloat, Tradeit, DMarket, Loot.farm, White.market, Bitskins, and Waxpeer. Every response is keyed by Steam's `market_hash_name` and returns the same row shape regardless of which marketplace the data came from. Prices are decimal strings in USD; timestamps are RFC 3339 UTC; bearer-token auth on `/v1/*` with per-key rate limits surfaced in `X-RateLimit-*` headers.

## Docs

- [OpenAPI 3.0 spec](https://api.skintick.io/openapi.yaml): Canonical machine-readable description of every endpoint, schema, and error response.
- [API reference](https://skintick.io/docs/): Browsable Redoc-rendered docs with examples.
- [Full LLM reference](https://skintick.io/llms-full.txt): Long-form human-readable copy of the docs optimized for LLM context windows.
- [Skinport API guide](https://skintick.io/skinport-api/): Marketplace-specific landing with usage patterns and live status.
- [Status page](https://skintick.io/status/): Real-time per-marketplace collector health, no auth required.

## Endpoints

- `GET /healthz`: Liveness check. Public.
- `GET /v1/status`: Per-marketplace collector status (`healthy`, `degraded`, `unavailable`, `unknown`). Public.
- `GET /v1/markets`: List supported marketplaces with fees and trade-lock days.
- `GET /v1/items?q=&limit=&cursor=`: Paginated item catalog with optional substring search.
- `GET /v1/items/{market_hash_name}`: Latest cross-market prices for one item; rows carry `is_outlier` + `confidence`.
- `GET /v1/items/{market_hash_name}/history?market=&from=&to=`: Time series of snapshots for one (item, marketplace).
- `POST /v1/prices/latest`: Batch latest-price lookups, up to 100 items per request. Returns `data`, `missing`, and `warnings`.
- `GET /v1/spreads`: Cross-marketplace arbitrage routes after fees and a coarse trade-lock risk adjustment. Sorted by `risk_adjusted_net_spread_pct` DESC.

## Marketplaces

- `skinport` (p2p, EU): ~24,400 items, full catalog, no auth, brotli encoding required by their feed.
- `csfloat` (p2p): per-listing data with floats/stickers, raw API key in Authorization header, 200 requests per ~30 min rate cap.
- `tradeit` (instant_bot, US): bot-inventory ~930 items via Cloudflare-fronted endpoint, prices carry an instant-trade premium.
- `dmarket` (p2p): ~1,440 items via cursor pagination, no auth on read endpoints.
- `lootfarm` (instant_bot): ~2,300 in-stock items, static fullprice.json feed.
- `whitemarket` (p2p, EU): ~26,300 priced items, broadest free catalog, static S3 export.
- `bitskins` (p2p): ~17,200 pre-aggregated items, anonymous GET, fastest single-call coverage.
- `waxpeer` (p2p, EU/CIS): ~21,300 pre-aggregated items, anonymous GET, includes Steam reference price.

## Conventions

- Prices are decimal strings (`"22.40"`) in USD, stored internally as integer cents.
- `market_hash_name` follows Steam's canonical format (`"AK-47 | Redline (Field-Tested)"`); URL-encode in path params.
- Timestamps are RFC 3339 in UTC.
- `is_outlier` is true when a marketplace's `min_price` falls outside 3× the cross-marketplace median; requires at least three priced p2p markets to fire.
- `confidence` is a coarse tier from per-row `listings_count`: `high` (≥10), `medium` (3–9), `low` (1–2), `unknown` (null).
- `is_stale` is true on latest-price rows when `collected_at` is older than 30 minutes.
- Errors return `{ "error": { "code", "message" } }`.

## Optional

- [Repo README](https://github.com/joelh12/Skintick/blob/main/README.md): Quick-start for local development.
- [CLAUDE.md](https://github.com/joelh12/Skintick/blob/main/CLAUDE.md): Repo conventions, scraping policy, and open items list.