# POST /v1/market/csfloat/orderbook/history

随时间变化的 CSFloat 求购订单簿快照。

返回随时间变化的 CSFloat 求购订单快照（日或小时间隔）。此端点的结构与 [GET /v1/market/csfloat/orderbook/latest](/zh-cn/docs/csfloat-orderbook-latest) 相同。

数据始于 2026 年 8 月 10 日。每次请求最多 100 个饰品。

每个间隔包含该间隔内观测到的最新数据。例如，请求 1h 间隔会返回该小时内*最新*的数据。

## 访问

需要 Scale 或 Enterprise API 密钥。

## 支持的间隔

| 间隔 | 最大范围 |
| --- | --- |
| `1h` | 365 天 |
| `1d` | 不限 |

## 请求

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

**curl**

```bash
curl -X POST https://api.cs2.sh/v1/market/csfloat/orderbook/history \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    "★ Karambit | Doppler (Factory New)"
  ],
  "start": "2026-08-10",
  "end": "2026-08-23",
  "interval": "1h"
}'
```

**Python**

```python
import requests

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

payload = {
    "items": ["★ Karambit | Doppler (Factory New)"],
    "start": "2026-08-10",
    "end": "2026-08-23",
    "interval": "1h",
}

response = requests.post(
    "https://api.cs2.sh/v1/market/csfloat/orderbook/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/csfloat/orderbook/history", {
  method: "POST",
  headers,
  body: JSON.stringify({
    "items": [
      "★ Karambit | Doppler (Factory New)"
    ],
    "start": "2026-08-10",
    "end": "2026-08-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{
            "★ Karambit | Doppler (Factory New)",
        },
        "start": "2026-08-10",
        "end": "2026-08-23",
        "interval": "1h",
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.cs2.sh/v1/market/csfloat/orderbook/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(
    "★ Karambit | Doppler (Factory New)"
  ),
  start = "2026-08-10",
  end = "2026-08-23",
  interval = "1h"
)

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

data <- resp_body_json(resp)
```

## 参数

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `items` | `string[]` | 是 | 基础或 Doppler/Gamma Doppler 相位 `market_hash_name` 值列表（最多 100 个）。 |
| `start` | `string` | 否 | 开始日期/时间（YYYY-MM-DD 或 RFC3339），包含。数据始于 2026-08-10。 |
| `end` | `string` | 否 | 结束日期/时间（YYYY-MM-DD 或 RFC3339），不含。默认现在。 |
| `interval` | `string` | 否 | 默认值: `1h`. 允许值: `1h`, `1d`. 分桶间隔。`1h` 最多 365 天；`1d` 不限。 |

## 响应

```json
{
  "response_time": "2026-08-23T22:00:11.929760469Z",
  "currency": "USD",
  "start": "2026-08-20T00:00:00Z",
  "end": "2026-08-22T00:00:00Z",
  "interval": "1h",
  "items": {
    "★ Karambit | Doppler (Factory New)": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "count": 48,
      "data": [
        {
          "bucket": "2026-08-20T00:00:00Z",
          "updated_at": "2026-08-20T00:55:11.258Z",
          "collected_at": "2026-08-20T00:56:10.301Z",
          "top_generic_bid": null,
          "orders": [
            {
              "price": 6550,
              "quantity": 1,
              "kind": "paint_index",
              "conditions": {
                "paint_index": 417
              }
            },
            {
              "price": 4290,
              "quantity": 1,
              "kind": "paint_index",
              "conditions": {
                "paint_index": 416
              }
            }
          ]
        }
      ],
      "variants": {
        "Phase 2": {
          "market_hash_name": "★ Karambit | Doppler (Factory New)",
          "name": "★ Karambit | Doppler (Factory New) | Phase 2",
          "display_name": "Phase 2",
          "version": "p2",
          "count": 46,
          "data": [
            {
              "bucket": "2026-08-20T00:00:00Z",
              "updated_at": "2026-08-20T00:57:14.824Z",
              "collected_at": "2026-08-20T00:58:10.396Z",
              "top_generic_bid": 1230,
              "orders": [
                {
                  "price": 1630,
                  "quantity": 1,
                  "kind": "paint_index",
                  "conditions": {
                    "paint_index": 419
                  }
                },
                {
                  "price": 1620,
                  "quantity": 1,
                  "kind": "paint_index",
                  "conditions": {
                    "paint_index": 419
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}
```

## 响应字段

[CSFloatBuyOrdersHistoryResponse](/zh-cn/docs/objects#csfloatbuyordershistoryresponse) 字段:

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 生成响应的时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询区间的有效起点，向下对齐到间隔边界。包含。 |
| `end` | `string (date-time)` | 是 | 查询区间的有效终点，向上对齐到间隔边界。不含。 |
| `interval` | `string` | 是 | 允许值: `1h`, `1d`. 请求的分桶间隔。 |
| `items` | [`Record<string, CSFloatBuyOrdersHistoryItem>`](/zh-cn/docs/objects#csfloatbuyordershistoryitem) | 是 | `market_hash_name` 到所返回求购订单簿历史的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果一并返回的逐饰品错误（部分成功）。 |

## 采样分桶

| 字段 | 描述 |
| --- | --- |
| `items.<name>.count` | 有数据的分桶数。 |
| `items.<name>.data[]` | 求购订单簿：每个 `bucket` 内最新的观测。 |
| `items.<name>.variants` | Doppler 和 Gamma Doppler 相位序列，以显示名称为键。 |
| `data[].orders` | 求购订单阶梯，按价格降序，结构与 `GET /v1/market/csfloat/orderbook/latest` 相同。 |
| `data[].top_generic_bid` | 无条件订单中的最高价格；仅存在条件订单时为 `null`。 |
| `data[].updated_at`、`collected_at` | CSFloat 的更新时间与 cs2.sh 的抓取时间。 |

- 仅请求相位名（例如 `★ Karambit | Doppler (Factory New) | Phase 2`）时，该相位仍嵌套在其基础条目下返回。

## 求购订单条件

| `kind` | 含义 |
| --- | --- |
| `generic` | 无条件。`conditions` 为 `{}`。 |
| `paint_index` | 挂单的 paint index 必须匹配。 |
| `float` | 挂单的磨损值必须位于给定范围内。 |
| `sticker` | 挂单必须满足指定的印花要求。 |
| `keychain_pattern` | 已挂挂件的图案值必须位于给定范围内。 |
| `paint_seeds` | 挂单的 paint seed 必须是给定值之一。 |
| `keychain` | 挂单必须具有指定挂件。 |
| `mixed` | 挂单必须同时满足所有给定条件类别。 |

| `conditions` 键 | 类型 | 含义 |
| --- | --- | --- |
| `paint_index` | `integer` | 挂单的 paint index 必须等于此值。 |
| `min_float` | `number` | 挂单的磨损值必须大于或等于此值。 |
| `max_float` | `number` | 挂单的磨损值必须小于或等于此值。 |
| `stickers` | [`CSFloatStickerCondition[]`](/zh-cn/docs/objects#csfloatstickercondition) | 挂单必须满足每项印花要求。同一 `sId` 重复出现表示要求多枚该印花。 |
| `min_keychain_pattern` | `integer` | 已挂挂件的图案值必须大于或等于此值。 |
| `max_keychain_pattern` | `integer` | 已挂挂件的图案值必须小于或等于此值。 |
| `paint_seeds` | `integer[]` | 挂单的 paint seed 必须等于其中一个值。 |
| `keychains` | [`CSFloatKeychainCondition[]`](/zh-cn/docs/objects#csfloatkeychaincondition) | 挂单必须具有此数组中标识的每个挂件。 |

存在多个条件字段时，挂单必须全部满足。`mixed` 订单还可以原样包含其他 CSFloat 条件键。

印花要求：

| 字段 | 类型 | 必需 | 含义 |
| --- | --- | --- | --- |
| `sId` | `integer` | 是 | 挂单必须具有的印花的 CSFloat 数字 ID。 |
| `s` | `integer` | 否 | 必须贴有此印花的槽位，从零开始。省略时，该印花可位于任意槽位。 |

挂件要求：

| 字段 | 类型 | 必需 | 含义 |
| --- | --- | --- | --- |
| `sId` | `integer` | 是 | 挂单必须具有的挂件的 CSFloat 数字 ID。 |

完整结构：[CSFloatBuyOrdersHistoryItem](/zh-cn/docs/objects#csfloatbuyordershistoryitem)、[CSFloatBuyOrdersHistoryVariant](/zh-cn/docs/objects#csfloatbuyordershistoryvariant)、[CSFloatBuyOrdersHistoryPoint](/zh-cn/docs/objects#csfloatbuyordershistorypoint)、[CSFloatBuyOrder](/zh-cn/docs/objects#csfloatbuyorder)、[CSFloatBuyOrderConditions](/zh-cn/docs/objects#csfloatbuyorderconditions)、[CSFloatStickerCondition](/zh-cn/docs/objects#csfloatstickercondition)、[CSFloatKeychainCondition](/zh-cn/docs/objects#csfloatkeychaincondition)。

### CSFloatBuyOrdersHistoryItem

一个基础饰品的 CSFloat 求购订单簿历史。相位序列嵌套在 `variants` 下。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范化的 Steam `market_hash_name`。 |
| `count` | `integer` | 是 | `data` 中的数据点数量。 |
| `data` | [CSFloatBuyOrdersHistoryPoint[]](/zh-cn/docs/objects#csfloatbuyordershistorypoint) | 是 | 按时间顺序排列的数据点。 |
| `variants` | [`Record<string, CSFloatBuyOrdersHistoryVariant>`](/zh-cn/docs/objects#csfloatbuyordershistoryvariant) | 否 | 以显示名称为键的 Doppler 和 Gamma Doppler 相位序列。 |

### CSFloatBuyOrdersHistoryVariant

一个 Doppler 或 Gamma Doppler 相位的 CSFloat 求购订单簿历史。

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

### CSFloatBuyOrdersHistoryPoint

一个 UTC 分桶内观测到的最新求购订单簿。这是某一时刻的订单簿状态，而非 OHLC 数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | UTC 分桶起点。 |
| `updated_at` | `string (date-time)` | 是 | CSFloat 最后更新此分桶所代表订单簿的时间。 |
| `collected_at` | `string (date-time)` | 是 | cs2.sh 采集此分桶所代表订单簿的时间。 |
| `top_generic_bid` | `number \| null` | 是 | 无条件订单中的最高价格（USD）。仅存在条件订单时为 `null`。 |
| `orders` | [CSFloatBuyOrder[]](/zh-cn/docs/objects#csfloatbuyorder) | 是 | 按价格降序的订单阶梯。 |

### CSFloatBuyOrder

一条挂起的 CSFloat 求购订单。其条件位于 `conditions` 中。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `price` | `number` | 是 | 订单价格（USD）。 |
| `quantity` | `integer` | 否 | 该价格下求购的饰品数量。 |
| `kind` | `string` | 是 | 允许值: `generic`, `paint_index`, `float`, `sticker`, `keychain_pattern`, `paint_seeds`, `keychain`, `mixed`. `conditions` 中匹配规则的摘要。`generic` 没有规则；`mixed` 包含多类规则或 API 无法识别的上游规则。 |
| `conditions` | [CSFloatBuyOrderConditions](/zh-cn/docs/objects#csfloatbuyorderconditions) | 是 | 挂单必须满足这些规则，此求购订单才会买入。存在多条规则时必须全部满足。`generic` 订单为空。`mixed` 订单还可能原样携带 API 无法识别的 CSFloat 规则键。 |

### CSFloatBuyOrderConditions

挂单必须满足这些规则，此求购订单才会买入。存在多条规则时必须全部满足。`generic` 订单为空。`mixed` 订单还可能原样携带 API 无法识别的 CSFloat 规则键。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `paint_index` | `integer` | 否 | 挂单的 paint index 必须等于此值。 |
| `min_float` | `number` | 否 | 挂单的磨损值必须大于或等于此值。 |
| `max_float` | `number` | 否 | 挂单的磨损值必须小于或等于此值。 |
| `stickers` | [CSFloatStickerCondition[]](/zh-cn/docs/objects#csfloatstickercondition) | 否 | 挂单必须满足此数组中的每项印花要求。同一印花 ID 重复出现表示要求多枚该印花。 |
| `min_keychain_pattern` | `integer` | 否 | 已挂挂件的图案值必须大于或等于此值。 |
| `max_keychain_pattern` | `integer` | 否 | 已挂挂件的图案值必须小于或等于此值。 |
| `paint_seeds` | `integer[]` | 否 | 挂单的 paint seed 必须等于其中一个值。 |
| `keychains` | [CSFloatKeychainCondition[]](/zh-cn/docs/objects#csfloatkeychaincondition) | 否 | 挂单必须具有此数组中标识的每个挂件。 |

### CSFloatStickerCondition

挂单必须具有的一枚印花。上游 CSFloat 的其他字段会原样保留。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `sId` | `integer` | 是 | 挂单必须具有的印花的 CSFloat 数字 ID。 |
| `s` | `integer` | 否 | 必须贴有此印花的槽位，从零开始。省略时，该印花可位于任意槽位。 |

### CSFloatKeychainCondition

挂单必须具有的一个挂件。上游 CSFloat 的其他字段会原样保留。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `sId` | `integer` | 是 | 挂单必须具有的挂件的 CSFloat 数字 ID。 |

## 错误

如果只有部分饰品名称失败，端点仍返回 `200`，其中包含成功的序列和 `errors[]`。没有 CSFloat paint index 的变体（Marble Fade、Case Hardened 以及其他按图案定价的系列）使用 `unsupported_variant`。见[部分成功](/zh-cn/docs/using-the-api#部分成功)和[请求错误](/zh-cn/docs/using-the-api#请求错误)。