# POST /v1/archive/buff

自 2024 年 9 月 6 日起的 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 天 |

## 请求

`POST https://api.cs2.sh/v1/archive/buff`

**curl**

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

**Python**

```python
import requests

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

payload = {
    "items": ["★ Karambit | Doppler (Factory New)"],
    "start": "2024-09-01",
    "end": "2026-09-07",
}

response = requests.post(
    "https://api.cs2.sh/v1/archive/buff",
    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/archive/buff", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "items": [
      "★ Karambit | Doppler (Factory New)"
    ],
    "start": "2024-09-01",
    "end": "2026-09-07"
  }),
});

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{
            "★ Karambit | Doppler (Factory New)",
        },
        "start": "2024-09-01",
        "end": "2026-09-07",
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.cs2.sh/v1/archive/buff", 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(
    "★ Karambit | Doppler (Factory New)"
  ),
  start = "2024-09-01",
  end = "2026-09-07"
)

resp <- request("https://api.cs2.sh/v1/archive/buff") |>
  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），不含。默认现在。 |

## 响应

```json
{
  "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](/zh-cn/docs/objects#archivebuffresponse) 字段:

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询区间的有效起点，与请求或默认值完全一致。包含。 |
| `end` | `string (date-time)` | 是 | 查询区间的有效终点，与请求或默认值完全一致。不含。 |
| `items` | [`Record<string, ArchiveBuffItem>`](/zh-cn/docs/objects#archivebuffitem) | 是 | `market_hash_name` 到 BUFF 成交序列的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#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](/zh-cn/docs/objects#archivebuffitem)、[ArchiveBuffVariant](/zh-cn/docs/objects#archivebuffvariant)、[ArchiveBuffPoint](/zh-cn/docs/objects#archivebuffpoint)。

### ArchiveBuffItem

单件饰品的 BUFF 成交采样与每日供应量，作为一条按时间顺序排列的序列。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 基础饰品的 `market_hash_name`。 |
| `count` | `integer` | 是 | `data` 中的数据点数量。 |
| `data` | [ArchiveBuffPoint[]](/zh-cn/docs/objects#archivebuffpoint) | 是 | 按时间顺序排列的成交采样和仅供应量数据点，每个时间戳一个点。 |
| `variants` | [`Record<string, ArchiveBuffVariant>`](/zh-cn/docs/objects#archivebuffvariant) | 否 | 具有 Doppler、Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 BUFF 序列。以显示名称为键，为空时省略。变体序列绝不会回退到基础饰品历史。 |

### ArchiveBuffVariant

一个 Doppler 或 Gamma Doppler 相位或 Case Hardened 分层的 BUFF 成交采样与每日供应量。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 基础饰品的 `market_hash_name`。完整变体名称见 `name`。 |
| `name` | `string` | 是 | 变体的完整 `market_hash_name`，例如 `★ Karambit \| Doppler (Factory New) \| Phase 2`。 |
| `display_name` | `string` | 是 | 人类可读的变体标签（例如 `Phase 1`、`Ruby`、`Tier 1`、`Blue Gem`）。 |
| `version` | `string` | 是 | 稳定变体代码。客户端代码应基于此切换。 |
| `count` | `integer` | 是 | `data` 中的数据点数量。 |
| `data` | [ArchiveBuffPoint[]](/zh-cn/docs/objects#archivebuffpoint) | 是 | 按时间顺序排列的成交采样和仅供应量数据点，每个时间戳一个点。 |

### ArchiveBuffPoint

BUFF 成交价格图表上的一个采样，或当天没有成交采样时的仅供应量数据点。采样是图表上的点，不是经核实的单笔成交，BUFF 也不提供成交量。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `time` | `string (date-time)` | 是 | BUFF 图表上的采样时间，UTC。仅供应量数据点使用中国时区零点（UTC 16:00）的时间戳。 |
| `sale_price` | `number \| null` | 是 | 成交价（USD），按成交日期的历史汇率由 CNY 换算。仅供应量数据点，以及成交日期尚未存储汇率的成交，为 `null`。 |
| `total_supply` | `integer \| null` | 是 | BUFF 在该采样所属中国自然日（UTC+8）报告的总供应量。当天没有报告供应量时为 `null`。 |

## 错误

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