POST /v1/archive/buff

本页内容

POST /v1/archive/buff
访问
数据粒度
请求
参数
响应
响应字段
成交
错误

返回 BUFF 成交趋势图表中的成交价和每日总供应量。

成交价自 2024 年 9 月 6 日起
每日 total_supply 自 2024 年 9 月 6 日起（仅限 BUFF 有报告的饰品）

数据每天约更新 1 次。每次请求最多 100 个饰品。

BUFF 变体数据包含：Dopplers、Gamma Dopplers、Case Hardened、Marble Fade Fire & Ice 和 Crimson Kimono。

访问#

需要 Scale 或 Enterprise API 密钥。

数据粒度#

BUFF 对近期历史的更新频率高于早期历史。只有发生成交的地方才有数据点，因此流动性差的饰品在每个区间的间隔都更大。

自	典型成交价频率
2026 年 9 月	1-3 小时
2026 年 8 月	约 12 小时
2026 年 3 月	约 2 天
2025 年 9 月	约 4 天
2024 年 9 月	约 6 天

请求#

POSTapi.cs2.sh/v1/archive/buff

curl -X POST https://api.cs2.sh/v1/archive/buff \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    "★ Karambit | Doppler (Factory New)"
  ],
  "start": "2024-09-01",
  "end": "2026-09-07",
  "currency": "USD"
}'

参数#

字段	类型	必需	描述
`items`	`string[]`	是	`market_hash_name` 值列表（最多 100 个）。
`start`	`string`	否	开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。默认为已采集历史的起点。
`end`	`string`	否	结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。
`currency`	`string`	否	默认值: `USD`. 允许值: `AUD`, `CAD`, `CHF`, `CNY`, `EUR`, `GBP`, `JPY`, `NZD`, `SGD`, `USD`. 响应中所有价格使用的货币。

响应#

{
  "response_time": "2026-09-06T00:30:00Z",
  "currency": "USD",
  "start": "2026-09-03T13:00:00Z",
  "end": "2026-09-03T20:00:00Z",
  "items": {
    "AK-47 | Redline (Field-Tested)": {
      "market_hash_name": "AK-47 | Redline (Field-Tested)",
      "count": 4,
      "data": [
        {
          "time": "2026-09-03T13:00:00Z",
          "sale_price": 38.07,
          "total_supply": 350680
        },
        {
          "time": "2026-09-03T15:00:00Z",
          "sale_price": 52.42,
          "total_supply": 350680
        },
        {
          "time": "2026-09-03T16:00:00Z",
          "sale_price": 62.04,
          "total_supply": 350713
        },
        {
          "time": "2026-09-03T19:00:00Z",
          "sale_price": 41.63,
          "total_supply": 350713
        }
      ]
    }
  }
}

响应字段#

ArchiveBuffResponse 字段:

字段	类型	必需	描述
`response_time`	`string (date-time)`	是	响应生成时间。
`currency`	`string`	是	sale_price 的货币单位：即请求的 `currency`，默认为 `USD`。
`start`	`string (date-time)`	是	查询区间的有效起点，与请求或默认值完全一致。包含。
`end`	`string (date-time)`	是	查询区间的有效终点，与请求或默认值完全一致。不含。
`items`	`Record<string, ArchiveBuffItem>`	是	`market_hash_name` 到 BUFF 成交序列的映射。
`errors`	ItemError[]	否	与成功结果并存的按饰品失败（部分成功）。

成交#

字段	描述
`items.<name>.count`	数据点数量。
`items.<name>.data[]`	BUFF 成交。
`data[].time`	成交时间。
`data[].sale_price`	成交价，美元，按成交日期的汇率转换。
`data[].total_supply`	BUFF 报告的该成交当天（UTC+8）的总供应量。
`items.<name>.variants`	每个变体的相同结构。

每个数据点上都存在 time。
当成交日期的汇率尚未存储，或该日期仅有供应量时，sale_price 可以是 null。
当 BUFF 当天没有报告供应量时，total_supply 可以是 null。
有供应量但没有成交的日期返回一个中国时区零点（UTC 16:00）的仅供应量数据点。
count 是数据点数量，不是成交量。
当该变体存在 BUFF 成交历史时，变体出现在 variants 下。
没有 BUFF 成交历史的有效请求饰品返回 not_in_archive。

完整结构：ArchiveBuffItem、ArchiveBuffVariant、ArchiveBuffPoint。

错误#

404 not_found 表示请求中的有效饰品在该时间范围内均没有 BUFF 成交历史。部分结果返回 200 和 errors[]；饰品错误代码包括 unknown_item、invalid_format 和 not_in_archive。见部分成功和请求错误。