Overview

CS Deals offers a public API for marketplace data and trading: REST endpoints for listings, prices, sales, buying, withdrawing and account state, plus a real-time WebSocket feed of listing activity with sequence numbers for building a trustworthy local book.

Authentication

Create a personal API key from Settings → API on the website (key creation is browser-only), then authenticate with Authorization: Bearer csd_... on every REST request. This info endpoint is the only unauthenticated route.

Conventions

Every field is snake_case. Prices, balances and amounts are integers (prices in cents). CS Deals ids are integers; external Steam identifiers are strings and always prefixed steam_ (steam_asset_id, steam_offer_id). Timestamps are ISO 8601 strings everywhere, REST and WebSocket alike.

REST endpoints

Every route, what it is for, and its rate limit in requests per minute. Limits are per API key, per endpoint.

Market data

Buying and selling

Items and trades

Account

GET /public/v1/listings and GET /public/v1/trades are metered per second rather than per minute: one request a second, each returning up to 1000 rows. Their limit accepts only 500 or 1000; every other paginated route keeps the usual sizes.

Rate-limited responses carry their budget:

Exceeding a limit returns 429 RATE_LIMITED with a Retry-After header in seconds. Unauthenticated requests are limited by IP instead.

WebSocket feed

Connect to wss://api.cs.deals/public/v1/ws with your API key (Bearer header or ?api_key= query parameter). The scheme is wss://, not https://. Connections without a valid key are closed with code 4401. Each user may hold at most 3 concurrent connections; further attempts are closed with code 4429.

// Node, header authimport WebSocket from "ws";const ws = new WebSocket("wss://api.cs.deals/public/v1/ws", {    headers: { Authorization: `Bearer ${process.env.CSDEALS_API_KEY}` },});ws.on("message", (data) => console.log(JSON.parse(data.toString())));ws.on("close", (code, reason) => console.log("closed", code, reason.toString()));

// Browser: no headers on a WebSocket, so authenticate by query parameterconst ws = new WebSocket("wss://api.cs.deals/public/v1/ws?api_key=csd_...");ws.onmessage = (event) => console.log(JSON.parse(event.data));

The first frame is { "event": "connected", "data": null, "ts": ... }.

Every event is a JSON envelope: { "event": string, "data": object, "seq": number, "ts": string }. ts is the server timestamp, ISO 8601. Control messages (connected, subscribed, error) carry no seq.

seq is a signed 64-bit integer (int64), global across all listing events and shared with the seq returned by GET /public/v1/book. Decode it into a 64-bit type, not a 32-bit one. It is strictly increasing but not contiguous: gaps are normal and never mean you missed an event.

Because the API runs on several processes, two events for the same listing can reach you slightly out of order. Every payload is absolute state, so the rule is one line: apply an event only if its seq is higher than the last seq you applied for that listing_id, and ignore it otherwise.

listing.created carries the same per-game item fields as GET /public/v1/listings rows (float, paint seed, stickers, and so on), so clients can filter interesting listings the moment they appear without a follow-up request.

Building a local book

Every event payload is absolute state (full listing on create, the new price, the new amount), so applying an event twice is harmless. That makes the sync protocol simple:

1. Connect to the WebSocket and start buffering events.
2. GET /public/v1/book: you receive { seq, listings }.
3. Load the listings, drop buffered events with seq <= the snapshot's seq, apply the rest in order, then keep applying live events.

A price_changed or amount_changed for a listing you don't hold can be ignored. If the socket drops, reconnect and repeat from step 1. One request and one socket rebuilds the whole state.

Filtering

By default a connection receives every event. Send a subscribe message to narrow the feed. Each message replaces the connection's filter:

{ "op": "subscribe", "events": ["listing.created"], "app_ids": [730] }

Omitting events or app_ids (or sending an empty array) removes the filter for that dimension. The server confirms with { "event": "subscribed", "data": { events, app_ids } }, where an unfiltered dimension is reported as the string "all" instead of an array; malformed messages get { "event": "error" } and leave the filter unchanged.

The event set will grow over time; unknown events should be ignored by clients for forward compatibility.

Webhooks

The WebSocket feed carries marketplace listing activity. For your own account, register a webhook URL under Settings → Developer and we POST every trade status change to it, so trade state does not have to be polled from GET /public/v1/trades.

Deliveries are signed with a secret derived from your API key (X-CSDeals-Signature: sha256=<hex> over <timestamp>.<body>), retried with backoff, and sent from a fixed set of source addresses you can allowlist. The payload's data is a /public/v1/trades row, unchanged.

Full setup, signature verification and retry semantics are in the webhooks guide.

Response Body