API
批量获取饰品价格
POST /prices/batch — 批量获取饰品价格
操作
POST /prices/batch
行为
一次调用返回一组饰品的当前报价。每个饰品的报价遵循与 GET /prices 相同的规则：每个市场的每个方向最多一条，仍在售的报价优先于已下架的报价，其次直接取自市场的数据优先于聚合平台的数据，再次取最新的报价；饰品有估值时另附其 CSCP 估值（side 为 mid）。
items中每个请求的名称对应一条记录，顺序与请求一致。- 未知名称不算错误：它们会以空的
markets列表返回。此端点从不返回404。 - 重复的名称会被保留，每次出现都有各自的记录。
markets和side以同样的方式过滤每个饰品。- 请求体中的未知字段会以
422拒绝。
[!note] 按饰品名称块计费，不足一块按一块计，计数基于完整的
market_hash_names列表（包括重复项）。费用会在查询前检查（余额不足时返回402），且仅在请求成功时扣费。
用量
{
"authentication": "user-api-key",
"credit_cost": 1,
"premium": false,
"recommended_interval_seconds": 60,
"rate_limit": {
"max_requests": 20,
"window_seconds": 60
},
"unit_pricing": {
"unit_size": 100,
"units_body_field": "market_hash_names",
"max_units": 1000
}
}请求
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchPricesIn"
}
}
},
"required": true
}
}响应
{
"200": {
"description": "请求成功",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Envelope_BatchPricesOut_"
}
}
}
},
"401": {
"description": "缺少认证信息或认证无效",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"402": {
"description": "点数不足以完成本次请求",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"403": {
"description": "凭证有效，但无权调用此操作",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"422": {
"description": "参数或请求体无效",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"429": {
"description": "对此端点的请求过多；请稍后重试",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"503": {
"description": "服务暂时不可用；请稍后重试",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
}模型
{
"BatchItemOut": {
"properties": {
"market_hash_name": {
"type": "string",
"title": "Market Hash Name",
"description": "饰品的 market hash name，与请求中的完全一致。"
},
"markets": {
"items": {
"$ref": "#/components/schemas/MarketQuoteOut"
},
"type": "array",
"title": "Markets",
"description": "该饰品的报价，每个市场的每个方向最多一条，先按市场代码、再按方向排序。饰品未知或所有报价都被过滤条件排除时为空。"
}
},
"type": "object",
"required": [
"market_hash_name",
"markets"
],
"title": "BatchItemOut",
"description": "一个请求的饰品及其市场报价。"
},
"BatchPricesIn": {
"properties": {
"app_id": {
"type": "string",
"maxLength": 16,
"minLength": 1,
"title": "App Id",
"description": "游戏的 Steam 应用 ID。默认为 `730`（Counter-Strike 2）。",
"default": "730"
},
"market_hash_names": {
"items": {
"type": "string",
"maxLength": 255,
"minLength": 1
},
"type": "array",
"maxItems": 1000,
"minItems": 1,
"title": "Market Hash Names",
"description": "要查询的 Steam market hash name 列表（精确匹配，区分大小写）。允许重复：每次出现都有各自的结果条目，并计入计费的饰品数量。"
},
"markets": {
"anyOf": [
{
"items": {
"type": "string",
"pattern": "^[A-Z0-9_]{1,32}$"
},
"type": "array",
"minItems": 1
},
{
"type": "null"
}
],
"title": "Markets",
"description": "要包含的市场代码，例如 `[\"BUFF\", \"UUYP\"]`。每个代码只能由大写字母、数字或下划线组成。省略则包含所有市场。"
},
"side": {
"type": "string",
"enum": [
"ask",
"bid",
"mid",
"all"
],
"title": "Side",
"description": "返回市场的哪一方向：`ask` 为在售挂单，`bid` 为求购订单，`mid` 为 CSCP 估值，`all` 为全部。默认为 `all`。",
"default": "all"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"market_hash_names"
],
"title": "BatchPricesIn",
"description": "批量价格查询的请求体。"
},
"BatchPricesOut": {
"properties": {
"app_id": {
"type": "string",
"title": "App Id",
"description": "Steam 应用 ID，原样回显请求中的值。"
},
"side": {
"type": "string",
"enum": [
"ask",
"bid",
"mid",
"all"
],
"title": "Side",
"description": "所应用的方向过滤条件，原样回显请求中的值。"
},
"items": {
"items": {
"$ref": "#/components/schemas/BatchItemOut"
},
"type": "array",
"title": "Items",
"description": "每个请求的名称对应一条记录，顺序与请求一致，包括重复项。"
}
},
"type": "object",
"required": [
"app_id",
"side",
"items"
],
"title": "BatchPricesOut",
"description": "每个请求饰品的市场报价，顺序与请求一致。"
},
"CreditMeta": {
"properties": {
"cost": {
"type": "integer",
"title": "Cost",
"description": "本次请求花费的点数。"
},
"remaining": {
"type": "integer",
"title": "Remaining",
"description": "本次请求后的预估剩余点数。仅作参考而非账目：并发请求可能导致其略有偏差。"
}
},
"type": "object",
"required": [
"cost",
"remaining"
],
"title": "CreditMeta",
"description": "计费请求的点数结算信息。"
},
"Envelope_BatchPricesOut_": {
"properties": {
"data": {
"$ref": "#/components/schemas/BatchPricesOut",
"description": "端点返回的数据。"
},
"meta": {
"$ref": "#/components/schemas/Meta",
"description": "请求元数据。"
}
},
"type": "object",
"required": [
"data",
"meta"
],
"title": "Envelope[BatchPricesOut]"
},
"ErrorBody": {
"properties": {
"code": {
"type": "string",
"title": "Code",
"description": "稳定的机器可读错误代码。请根据此值进行分支处理，而不是 `message`。"
},
"message": {
"type": "string",
"title": "Message",
"description": "面向人类阅读的说明。措辞可能变化。"
},
"details": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Details",
"description": "可选的结构化上下文，例如校验错误列表；对于 `credit_insufficient`，则为所需点数和剩余点数。"
}
},
"type": "object",
"required": [
"code",
"message"
],
"title": "ErrorBody",
"description": "失败请求的详细信息。"
},
"ErrorEnvelope": {
"properties": {
"error": {
"$ref": "#/components/schemas/ErrorBody",
"description": "出了什么问题。"
},
"meta": {
"$ref": "#/components/schemas/Meta",
"description": "请求元数据。"
}
},
"type": "object",
"required": [
"error",
"meta"
],
"title": "ErrorEnvelope",
"description": "错误响应：`error` 中为错误信息，`meta` 中为请求元数据。"
},
"MarketQuoteOut": {
"properties": {
"market_code": {
"type": "string",
"title": "Market Code",
"description": "该报价所属市场的代码，例如 `BUFF`。`CSCP` 表示 cs.cheap 对该饰品的估值：跨市场的人民币加权共识，每天更新，没有数量，`changed_at` 与 `fresh_at` 为其计算时间，详情见 `valuation`。它是估算值，不是任何人都能成交的报价。"
},
"provider_code": {
"type": "string",
"title": "Provider Code",
"description": "采集该报价的数据来源代码。数据直接来自该市场时等于 `market_code`；否则为报告该市场价格的聚合平台。"
},
"side": {
"type": "string",
"enum": [
"ask",
"bid",
"mid"
],
"title": "Side",
"description": "`ask` 表示在售挂单报价，`bid` 表示求购订单报价，`mid` 表示 `CSCP` 估值（在售共识与求购共识的中间价）。"
},
"market_currency_code": {
"type": "string",
"title": "Market Currency Code",
"description": "`market_price_amount` 的货币，例如 `CNY`。价格以该市场自身的货币返回，不做换算。"
},
"market_price_amount": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Market Price Amount",
"description": "以 `market_currency_code` 计的价格，为十进制字符串（普通记数法，去除末尾的零，从不使用科学记数法）；来源未报告价格时为 `null`。已下架的报价保留最后已知的价格。"
},
"quantity": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Quantity",
"description": "来源报告的市场该方向上的数量；未报告时为 `null`。饰品下架后为 `0`。"
},
"is_quantity_minimum": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Quantity Minimum",
"description": "`quantity` 为下限时为 `true`（来源只报告“至少”这么多）；未知时为 `null`。"
},
"is_all_items_same_price": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is All Items Same Price",
"description": "所有在售单件的价格都等于 `market_price_amount` 时为 `true`；来源只报告最低价或各件价格不同时为 `false`；未知时为 `null`。"
},
"changed_at": {
"type": "string",
"title": "Changed At",
"description": "该报价的价格或数量在来源处最后一次变化的时间，采用 RFC 3339 UTC 格式（例如 `2026-09-24T03:12:08Z`）。"
},
"observed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observed At",
"description": "该报价最后一次在来源处被单独观测到的时间，采用 RFC 3339 UTC 格式；未记录时为 `null`。"
},
"delisted_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Delisted At",
"description": "发现该饰品在市场该方向上已不再挂出的时间，采用 RFC 3339 UTC 格式；仍在挂出时为 `null`。已下架的报价保留最后的价格，`quantity` 为 `0`。"
},
"fresh_at": {
"type": "string",
"title": "Fresh At",
"description": "来源最后一次确认该报价仍为当前值的时间，采用 RFC 3339 UTC 格式：取 `changed_at`、`observed_at` 与该市场最近一次完整扫描完成时间中的最晚者。"
},
"valuation": {
"anyOf": [
{
"$ref": "#/components/schemas/ValuationOut"
},
{
"type": "null"
}
],
"description": "估值详情，仅出现在 `CSCP` 报价上；所有市场报价上均为 `null`。"
}
},
"type": "object",
"required": [
"market_code",
"provider_code",
"side",
"market_currency_code",
"market_price_amount",
"quantity",
"is_quantity_minimum",
"is_all_items_same_price",
"changed_at",
"observed_at",
"delisted_at",
"fresh_at",
"valuation"
],
"title": "MarketQuoteOut",
"description": "单个市场对某个饰品在某一方向上的报价。"
},
"Meta": {
"properties": {
"request_id": {
"type": "string",
"title": "Request Id",
"description": "本次请求的唯一标识符，与响应头 `X-Request-ID` 相同。联系支持时请提供。"
},
"billable": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Billable",
"description": "该请求是否以点数计费。仅出现在计量端点上；`false` 表示该请求免费，例如因为它本身不收费，或已被你的订阅覆盖。"
},
"credit": {
"anyOf": [
{
"$ref": "#/components/schemas/CreditMeta"
},
{
"type": "null"
}
],
"description": "本次请求的费用和你的预估剩余余额。仅在 `billable` 为 `true` 时出现。"
}
},
"type": "object",
"required": [
"request_id"
],
"title": "Meta",
"description": "每个带信封的响应中都包含的请求元数据。"
},
"ValuationOut": {
"properties": {
"valuation_date": {
"type": "string",
"title": "Valuation Date",
"description": "估值的 UTC 日期（`YYYY-MM-DD`）。每天计算一次，依据该日期之前七天的每日收盘报价。"
},
"credibility": {
"type": "number",
"title": "Credibility",
"description": "0 到 1 之间的置信度分数，等于 `e^(-uncertainty)`；越接近 1，各来源越一致。依赖该估值之前请自行设定阈值。"
},
"uncertainty": {
"type": "number",
"title": "Uncertainty",
"description": "估值在对数尺度上的标准不确定度（0 或以上）。约 68% 的合理取值落在 价格 × `e^(-uncertainty)` 与 价格 × `e^(uncertainty)` 之间。"
},
"is_two_sided": {
"type": "boolean",
"title": "Is Two Sided",
"description": "在售挂单与求购订单都参与计算时为 `true`。为 `false` 时只有在售挂单可用，估值为在售共识减去同类饰品的典型半价差。"
},
"ask_amount": {
"type": "string",
"title": "Ask Amount",
"description": "各市场在售挂单的加权共识，按人民币现金买入成本计（含费用），为十进制字符串。"
},
"bid_amount": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bid Amount",
"description": "各市场求购订单的加权共识，按扣除费用后到手的人民币现金计，为十进制字符串；价格高于该市场在售挂单的求购订单已被剔除。`is_two_sided` 为 `false` 时为 `null`。"
},
"ask_quote_count": {
"type": "integer",
"title": "Ask Quote Count",
"description": "`ask_amount` 中在售挂单来源的数量。"
},
"bid_quote_count": {
"type": "integer",
"title": "Bid Quote Count",
"description": "`bid_amount` 中求购订单来源的数量。"
}
},
"type": "object",
"required": [
"valuation_date",
"credibility",
"uncertainty",
"is_two_sided",
"ask_amount",
"bid_amount",
"ask_quote_count",
"bid_quote_count"
],
"title": "ValuationOut",
"description": "饰品的 CSCP 公允价值详情，取自最新一日的估值。"
}
}