POST /v1/archive/buff

本页内容

POST /v1/archive/buff
访问
采样密度
请求
参数
响应
响应字段
采样
错误

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

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

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

访问#

需要 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"
}'

参数#

字段	类型	必需	描述
`items`	`string[]`	是	`market_hash_name` 值列表（最多 100 个）。
`start`	`string`	否	开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。默认为已采集历史的起点。
`end`	`string`	否	结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。

响应#

{
  "response_time": "2026-09-07T03:06:32.382569714Z",
  "currency": "USD",
  "start": "2026-09-03T00:00:00Z",
  "end": "2026-09-06T00:00:00Z",
  "items": {
    "★ Karambit | Doppler (Factory New)": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "count": 23,
      "data": [
        {
          "time": "2026-09-03T00:00:00Z",
          "sale_price": 1872.55,
          "total_supply": 30164
        },
        {
          "time": "2026-09-03T03:00:00Z",
          "sale_price": 1469.43,
          "total_supply": 30164
        }
      ],
      "variants": {
        "Phase 2": {
          "market_hash_name": "★ Karambit | Doppler (Factory New)",
          "name": "★ Karambit | Doppler (Factory New) | Phase 2",
          "display_name": "Phase 2",
          "version": "p2",
          "count": 28,
          "data": [
            {
              "time": "2026-09-03T00:00:00Z",
              "sale_price": 1872.55,
              "total_supply": 7509
            }
          ]
        }
      }
    }
  }
}

响应字段#

ArchiveBuffResponse 字段:

字段	类型	必需	描述
`response_time`	`string (date-time)`	是	响应生成时间。
`currency`	`string`	是	货币代码（始终为 `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。见部分成功和请求错误。