GET /v1/listings — 浏览实时的 CS2 市场挂单

GET

listings

Live buyable listings

curl --request GET \
  --url https://csboard.com/v1/listings \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://csboard.com/v1/listings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://csboard.com/v1/listings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://csboard.com/v1/listings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://csboard.com/v1/listings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "itm_8841201",
      "market_hash_name": "AK-47 | Redline (Minimal Wear)",
      "wear": "Minimal Wear",
      "doppler_phase": null,
      "float_value": 0.0912,
      "paint_seed": 412,
      "stickers": [
        {
          "name": "Crown (Foil)",
          "image": "https://cdn.csboard.com/stickers/crown_foil.png",
          "slot": 0,
          "wear": 0
        }
      ],
      "price_usd": 14.37,
      "category": "Rifle",
      "rarity": "Classified",
      "image": "https://cdn.csboard.com/items/ak47_redline_mw.png",
      "inspect_link": "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20...",
      "tradable": false,
      "tradable_at": "2026-07-06T12:00:00Z",
      "delivery": "hold",
      "refund_percent": 100,
      "listed_at": "2026-06-29T08:41:17.000Z"
    }
  ],
  "next_cursor": "eyJpZCI6Iml0bV84ODQxMjAxIn0="
}

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

传入 appId=570 读取 Dota 2，传入 appId=252490 读取 Rust。这些行的键名相同；仅 CS2 才有的字段（wear、doppler_phase、float_value、paint_seed、inspect_link、tradable_at、listed_at）为 null，stickers 为 []。参见游戏。

查询参数

integer

默认值:"730"

要读取的游戏：730 = CS2，570 = Dota 2，252490 = Rust。不传则为 CS2。您的密钥可用的游戏请参见 GET /v1/games。

string

对商品的 market_hash_name 进行模糊匹配 —— 将查询拆分为多个词，并对每个词进行子串匹配，非常适合探索。注意：如果某个名称是更长商品名称的词子集（例如 Spectrum Case 与 Spectrum 2 Case），则无法通过此方式单独筛选。要查询单个特定商品，请使用 name。

string

精确的 market_hash_name（不区分大小写）。获取某个特定商品列表的精确方式 —— name=Spectrum Case 仅返回 Spectrum Case，绝不会返回 Spectrum 2 Case。当同时提供时，优先于 search。

string

按商品类别过滤，例如 Rifle、Knife、Gloves、Pistol。

string

按磨损档位过滤。可选值：Factory New、Minimal Wear、Field-Tested、Well-Worn、Battle-Scarred 之一。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

string

按稀有度档位过滤，例如 Classified、Covert、Extraordinary。

number

最低报价，单位美元（含）。

number

最高报价，单位美元（含）。

number

最小磨损值（含）。接受 0.0 到 1.0 之间的值。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

number

最大磨损值（含）。接受 0.0 到 1.0 之间的值。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

string

交付分组——与网站商品网格显示的三种相同。可选值：

instant — 机器人交付。几秒到几分钟。
up_to_12h — 需要来源市场上的真人卖家发起交易。网站上显示为 ≤12 小时。
hold — 处于 Steam 交易锁定期，直到物品的 tradable_at。

任何必须立即交付的流程都请使用 delivery=instant——提现、机器人派发、正在屏幕前等待的用户。其他任何值都会返回 400，因此拼写错误会直接报错，而不会悄悄扩大结果范围。

number

仅返回 refund_percent 不低于该值（0–100）的挂单。没有公布数值的挂单会被排除，而不会被默认视为符合条件。?delivery=instant&min_refund_percent=100 正是提现流程需要的商品池：立即发货，且 Steam 交易回滚不会让任何人蒙受损失。

string

StatTrak™ 过滤。only 仅返回 StatTrak™ 商品；exclude 将其从结果中移除。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

string

纪念品过滤。only 仅返回纪念品商品；exclude 将其从结果中移除。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

string (ISO 8601)

仅返回在该时间戳之后进入目录的挂单——增量轮询参数。与 sort=newest 搭配使用时，通常的响应是一个空页面，这正是让频繁轮询变得廉价、而不是每次都全量重扫的原因。请将水位线回退约 60 秒，并按 id 去重。 请发送 max(listed_at) - 60s，而不是那个裸的最大值。时间戳取自发布该挂单的数据库事务的开始时刻，因此一个大批次可能提交出时间戳更早的行，而一个更小、更晚的批次却已经提交完毕；把水位线精确推进到最大值，会永久跳过这些挂单。仅限 CS2——在其他 appId 下发送会返回 400 invalid_param。

string

默认值:"id"

排序方式。可选值：id（稳定的默认值）、newest、price_asc、price_desc 之一。newest 按 listed_at 排序，因此重新上架的商品会与真正的新库存一起浮现。newest 仅限 CS2——在其他 appId 下使用会返回 400 invalid_param。

string

键集分页游标。传入上一次响应中的 next_cursor 值以获取下一页。

integer

默认值:"50"

每页结果数。最小 1，最大 200。

响应字段

Listing[]

必填

本页的挂单对象数组。

显示 Listing object

string

必填

稳定的挂单标识符。将其传给 POST /v1/orders 以购买该商品。

string

必填

Steam 市场哈希名称，例如 AK-47 | Redline (Minimal Wear)。

string | null

磨损档位：Factory New、Minimal Wear、Field-Tested、Well-Worn 或 Battle-Scarred。对于不带磨损的商品（如部分匕首或手套）为 null。

string | null

多普勒或伽马多普勒相位，例如 "Phase 2"、"Ruby"、"Emerald"。非多普勒商品为 null。

number | null

商品磨损值，介于 0.0 和 1.0 之间。不适用时为 null。

integer | null

印花种子（图案索引）。不适用时为 null。

Sticker[]

必填

已贴贴纸。若无则为空数组。

显示 Sticker object

string

贴纸名称，例如 Crown (Foil)。

string (URI)

贴纸图像的 CDN URL。

integer

贴纸槽位，0 到 4。

number | null

贴纸磨损，介于 0.0 和 1.0 之间。如果贴纸尚未被刮过，则为 null。

number

必填

美元权威报价。如果您通过 POST /v1/orders 购买该挂单，扣除的金额就是这个数值。

string

必填

商品类别，例如 Rifle、Knife、Gloves。

string

稀有度档位，例如 Classified、Covert。

string (URI)

商品图像的 CDN URL。

string

该商品的 Steam 检视链接（steam://rungame/...）。

boolean

必填

该商品当前是否可交易。false 表示处于交易冻结期。

datetime | null

该商品脱离交易冻结的 ISO 8601 时间戳。若已可交易则为 null。

string

必填

预期交付模式：instant（机器人，几秒到几分钟）、up_to_12h（需要来源市场上的真人卖家发起交易）或 hold（处于 Steam 交易锁定期，直到 tradable_at）。

number | null

如果 Valve 回滚 Steam 交易，这笔购买能退回多少。这是挂单来源市场的属性，而不是客服政策；在我们的各个来源中，该值介于 0 到 100 之间。null 表示该挂单没有公布的数值——请视为未知，切勿当作 100。使用 min_refund_percent 过滤，可构建一个每件物品都能得到全额补偿的商品池。

datetime | null

该商品进入目录的时间。这与记录的创建时间并不相同：商品会不断回到目录——已取消的订单、过期的交易报价、解除的冻结——重新上架的商品对您而言就是新的，即使它此前已经存在。这个值就是要回传给 available_after 的值。

string | null

必填

不透明的键集游标。将其作为 cursor 查询参数传入以获取下一页。最后一页为 null。

分页

此端点使用键集分页。要遍历所有页面：

发起初始请求（不带 cursor）。
如果 next_cursor 非空，则携带 cursor=<next_cursor> 重复请求。
当 next_cursor 为 null 时停止——您已到达最后一页。

键集分页是稳定的：在遍历期间新出现的挂单不会导致重复或跳行。

示例请求

curl "https://csboard.com/v1/listings?category=Rifle&wear=Minimal+Wear&min_float=0.07&max_float=0.12&sort=price_asc&limit=20" \
  -H "Authorization: Bearer csb_pub_..."

示例响应

{
  "items": [
    {
      "id": "itm_8841201",
      "market_hash_name": "AK-47 | Redline (Minimal Wear)",
      "wear": "Minimal Wear",
      "doppler_phase": null,
      "float_value": 0.0912,
      "paint_seed": 412,
      "stickers": [
        {
          "name": "Crown (Foil)",
          "image": "https://cdn.csboard.com/stickers/crown_foil.png",
          "slot": 0,
          "wear": 0.0
        }
      ],
      "price_usd": 14.37,
      "category": "Rifle",
      "rarity": "Classified",
      "image": "https://cdn.csboard.com/items/ak47_redline_mw.png",
      "inspect_link": "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20...",
      "tradable": false,
      "tradable_at": "2026-07-06T12:00:00Z",
      "delivery": "hold",
      "refund_percent": 100,
      "listed_at": "2026-06-29T08:41:17.000Z"
    }
  ],
  "next_cursor": "eyJpZCI6Iml0bV84ODQxMjAxIn0="
}

错误代码

HTTP 状态码	代码	含义
400	`invalid_param`	参数格式错误，或在其他 `appId` 下发送了仅限 CS2 的过滤参数。
400	`unsupported_game`	您的密钥无法使用该 `appId`。`supported_app_ids` 列出了可用的值。
401	`missing_api_key`, `invalid_api_key`	API 密钥缺失或无效。
429	`rate_limit_exceeded`	超过该密钥的每分钟限额（默认 100 次/分钟）。请按照 `Retry-After` 响应头中的秒数退避。

每条挂单上的 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. Calls made with a key are metered only by that key's own limits — there is no per-IP limit on top — and every answer carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and X-RateLimit-Bucket for the bucket the call spent. See Rate limits.

查询参数

appId

enum<integer>

默认值:730

Steam appId of the game. 730 = CS2 (the default), 570 = Dota 2, 252490 = Rust. Omit it and the endpoint answers for CS2 exactly as before. An appId this key may not use answers 400 unsupported_game, whose supported_app_ids lists the ones it may — see GET /games.

可用选项:

730,

570,

252490

string

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.

响应

A page of listings.

items

object[]

必填

Show child attributes

next_cursor

string | null

必填

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

Live buyable listings

curl --request GET \
  --url https://csboard.com/v1/listings \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://csboard.com/v1/listings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://csboard.com/v1/listings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://csboard.com/v1/listings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://csboard.com/v1/listings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "items": [
    {
      "id": "itm_8841201",
      "market_hash_name": "AK-47 | Redline (Minimal Wear)",
      "wear": "Minimal Wear",
      "doppler_phase": null,
      "float_value": 0.0912,
      "paint_seed": 412,
      "stickers": [
        {
          "name": "Crown (Foil)",
          "image": "https://cdn.csboard.com/stickers/crown_foil.png",
          "slot": 0,
          "wear": 0
        }
      ],
      "price_usd": 14.37,
      "category": "Rifle",
      "rarity": "Classified",
      "image": "https://cdn.csboard.com/items/ak47_redline_mw.png",
      "inspect_link": "steam://rungame/730/76561202255233023/+csgo_econ_action_preview%20...",
      "tradable": false,
      "tradable_at": "2026-07-06T12:00:00Z",
      "delivery": "hold",
      "refund_percent": 100,
      "listed_at": "2026-06-29T08:41:17.000Z"
    }
  ],
  "next_cursor": "eyJpZCI6Iml0bV84ODQxMjAxIn0="
}

市场数据

交易

P2P

账户

状态

GET /v1/listings — 浏览实时的 CS2 市场挂单

查询参数

响应字段

分页

示例请求

示例响应

错误代码

授权

查询参数

响应

​查询参数

​响应字段

​分页

​示例请求

​示例响应

​错误代码

授权

查询参数

响应

查询参数

响应字段

分页

示例请求

示例响应

错误代码