Skip to main content
GET
Live buyable listings
listings 端点公开了 CSBoard 市场上当前所有可购买的商品。每条记录都包含您进行评估所需的完整检视数据——磨损值、印花种子、已贴贴纸及其磨损——以及美元的权威报价。结果通过键集游标分页,即便不断有新挂单出现,您也能可靠地遍历整个目录。 需要身份验证。 请将密钥作为 Authorization: Bearer csb_pub_... 发送。

查询参数

对商品的 market_hash_name 进行模糊匹配 —— 将查询拆分为多个词,并对每个词进行子串匹配,非常适合探索。注意:如果某个名称是更长商品名称的词子集(例如 Spectrum CaseSpectrum 2 Case),则无法通过此方式单独筛选。要查询单个特定商品,请使用 name
string
精确的 market_hash_name(不区分大小写)。获取某个特定商品列表的精确方式 —— name=Spectrum Case 仅返回 Spectrum Case,绝不会返回 Spectrum 2 Case。当同时提供时,优先于 search
string
按商品类别过滤,例如 RifleKnifeGlovesPistol
string
按磨损档位过滤。可选值:Factory NewMinimal WearField-TestedWell-WornBattle-Scarred 之一。
string
按稀有度档位过滤,例如 ClassifiedCovertExtraordinary
number
最低报价,单位美元(含)。
number
最高报价,单位美元(含)。
number
最小磨损值(含)。接受 0.01.0 之间的值。
number
最大磨损值(含)。接受 0.01.0 之间的值。
string
StatTrak™ 过滤。only 仅返回 StatTrak™ 商品;exclude 将其从结果中移除。
string
纪念品过滤。only 仅返回纪念品商品;exclude 将其从结果中移除。
string (ISO 8601)
仅返回在该时间戳之后进入目录的挂单——增量轮询参数。与 sort=newest 搭配使用时,通常的响应是一个空页面,这正是让频繁轮询变得廉价、而不是每次都全量重扫的原因。请将水位线回退约 60 秒,并按 id 去重。 请发送 max(listed_at) - 60s,而不是那个裸的最大值。时间戳取自发布该挂单的数据库事务的开始时刻,因此一个大批次可能提交出时间戳更早的行,而一个更小、更晚的批次却已经提交完毕;把水位线精确推进到最大值,会永久跳过这些挂单。
string
默认值:"id"
排序方式。可选值:id(稳定的默认值)、newestprice_ascprice_desc 之一。newestlisted_at 排序,因此重新上架的商品会与真正的新库存一起浮现。
string
键集分页游标。传入上一次响应中的 next_cursor 值以获取下一页。
integer
默认值:"50"
每页结果数。最小 1,最大 200

响应字段

Listing[]
必填
本页的挂单对象数组。
string | null
必填
不透明的键集游标。将其作为 cursor 查询参数传入以获取下一页。最后一页为 null

分页

此端点使用键集分页。要遍历所有页面:
  1. 发起初始请求(不带 cursor)。
  2. 如果 next_cursor 非空,则携带 cursor=<next_cursor> 重复请求。
  3. next_cursornull 时停止——您已到达最后一页。
键集分页是稳定的:在遍历期间新出现的挂单不会导致重复或跳行。

示例请求

示例响应

错误代码

每条挂单上的 price_usd权威购买价格——它反映了查询时刻的实时报价,也正是您将被扣除的金额。请不要将 /prices 端点中的 min_price_usd 用作购买价格估算;该值可能滞后。

授权

Authorization
string
header
必填

Send your key as a Bearer token on every request: Authorization: Bearer csb_pub_.... Generate keys in your CSBoard profile.

查询参数

Full-text match on market hash name.

name
string

Exact market_hash_name (case-insensitive) — the precise single-item lookup. Unlike fuzzy search, it isolates one item even when its name is a word-subset of a longer one (e.g. Spectrum Case vs Spectrum 2 Case). Takes precedence over search.

category
string

e.g. Rifle, Knife, Gloves.

wear
enum<string>

Item wear bucket.

可用选项:
Factory New,
Minimal Wear,
Field-Tested,
Well-Worn,
Battle-Scarred
rarity
string

e.g. Classified, Covert.

min_price
number

Minimum price in USD.

max_price
number

Maximum price in USD.

min_float
number

Minimum float value.

max_float
number

Maximum float value.

delivery
enum<string>

Delivery bucket, the same three the site's grid shows. instant = bot fulfilment (seconds to minutes); up_to_12h = a human seller on the source market must send the trade; hold = inside a Steam trade lock until the item's tradable_at. Any other value is a 400.

可用选项:
instant,
up_to_12h,
hold
min_refund_percent
number

Only listings whose refund_percent is at least this (0-100). Listings with no published figure are EXCLUDED, not assumed. Combine with delivery=instant for a pool that ships now and is fully refundable on a Steam reversal.

必填范围: 0 <= x <= 100
stat_trak
enum<string>

Filter StatTrak™ items.

可用选项:
only,
exclude
souvenir
enum<string>

Filter Souvenir items.

可用选项:
only,
exclude
available_after
string<date-time>

ISO-8601 timestamp. Returns only listings that entered the catalogue after it — the delta-poll parameter. Pair with sort=newest; the usual response is an empty page, which is what makes frequent polling cheap instead of a full rescan every tick.

Overlap your watermark by ~60 seconds and dedupe by id. Send max(listed_at) - 60s, never the bare maximum. Timestamps come from the start of the database transaction that published the listing, so a large batch can commit rows stamped earlier than rows a smaller, later batch already committed; a watermark advanced to the exact maximum steps over those listings permanently.

sort
enum<string>
默认值:id

Sort order. Default id. newest orders by listed_at (when the item entered the catalogue), so re-listings surface too.

可用选项:
id,
newest,
price_asc,
price_desc
cursor
string

Keyset cursor from next_cursor.

limit
integer
默认值:50

1–200. Default 50.

必填范围: 1 <= x <= 200

响应

A page of listings.

items
object[]
必填
next_cursor
string | null
必填

Pass back as cursor to fetch the next page. Null on the last page.