# POST /v1/market/buff/history

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

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

来自 [GET /v1/market/buff/latest](/zh-cn/docs/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 采集时间。

## 请求

`POST https://api.cs2.sh/v1/market/buff/history`

**curl**

```bash
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"
}'
```

**Python**

```python
import requests

headers = {
    "Authorization": "Bearer <<YOUR_API_KEY>>",
    "Accept-Encoding": "gzip",
    "Content-Type": "application/json",
}

payload = {
    "items": ["★ Bayonet | Fade (Factory New)", "AK-47 | Case Hardened (Field-Tested)"],
    "start": "2026-07-20",
    "end": "2026-07-23",
    "interval": "1h",
}

response = requests.post(
    "https://api.cs2.sh/v1/market/buff/history",
    headers=headers,
    json=payload,
)

response.raise_for_status()
data = response.json()
```

**Node**

```javascript
const headers = {
  "Authorization": "Bearer <<YOUR_API_KEY>>",
  "Accept-Encoding": "gzip",
  "Content-Type": "application/json",
};

const response = await fetch("https://api.cs2.sh/v1/market/buff/history", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "items": [
      "★ Bayonet | Fade (Factory New)",
      "AK-47 | Case Hardened (Field-Tested)"
    ],
    "start": "2026-07-20",
    "end": "2026-07-23",
    "interval": "1h"
  }),
});

if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
```

**Go**

```go
package main

import (
    "bytes"
    "compress/gzip"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload := map[string]any{
        "items": []any{
            "★ Bayonet | Fade (Factory New)",
            "AK-47 | Case Hardened (Field-Tested)",
        },
        "start": "2026-07-20",
        "end": "2026-07-23",
        "interval": "1h",
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.cs2.sh/v1/market/buff/history", bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer <<YOUR_API_KEY>>")
    req.Header.Set("Accept-Encoding", "gzip")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode < 200 || resp.StatusCode >= 300 {
        body, _ := io.ReadAll(resp.Body)
        panic(fmt.Sprintf("HTTP %d: %s", resp.StatusCode, body))
    }

    var reader io.Reader = resp.Body
    if resp.Header.Get("Content-Encoding") == "gzip" {
        gz, err := gzip.NewReader(resp.Body)
        if err != nil { panic(err) }
        defer gz.Close()
        reader = gz
    }

    var data any
    if err := json.NewDecoder(reader).Decode(&data); err != nil { panic(err) }
    fmt.Printf("%#v\n", data)
}
```

**R**

```r
library(httr2)

payload <- list(
  items = list(
    "★ Bayonet | Fade (Factory New)",
    "AK-47 | Case Hardened (Field-Tested)"
  ),
  start = "2026-07-20",
  end = "2026-07-23",
  interval = "1h"
)

resp <- request("https://api.cs2.sh/v1/market/buff/history") |>
  req_headers(
    Authorization = "Bearer <<YOUR_API_KEY>>",
    `Accept-Encoding` = "gzip"
  ) |>
  req_body_json(payload) |>
  req_perform()

data <- resp_body_json(resp)
```

## 参数

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

## 响应

```json
{
  "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](/zh-cn/docs/objects#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>`](/zh-cn/docs/objects#buffmarketfloathistoryitem) | 是 | `market_hash_name` 到逐饰品 BUFF 历史的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#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](/zh-cn/docs/objects#buffmarketfloathistoryitem)、[BUFFMarketFloatHistoryBucket](/zh-cn/docs/objects#buffmarketfloathistorybucket)、[BUFFMarketFloatHistoryPoint](/zh-cn/docs/objects#buffmarketfloathistorypoint)。

### BUFFMarketFloatHistoryItem

单件饰品的 BUFF 市场磨损/渐变 OHLC 历史。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范化的基础 `market_hash_name`。 |
| `buckets` | [BUFFMarketFloatHistoryBucket[]](/zh-cn/docs/objects#buffmarketfloathistorybucket) | 否 | 基础饰品挂单各区间的 OHLC 历史。 |
| `variants` | [`Record<string, BUFFMarketFloatHistoryVariant>`](/zh-cn/docs/objects#buffmarketfloathistoryvariant) | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 OHLC 历史。按显示名称作为键。 |

### BUFFMarketFloatHistoryBucket

单个 BUFF 市场区间的 OHLC 历史。`data` 按时间顺序排列，每项对应一个间隔。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket_id` | `string` | 是 | 稳定的区间标识（例如 `fade:99:100`、`variant:p2\|float:0.00:0.01`）。 |
| `bucket_type` | `string` | 是 | 允许值: `base`, `float`, `fade`, `float_fade`. 区间分层，参见 `BUFFMarketFloatLatestBucket.bucket_type`。 |
| `float` | [BUFFMarketFloatRange](/zh-cn/docs/objects#buffmarketfloatrange) | 否 | `float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。 |
| `fade` | [BUFFMarketFloatRange](/zh-cn/docs/objects#buffmarketfloatrange) | 否 | `float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。 |
| `data` | [BUFFMarketFloatHistoryPoint[]](/zh-cn/docs/objects#buffmarketfloathistorypoint) | 是 | 该区间的 OHLC 观测，按时间顺序排列。 |

### BUFFMarketFloatHistoryPoint

BUFF 市场磨损/渐变区间历史中的单个 OHLC 观测点。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | OHLC 间隔的开始时间（UTC 对齐到间隔边界）。 |
| `updated_at` | `string (date-time)` | 否 | BUFF 在此间隔内最后一次刷新该区间的时间。 |
| `collected_at` | `string (date-time)` | 否 | cs2.sh 在此间隔内抓取源数据行的时间。 |
| `open_ask` | `number` | 否 | 间隔内首次观测的挂单价（USD）。 |
| `high_ask` | `number` | 否 | 间隔内最高挂单价（USD）。 |
| `low_ask` | `number` | 否 | 间隔内最低挂单价（USD）。 |
| `close_ask` | `number` | 否 | 间隔内最后一次挂单价（USD）。 |
| `open_avg_ask` | `number` | 否 | 间隔内首次观测的 `avg_ask` 值。 |
| `high_avg_ask` | `number` | 否 | 间隔内最高 `avg_ask` 值。 |
| `low_avg_ask` | `number` | 否 | 间隔内最低 `avg_ask` 值。 |
| `close_avg_ask` | `number` | 否 | 间隔内最后一次 `avg_ask` 值。 |
| `open_bid` | `number` | 否 | 间隔内首次观测的求购价（USD）。 |
| `high_bid` | `number` | 否 | 间隔内最高求购价（USD）。 |
| `low_bid` | `number` | 否 | 间隔内最低求购价（USD）。 |
| `close_bid` | `number` | 否 | 间隔内最后一次求购价（USD）。 |
| `ask_volume` | `integer` | 否 | 间隔内最后一次观测的挂单数量。 |
| `bid_volume` | `integer` | 否 | 间隔内最后一次观测的求购单数量。 |
| `open_time` | `string (date-time)` | 是 | 间隔内首次观测的时间戳。与 `bucket`（间隔边界）不同。 |
| `close_time` | `string (date-time)` | 是 | 间隔内最后一次观测的时间戳。与 `bucket`（间隔边界）不同。 |

## 错误

`404 not_found` 表示请求中的有效饰品均没有 BUFF 区间历史。部分结果返回 `200` 和 `errors[]`；饰品错误代码包括 `unknown_item`、`invalid_format` 和 `not_in_cache`。见[部分成功](/zh-cn/docs/using-the-api#部分成功)和[请求错误](/zh-cn/docs/using-the-api#请求错误)。