POST /v1/market/buff/history

本页内容

POST /v1/market/buff/history
访问
支持的间隔
请求
参数
响应
响应字段
区间历史
错误

返回 BUFF 磨损与渐变区间的 OHLC 历史。数据自 2026 年 5 月 19 日起。

来自 GET /v1/market/buff/latest 的每个区间都拥有独立的时间序列，包括 Doppler、Gamma Doppler 和 Case Hardened 变体区间。OHLC 同时计算 ask、avg_ask 与 bid；ask_volume 与 bid_volume 为间隔内最后观测值。数据每 10 分钟更新一次。每次请求最多 100 个饰品。

访问#

需要 Scale 或 Enterprise API 密钥。

支持的间隔#

间隔	最大范围
`30m`	90 天
`1h`	365 天
`1d`	不限

bucket 是 UTC 间隔的开始时间。open_time 与 close_time 是间隔内实际首次和最后一次观测的时间。updated_at 是该分桶所代表的 BUFF 最后更新时间，collected_at 是该分桶所代表的 cs2.sh 采集时间。

请求#

POSTapi.cs2.sh/v1/market/buff/history

curl -X POST https://api.cs2.sh/v1/market/buff/history \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    "★ Bayonet | Fade (Factory New)",
    "AK-47 | Case Hardened (Field-Tested)"
  ],
  "start": "2026-07-20",
  "end": "2026-07-23",
  "interval": "1h"
}'

参数#

字段	类型	必需	描述
`items`	`string[]`	是	`market_hash_name` 值列表（最多 100 个）
`start`	`string`	是	开始日期/时间（YYYY-MM-DD 或 RFC3339）
`end`	`string`	否	结束日期/时间（YYYY-MM-DD 或 RFC3339）。默认现在。
`interval`	`string`	否	默认值: `30m`. 允许值: `30m`, `1h`, `1d`.

响应#

{
  "response_time": "2026-07-26T18:54:21.429446677Z",
  "currency": "USD",
  "start": "2026-07-20T00:00:00Z",
  "end": "2026-07-23T00:00:00Z",
  "interval": "1h",
  "items": {
    "★ Bayonet | Fade (Factory New)": {
      "market_hash_name": "★ Bayonet | Fade (Factory New)",
      "buckets": [
        {
          "bucket_id": "base",
          "bucket_type": "base",
          "data": [
            {
              "bucket": "2026-07-20T00:00:00Z",
              "updated_at": "2026-07-20T00:46:24Z",
              "collected_at": "2026-07-20T00:50:57.483Z",
              "open_ask": 371.36,
              "high_ask": 371.57,
              "low_ask": 371.36,
              "close_ask": 371.57,
              "open_avg_ask": 379.74,
              "high_avg_ask": 379.96,
              "low_avg_ask": 379.74,
              "close_avg_ask": 379.96,
              "open_bid": 359.57,
              "high_bid": 359.78,
              "low_bid": 359.57,
              "close_bid": 359.78,
              "ask_volume": 177,
              "bid_volume": 23,
              "open_time": "2026-07-20T00:00:53.231Z",
              "close_time": "2026-07-20T00:50:57.483Z"
            }
          ]
        }
      ]
    }
  }
}

响应字段#

BUFFMarketFloatHistoryResponse 字段:

字段	类型	必需	描述
`response_time`	`string (date-time)`	是	响应生成时间。
`currency`	`string`	是	货币代码（始终为 `USD`）。
`start`	`string (date-time)`	是	查询区间的有效起点，向下对齐到间隔边界。
`end`	`string (date-time)`	是	查询区间的有效终点，向上对齐到间隔边界。不含。
`interval`	`string`	是	允许值: `30m`, `1h`, `1d`. OHLC 分桶粒度。
`items`	`Record<string, BUFFMarketFloatHistoryItem>`	是	`market_hash_name` 到逐饰品 BUFF 历史的映射。
`errors`	ItemError[]	否	部分成功响应中按饰品的错误列表。

区间历史#

字段	描述
`items.<name>.buckets[]`	该饰品的价格区间，其标识（`bucket_id`、`bucket_type`、`float`/`fade`）与 `GET /v1/market/buff/latest` 一致。
`buckets[].data[]`	该区间的 OHLC 数据点。
`data[].bucket`	UTC 间隔边界。
`data[].open_time`、`close_time`	分桶内真实的第一次和最后一次观测时间戳。
`data[].ask`、`avg_ask`、`bid`	OHLC 值。
`data[].ask_volume`、`bid_volume`	分桶内最后观测的成交量。
`items.<name>.variants`	按变体显示名称嵌套的相同区间历史。

float 出现在 float 和 float_fade 区间上；fade 出现在 fade 和 float_fade 区间上。

完整结构：BUFFMarketFloatHistoryItem、BUFFMarketFloatHistoryBucket、BUFFMarketFloatHistoryPoint。

错误#

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