# API 对象

cs2.sh API 中使用的响应对象结构。

cs2.sh API 的响应对象字段参考。

## 对象分组

- [响应封装](#响应封装)
- [饰品对象](#饰品对象)
- [历史分桶](#历史分桶)
- [最新价格来源数据](#最新价格来源数据)
- [OHLC 来源数据](#ohlc-来源数据)
- [饰品 Schema](#饰品-schema)
- [健康状态](#健康状态)
- [错误](#错误)

## 响应封装

### LatestPricesGetResponse

全量饰品快照。由 `GET /v1/prices/latest` 返回，带有共享响应元数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`） |
| `items` | [`Record<string, Item>`](/zh-cn/docs/objects#item) | 是 | `market_hash_name` 到饰品价格数据的映射。 |

### LatestPricesPostResponse

按饰品过滤的快照。由 `POST /v1/prices/latest` 返回，包含逐饰品 `errors`。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`） |
| `items` | [`Record<string, Item>`](/zh-cn/docs/objects#item) | 是 | `market_hash_name` 到饰品价格数据的映射，过滤到请求的饰品。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果一起返回的逐饰品失败（部分成功）。 |

### HistoryResponse

`POST /v1/prices/history` 的响应结构。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询范围的有效开始时间，向下取整到间隔边界。 |
| `end` | `string (date-time)` | 是 | 查询范围的有效结束时间，向上取整到间隔边界。不包含该时间。 |
| `interval` | `string` | 是 | 允许值: `5m`, `30m`, `1h`, `1d`. OHLC 分桶大小。 |
| `items` | [`Record<string, HistoryItem>`](/zh-cn/docs/objects#historyitem) | 是 | `market_hash_name` 到 OHLC 时间序列的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果一起返回的逐饰品失败（部分成功）。 |

### ItemLiquidityGetResponse

全量饰品流动性快照。由 `GET /v1/liquidity/items` 返回。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 快照计算时间。 |
| `run_date` | `string (date)` | 是 | 每日计算对应的 UTC 日期。 |
| `items` | [`Record<string, ItemLiquidityItem>`](/zh-cn/docs/objects#itemliquidityitem) | 是 | `market_hash_name` 到饰品流动性数据的映射。 |

### BUFFMarketFloatLatestResponse

所有饰品的 BUFF 磨损与渐变范围快照。由 `GET /v1/market/buff/latest` 返回；所有价格均为 USD。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `items` | [`Record<string, BUFFMarketFloatItem>`](/zh-cn/docs/objects#buffmarketfloatitem) | 是 | `market_hash_name` 到逐饰品 BUFF 数据的映射。 |

### BUFFMarketFloatHistoryResponse

由 `POST /v1/market/buff/history` 返回的响应。每个请求的 BUFF 市场磨损/渐变区间都会带有 OHLC 历史。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `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) | 否 | 部分成功响应中按饰品的错误列表。 |

### ArchiveCSFloatResponse

`POST /v1/archive/csfloat` 的响应结构。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询范围的有效开始时间，向下取整到日边界。 |
| `end` | `string (date-time)` | 是 | 查询范围的有效结束时间，向上取整到日边界。不包含该时间。 |
| `items` | [`Record<string, ArchiveCSFloatItem>`](/zh-cn/docs/objects#archivecsfloatitem) | 是 | `market_hash_name` 到 CSFloat 成交时间序列的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果一起返回的逐饰品失败（部分成功）。 |

### ArchiveHistoryResponse

`POST /v1/archive/history` 的响应结构。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询范围的有效开始时间，向下取整到间隔边界。 |
| `end` | `string (date-time)` | 是 | 查询范围的有效结束时间，向上取整到间隔边界。不包含该时间。 |
| `interval` | `string` | 是 | 允许值: `1h`, `1d`. 归档分桶大小。 |
| `items` | [`Record<string, ArchiveHistoryItem>`](/zh-cn/docs/objects#archivehistoryitem) | 是 | `market_hash_name` 到归档时间序列的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果一起返回的逐饰品失败（部分成功）。 |

### ArchiveSteamResponse

`POST /v1/archive/steam` 的响应结构。合法常规饰品无数据时返回饰品级 `not_in_archive`；如果每个合法常规饰品均无数据，端点返回 `404 not_found`。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 规范化 UTC 起点，包含。 |
| `end` | `string (date-time)` | 是 | 规范化 UTC 终点，不含。 |
| `interval` | `string` | 是 | 允许值: `1h`, `1d`. 每个返回分桶对应的请求的原生 Steam 间隔。 |
| `items` | [`Record<string, ArchiveSteamItem>`](/zh-cn/docs/objects#archivesteamitem) | 是 | `market_hash_name` 到原生 Steam 成交历史分桶的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 部分成功响应中按饰品的错误列表。 |

### ArchiveYoupinResponse

`POST /v1/archive/youpin` 的响应结构。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 查询范围的实际起点，向下取整到 1h 边界。 |
| `end` | `string (date-time)` | 是 | 查询范围的实际终点，向上取整到 1h 边界。不含。 |
| `items` | [`Record<string, ArchiveYoupinItem>`](/zh-cn/docs/objects#archiveyoupinitem) | 是 | `market_hash_name` 到 Youpin 成交序列的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 与成功结果并存的按饰品失败（部分成功）。 |

### SteamOrderbookLatestResponse

所有被追踪常规饰品的最新 Steam 订单簿快照。由 `GET /v1/market/steam/latest` 返回；不支持变体。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 此快照响应的生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `as_of` | `string (date-time)` | 是 | 整个快照中最新的 `updated_at`。 |
| `items` | [`Record<string, SteamOrderbookItem>`](/zh-cn/docs/objects#steamorderbookitem) | 是 | 具有当前订单簿数据的常规饰品，按 `market_hash_name` 键控。 |

### SteamOrderbookHistoryResponse

`POST /v1/market/steam/history` 的响应结构。有合法常规饰品但无数据时会从 `items` 中省略；如果所有合法常规饰品均无数据，则 `items` 为空。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `response_time` | `string (date-time)` | 是 | 响应生成时间。 |
| `currency` | `string` | 是 | 货币代码（始终为 `USD`）。 |
| `start` | `string (date-time)` | 是 | 规范化 UTC 起点，包含。 |
| `end` | `string (date-time)` | 是 | 规范化 UTC 终点，不含。 |
| `interval` | `string` | 是 | 允许值: `1h`, `1d`. 请求的分桶间隔。 |
| `items` | [`Record<string, SteamOrderbookHistoryItem>`](/zh-cn/docs/objects#steamorderbookhistoryitem) | 是 | `market_hash_name` 到返回订单簿历史的映射。 |
| `errors` | [ItemError[]](/zh-cn/docs/objects#itemerror) | 否 | 部分成功响应中按饰品的错误列表。 |

### SchemaResponse

`GET /v1/schema` 的响应结构：按 `market_hash_name` 键控的完整饰品目录及其元数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `schema_version` | `string` | 是 | 目录 schema 版本。变化时客户端应重新同步。 |
| `generation_id` | `string` | 是 | 此不可变 schema 代次的稳定标识符。 |
| `generated_at` | `string (date-time)` | 是 | 此不可变 schema 代次的构建时间。比较 `generation_id` 可检测代次变化。 |
| `counts` | `object` | 是 | 目录实体计数。 |
| `rarities` | [SchemaRarity[]](/zh-cn/docs/objects#schemararity) | 是 | 稀有度分层。 |
| `collections` | [`Record<string, SchemaCollection>`](/zh-cn/docs/objects#schemacollection) | 是 | 按收藏品名称键控的收藏品元数据。 |
| `items` | [`Record<string, SchemaItem>`](/zh-cn/docs/objects#schemaitem) | 是 | 按 `market_hash_name` 键控的饰品记录。 |

## 饰品对象

### Item

一个饰品在所有来源上的价格数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称（规范饰品标识符）。 |
| `buff` | [BUFFSourceData](/zh-cn/docs/objects#buffsourcedata) | 是 | 来自 BUFF 的价格数据。 |
| `youpin` | [YoupinSourceData](/zh-cn/docs/objects#youpinsourcedata) | 是 | 来自 Youpin898 的价格数据。 |
| `csfloat` | [CsfloatSourceData](/zh-cn/docs/objects#csfloatsourcedata) | 是 | 来自 CSFloat 的当前挂单与求购单价格。 |
| `skinport` | [SkinportSourceData](/zh-cn/docs/objects#skinportsourcedata) | 是 | 来自 Skinport 的价格数据，包括 Skinport 提供的滚动历史窗口。 |
| `c5game` | [C5GameSourceData](/zh-cn/docs/objects#c5gamesourcedata) | 是 | 来自 C5Game 的价格数据。Ask 和 bid 来自独立采集流程，因此同一饰品的时间戳可能不同。 |
| `steam` | [SteamSourceData](/zh-cn/docs/objects#steamsourcedata) | 是 | 来自 Steam 社区市场的价格数据。 |
| `variants` | [`Record<string, Variant>`](/zh-cn/docs/objects#variant) | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体价格数据。按显示名称作为键。 |

### Variant

饰品的一个变体（Doppler / Gamma Doppler 相位或 Case Hardened 分层）。`youpin` 在每个 Doppler 与 Gamma Doppler 相位上提供 `ask`、`bid` 与 `bid_volume`，大多数饰品还提供 `ask_volume`。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 基础饰品 `market_hash_name`。完整变体名称见：`name`。 |
| `name` | `string` | 是 | 变体的完整 `market_hash_name`，例如 `★ Karambit \| Doppler (Factory New) \| Phase 1`。 |
| `display_name` | `string` | 是 | 人类可读的变体标签（例如 `Phase 1`、`Ruby`、`Tier 1`、`Blue Gem`）。 |
| `version` | `string` | 是 | 允许值: `p1`, `p2`, `p3`, `p4`, `ruby`, `sapphire`, `blackpearl`, `emerald`, `t1`, `t2`, `t3`, `t4`, `singleblue`. 稳定变体代码。客户端代码应基于此切换。 |
| `buff` | [BUFFSourceData](/zh-cn/docs/objects#buffsourcedata) | 否 | 来自 BUFF 的价格数据。 |
| `youpin` | [YoupinSourceData](/zh-cn/docs/objects#youpinsourcedata) | 否 | 来自 Youpin898 的价格数据。 |
| `csfloat` | [CsfloatSourceData](/zh-cn/docs/objects#csfloatsourcedata) | 否 | 来自 CSFloat 的当前挂单与求购单价格。 |
| `skinport` | [SkinportSourceData](/zh-cn/docs/objects#skinportsourcedata) | 否 | 来自 Skinport 的价格数据，包括 Skinport 提供的滚动历史窗口。 |
| `c5game` | [C5GameSourceData](/zh-cn/docs/objects#c5gamesourcedata) | 否 | 来自 C5Game 的价格数据。Ask 和 bid 来自独立采集流程，因此同一饰品的时间戳可能不同。 |
| `steam` | [SteamSourceData](/zh-cn/docs/objects#steamsourcedata) | 否 | 来自 Steam 社区市场的价格数据。 |

### HistoryItem

单个饰品的 OHLC 时间序列。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称（规范饰品标识符）。 |
| `count` | `integer` | 是 | 有数据的分桶数量 |
| `data` | [HistoryBucket[]](/zh-cn/docs/objects#historybucket) | 是 | 按时间顺序排列的 OHLC 分桶。 |
| `variants` | `Record<string, object>` | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 OHLC 时间序列。按显示名称作为键。 |

### ItemLiquidityItem

单个饰品的流动性分档和预计售出时间。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称。 |
| `liquidity` | `string` | 否 | 允许值: `unknown`, `extremely_illiquid`, `very_illiquid`, `illiquid`, `moderate`, `liquid`, `very_liquid`, `extremely_liquid`. 重新计算的饰品流动性分档。 |
| `estimated_sale_time` | `string` | 否 | 允许值: `under 1 hour`, `1 - 2 hours`, `2 - 6 hours`, `6 - 12 hours`, `12 - 24 hours`, `1 - 2 days`, `2 - 3 days`, `3 - 4 days`, `4 - 5 days`, `5 - 7 days`, `7 - 10 days`, `10 - 14 days`, `2 - 3 weeks`, `3 - 4 weeks`, `1 - 1.5 months`, `1.5 - 2 months`, `2+ months`, `unknown`. 竞争性定价挂单售出的第 80 百分位预计等待时间。 |
| `variants` | `Record<string, object>` | 否 | 按显示名称作为键的逐变体饰品流动性。 |

### BUFFMarketFloatItem

单件饰品的 BUFF 市场磨损/渐变数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范化的基础 `market_hash_name`。 |
| `buckets` | [BUFFMarketFloatLatestBucket[]](/zh-cn/docs/objects#buffmarketfloatlatestbucket) | 否 | 基础饰品挂单的最新 BUFF 区间。 |
| `variants` | [`Record<string, BUFFMarketFloatVariant>`](/zh-cn/docs/objects#buffmarketfloatvariant) | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 BUFF 数据。按显示名称作为键（例如 `Phase 1`、`Ruby`、`Tier 1`）。 |

### 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 历史。按显示名称作为键。 |

### BUFFMarketFloatVariant

单个饰品变体（Doppler / Gamma Doppler 相位或 Case Hardened 分层）的 BUFF 最新数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 基础饰品的 `market_hash_name`。完整变体名称见 `name`。 |
| `name` | `string` | 是 | 该变体的完整 `market_hash_name`，例如 `★ M9 Bayonet \| Doppler (Factory New) \| Phase 1`。 |
| `display_name` | `string` | 是 | 人类可读的变体标签（例如 `Phase 1`、`Ruby`、`Tier 1`）。 |
| `version` | `string` | 是 | 稳定的变体代码。客户端代码应基于该字段分支。 |
| `buckets` | [BUFFMarketFloatLatestBucket[]](/zh-cn/docs/objects#buffmarketfloatlatestbucket) | 是 | 该变体的最新 BUFF 区间。 |

### BUFFMarketFloatHistoryVariant

单个饰品变体的 BUFF OHLC 历史。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 基础饰品的 `market_hash_name`。完整变体名称见 `name`。 |
| `name` | `string` | 是 | 该变体的完整 `market_hash_name`，例如 `★ M9 Bayonet \| Doppler (Factory New) \| Phase 1`。 |
| `display_name` | `string` | 是 | 人类可读的变体标签。 |
| `version` | `string` | 是 | 稳定的变体代码。 |
| `buckets` | [BUFFMarketFloatHistoryBucket[]](/zh-cn/docs/objects#buffmarketfloathistorybucket) | 是 | 该变体每个区间的 OHLC 历史。 |

### ArchiveCSFloatItem

单个饰品的 CSFloat 成交时间序列。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称。 |
| `count` | `integer` | 是 | 有数据的天数 |
| `data` | [ArchiveCSFloatBucket[]](/zh-cn/docs/objects#archivecsfloatbucket) | 是 | 按时间顺序排列的每日成交聚合。 |
| `variants` | `Record<string, object>` | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体 CSFloat 成交时间序列。按显示名称作为键。 |

### ArchiveHistoryItem

单个饰品的长期归档时间序列。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称。 |
| `count` | `integer` | 是 | 有数据的分桶数量。 |
| `data` | [ArchiveHistoryBucket[]](/zh-cn/docs/objects#archivehistorybucket) | 是 | 按时间顺序排列的归档分桶。 |
| `variants` | `Record<string, object>` | 否 | 带有 Doppler / Gamma Doppler 相位或 Case Hardened 分层的饰品的逐变体归档时间序列。按显示名称作为键。 |

### ArchiveSteamItem

单个常规饰品的原生 Steam 成交历史分桶。不返回变体。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范化的常规 Steam market hash name。 |
| `count` | `integer` | 是 | `data` 中的分桶数量。 |
| `data` | [ArchiveSteamBucket[]](/zh-cn/docs/objects#archivesteambucket) | 是 | 按 `bucket` 升序排列的分桶。 |

### ArchiveYoupinItem

单个饰品的 Youpin 成交历史，按上游抽样间隔各提供一条独立序列。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | Steam 市场哈希名称。 |
| `intervals` | `object` | 是 | 按上游抽样间隔键控的独立序列，按 `1h`、`4h`、`12h` 顺序输出。只有该间隔在请求窗口内被观测过时键才存在，因此仅为承载所请求变体而存在的条目返回 `{}`。 |
| `variants` | `Record<string, object>` | 否 | 具备 Doppler 或 Gamma Doppler 相位或 Case Hardened 分层的饰品的按变体 Youpin 成交历史。以显示名称为键，为空时省略。变体序列绝不回退到基础饰品历史。 |

### SteamOrderbookItem

单个常规饰品的最新全深度 Steam 订单簿。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time)` | 是 | Steam 最后更新该订单簿的时间。 |
| `collected_at` | `string (date-time)` | 是 | cs2.sh 采集该订单簿的时间。 |
| `top` | [SteamOrderbookTop](/zh-cn/docs/objects#steamorderbooktop) | 是 | Steam 订单簿的最优卖单/买单（盘口顶部）。某一侧缺失时对应字段为 `null`。 |
| `depth` | [SteamOrderbookDepth](/zh-cn/docs/objects#steamorderbookdepth) | 是 | 列式表示的全深度 Steam 订单簿档位。 |

### SteamOrderbookHistoryItem

单个常规饰品的 Steam 订单簿分桶快照。不返回变体。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `count` | `integer` | 是 | `data` 中的数据点数量。 |
| `data` | [SteamOrderbookHistoryPoint[]](/zh-cn/docs/objects#steamorderbookhistorypoint) | 是 | 按 `bucket` 升序排列的数据点。 |

## 历史分桶

### HistoryBucket

单个 OHLC 时间分桶。`bucket` 是间隔边界（UTC 对齐、确定性）；每个按来源对象上的 `open_time`/`close_time` 是其中实际第一次/最后一次观测时间戳。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | 时间分桶的开始时间。UTC 对齐到间隔边界（例如 `1h` 分桶的 `2026-01-08T19:00:00Z`）。确定性。 |
| `buff` | [BUFFOHLCSourceData](/zh-cn/docs/objects#buffohlcsourcedata) | 否 | BUFF 价格的 OHLC 分桶。 |
| `youpin` | [YoupinOHLCSourceData](/zh-cn/docs/objects#youpinohlcsourcedata) | 否 | Youpin 价格的 OHLC 分桶。 |
| `csfloat` | [CsfloatOHLCSourceData](/zh-cn/docs/objects#csfloatohlcsourcedata) | 否 | CSFloat ask 与 bid 价格的 OHLC 分桶。 |
| `skinport` | [SkinportOHLCSourceData](/zh-cn/docs/objects#skinportohlcsourcedata) | 否 | Skinport ask 价格的 OHLC 分桶。 |
| `c5game` | [C5GameOHLCSourceData](/zh-cn/docs/objects#c5gameohlcsourcedata) | 否 | C5Game ask 和 bid 价格的 OHLC 分桶。 |
| `steam` | [SteamOHLCSourceData](/zh-cn/docs/objects#steamohlcsourcedata) | 否 | Steam Community Market ask 和 bid 价格的 OHLC 分桶。 |

### BUFFMarketFloatLatestBucket

一个由 `bucket_type` 标识的最新 BUFF 磨损或渐变范围区间。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket_id` | `string` | 是 | 稳定的区间标识（例如 `base`、`float:0.15:0.18`、`variant:p2\|float:0.00:0.01`）。 |
| `bucket_type` | `string` | 是 | 允许值: `base`, `float`, `fade`, `float_fade`. 区间分层。 - `base`：对整件饰品或变体的聚合。 - `float`：按磨损区间切分（见 `float`）。 - `fade`：按渐变百分比切分（见 `fade`）。 - `float_fade`：磨损与渐变组合切分。 |
| `float` | [BUFFMarketFloatRange](/zh-cn/docs/objects#buffmarketfloatrange) | 否 | `float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。 |
| `fade` | [BUFFMarketFloatRange](/zh-cn/docs/objects#buffmarketfloatrange) | 否 | `float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。 |
| `updated_at` | `string (date-time)` | 否 | BUFF 上次刷新该区间的时间。 |
| `collected_at` | `string (date-time)` | 否 | cs2.sh 拉取该区间的时间。 |
| `ask` | `number` | 否 | 该区间内最低挂单价（USD）。 |
| `avg_ask` | `number` | 否 | 该区间内平均挂单价（USD）。 |
| `bid` | `number` | 否 | BUFF 上的最高求购单价格（USD）。 |
| `ask_volume` | `integer` | 否 | 该区间内在售饰品数量。 |
| `bid_volume` | `integer` | 否 | 针对该区间的活跃求购单数量。 |

### 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`（间隔边界）不同。 |

### BUFFMarketFloatRange

`float` 或 `fade` 区间的数值范围。`min` 含，`max` 不含。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `min` | `number` | 否 | 下界（含）。 |
| `max` | `number` | 否 | 上界（不含）。 |

### ArchiveCSFloatBucket

CSFloat 上一天的成交数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `date` | `string` | 是 | `YYYY-MM-DD` 格式的日期（UTC）。 |
| `price` | `number \| null` | 是 | 当天所有成交价格的算术平均值（USD）。 |
| `volume` | `integer` | 是 | 当天成交次数。 |

### ArchiveHistoryBucket

单个归档时间分桶。只有当该平台在此分桶中存在数据时，对应平台键才会出现。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | 时间分桶的开始时间（UTC 对齐到间隔边界）。 |
| `aggregate` | [ArchiveHistoryPlatformData](/zh-cn/docs/objects#archivehistoryplatformdata) | 否 | 归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。 |
| `buff` | [ArchiveHistoryPlatformData](/zh-cn/docs/objects#archivehistoryplatformdata) | 否 | 归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。 |
| `youpin` | [ArchiveHistoryPlatformData](/zh-cn/docs/objects#archivehistoryplatformdata) | 否 | 归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。 |
| `c5game` | [ArchiveHistoryPlatformData](/zh-cn/docs/objects#archivehistoryplatformdata) | 否 | 归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。 |

### ArchiveHistoryPlatformData

归档分桶内的逐平台价格数据。`hourly_volume` 和 `total_supply` 仅在 `aggregate` 平台上填充。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `time` | `string (date-time)` | 是 | 分桶内最后一次观测的实际时间戳。不同于分桶边界。 |
| `ask` | `number \| null` | 是 | 分桶内最后观测到的 ask 价格（USD）。 |
| `ask_volume` | `integer \| null` | 是 | 最后观测到的在售饰品数量。 |
| `bid` | `number \| null` | 是 | 分桶内最后观测到的 bid 价格（USD）。 |
| `bid_volume` | `integer \| null` | 是 | 最后观测到的求购单数量。 |
| `hourly_volume` | `number \| null` | 否 | 聚合交易量指标（仅 `aggregate` 平台）。 |
| `total_supply` | `number \| null` | 否 | 总市场供应量指标（仅 `aggregate` 平台）。 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的观测数量。 |

### ArchiveSteamBucket

一个原生 Steam 成交历史分桶。`price` 是 Steam 成交中位价，`volume` 是 purchases 数量。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | 原生 Steam 分桶开始时间。 |
| `price` | `number \| null` | 是 | Steam USD 成交中位价。 |
| `volume` | `integer \| null` | 是 | Steam 报告的购买次数。 |

### ArchiveYoupinSeries

单一上游抽样间隔下的一条独立 Youpin 成交序列，只含 `count` 和 `data`。序列之间绝不拼接、求和或交错。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `count` | `integer` | 是 | 该序列中的点数量，等于 `data` 的长度。这不是成交量；`count` 为 0 且 `data` 为空表示该间隔被观测过且窗口内无成交。 |
| `data` | [ArchiveYoupinPoint[]](/zh-cn/docs/objects#archiveyoupinpoint) | 是 | 该间隔下的成交，按分桶排序。 |

### ArchiveYoupinPoint

Youpin 上的一笔成交。Youpin 对每个抽样分桶只保留一笔成交，因此点是一笔真实成交，不是聚合值。抽样间隔由序列的键承载，绝不作为点上的字段。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | 该点所代表的上游抽样分桶的起点，宽度与所在序列一致。 |
| `time` | `string (date-time)` | 是 | 分桶内的实际成交时间。 |
| `price` | `number \| null` | 是 | 成交价（USD），按成交日期各自的历史汇率由 CNY 换算；当该日期的汇率无法解析时为 `null`。 |

### SteamOrderbookTop

Steam 订单簿的最优卖单/买单（盘口顶部）。某一侧缺失时对应字段为 `null`。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `ask` | `number \| null` | 是 | 最优卖单 USD 价格；缺失时为 `null`。 |
| `ask_volume` | `integer \| null` | 是 | Steam 卖单总数量；缺失时为 `null`。 |
| `bid` | `number \| null` | 是 | 最优买单 USD 价格；缺失时为 `null`。 |
| `bid_volume` | `integer \| null` | 是 | Steam 买单总数量；缺失时为 `null`。 |

### SteamOrderbookDepth

列式表示的全深度 Steam 订单簿档位。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `ask_levels` | `integer` | 是 | `asks` 中的卖单档位数量。 |
| `bid_levels` | `integer` | 是 | `bids` 中的买单档位数量。 |
| `asks` | [SteamOrderbookDepthSide](/zh-cn/docs/objects#steamorderbookdepthside) | 是 | 订单簿某一侧的列式深度。`prices[i]` 与 `volumes[i]` 一一对应；每个 `volume` 是该价格上的数量，不是累计数量。 |
| `bids` | [SteamOrderbookDepthSide](/zh-cn/docs/objects#steamorderbookdepthside) | 是 | 订单簿某一侧的列式深度。`prices[i]` 与 `volumes[i]` 一一对应；每个 `volume` 是该价格上的数量，不是累计数量。 |

### SteamOrderbookDepthSide

订单簿某一侧的列式深度。`prices[i]` 与 `volumes[i]` 一一对应；每个 `volume` 是该价格上的数量，不是累计数量。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `prices` | `number[]` | 是 | USD 十进制价格。卖单升序，买单降序。 |
| `volumes` | `integer[]` | 是 | 每个对应价格上的数量。 |

### SteamOrderbookHistoryPoint

一个分桶内最新的全深度 Steam 订单簿快照。这不是 OHLC 数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `bucket` | `string (date-time)` | 是 | UTC 分桶开始时间。 |
| `updated_at` | `string (date-time)` | 是 | Steam 最后更新该分桶所代表订单簿的时间。 |
| `collected_at` | `string (date-time)` | 是 | cs2.sh 采集该分桶所代表订单簿的时间。 |
| `top` | [SteamOrderbookTop](/zh-cn/docs/objects#steamorderbooktop) | 是 | Steam 订单簿的最优卖单/买单（盘口顶部）。某一侧缺失时对应字段为 `null`。 |
| `depth` | [SteamOrderbookDepth](/zh-cn/docs/objects#steamorderbookdepth) | 是 | 列式表示的全深度 Steam 订单簿档位。 |

## 最新价格来源数据

### BUFFSourceData

来自 BUFF 的价格数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | BUFF 上次更新此价格的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `bid` | `number \| null` | 是 | 最高求购单价格（USD） |
| `bid_volume` | `integer \| null` | 是 | 活跃求购单数量 |

### YoupinSourceData

来自 Youpin898 的价格数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | Youpin 上次更新此价格的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `bid` | `number \| null` | 是 | 最高求购单价格（USD） |
| `bid_volume` | `integer \| null` | 是 | 活跃求购单数量 |

### CsfloatSourceData

来自 CSFloat 的当前挂单与求购单价格。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | CSFloat 上次更新此价格的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `bid` | `number \| null` | 是 | 最高求购单价格（USD） |

### SkinportSourceData

来自 Skinport 的价格数据，包括 Skinport 提供的滚动历史窗口。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | Skinport 上次更新此价格的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `max_ask` | `number \| null` | 是 | 最高挂单价（USD） |
| `mean_ask` | `number \| null` | 是 | 平均挂单价（USD） |
| `median_ask` | `number \| null` | 是 | 挂单价中位数（USD） |
| `24h_history` | [SkinportPriceWindow](/zh-cn/docs/objects#skinportpricewindow) \| `null` | 是 | - |
| `7d_history` | [SkinportPriceWindow](/zh-cn/docs/objects#skinportpricewindow) \| `null` | 是 | - |
| `30d_history` | [SkinportPriceWindow](/zh-cn/docs/objects#skinportpricewindow) \| `null` | 是 | - |
| `90d_history` | [SkinportPriceWindow](/zh-cn/docs/objects#skinportpricewindow) \| `null` | 是 | - |

### SteamSourceData

来自 Steam 社区市场的价格数据。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | 上游价格上次更新的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `bid` | `number \| null` | 是 | 最高求购单价格（USD） |
| `bid_volume` | `integer \| null` | 是 | 活跃求购单数量 |

### C5GameSourceData

来自 C5Game 的价格数据。Ask 和 bid 来自独立采集流程，因此同一饰品的时间戳可能不同。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time) \| null` | 是 | C5Game 上次更新此价格的时间 |
| `collected_at` | `string (date-time) \| null` | 是 | cs2.sh 拉取此数据的时间 |
| `ask` | `number \| null` | 是 | 最低 ask 价格（USD） |
| `ask_volume` | `integer \| null` | 是 | 在售饰品数量 |
| `bid` | `number \| null` | 是 | 最高求购单价格（USD） |

### SkinportPriceWindow

Skinport 提供的滚动价格窗口。当 Skinport 最近没有该饰品成交时，对象为 `null`。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `price` | `number` | 是 | 窗口内最近成交价（USD） |
| `max_price` | `number` | 是 | 窗口内最高成交价（USD） |
| `mean_price` | `number` | 是 | 窗口内平均成交价（USD） |
| `median_price` | `number` | 是 | 窗口内成交价中位数（USD） |
| `volume` | `integer` | 是 | 窗口内成交次数 |

## OHLC 来源数据

### BUFFOHLCSourceData

BUFF 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `open_bid` | `number \| null` | 是 | 分桶内第一个 bid 价格 |
| `high_bid` | `number \| null` | 是 | 分桶内最高 bid 价格 |
| `low_bid` | `number \| null` | 是 | 分桶内最低 bid 价格 |
| `close_bid` | `number \| null` | 是 | 分桶内最后一个 bid 价格 |
| `bid_volume` | `integer \| null` | 是 | 分桶内最后观测到的 bid 成交量 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

### YoupinOHLCSourceData

Youpin 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `open_bid` | `number \| null` | 是 | 分桶内第一个 bid 价格 |
| `high_bid` | `number \| null` | 是 | 分桶内最高 bid 价格 |
| `low_bid` | `number \| null` | 是 | 分桶内最低 bid 价格 |
| `close_bid` | `number \| null` | 是 | 分桶内最后一个 bid 价格 |
| `bid_volume` | `integer \| null` | 是 | 分桶内最后观测到的 bid 成交量 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

### CsfloatOHLCSourceData

CSFloat ask 与 bid 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `open_bid` | `number \| null` | 是 | 分桶内第一个 bid 价格 |
| `high_bid` | `number \| null` | 是 | 分桶内最高 bid 价格 |
| `low_bid` | `number \| null` | 是 | 分桶内最低 bid 价格 |
| `close_bid` | `number \| null` | 是 | 分桶内最后一个 bid 价格 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

### SkinportOHLCSourceData

Skinport ask 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

### SteamOHLCSourceData

Steam Community Market ask 和 bid 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `open_bid` | `number \| null` | 是 | 分桶内第一个 bid 价格 |
| `high_bid` | `number \| null` | 是 | 分桶内最高 bid 价格 |
| `low_bid` | `number \| null` | 是 | 分桶内最低 bid 价格 |
| `close_bid` | `number \| null` | 是 | 分桶内最后一个 bid 价格 |
| `bid_volume` | `integer \| null` | 是 | 分桶内最后观测到的 bid 成交量 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

### C5GameOHLCSourceData

C5Game ask 和 bid 价格的 OHLC 分桶。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `open_ask` | `number \| null` | 是 | 分桶内第一个 ask 价格 |
| `high_ask` | `number \| null` | 是 | 分桶内最高 ask 价格 |
| `low_ask` | `number \| null` | 是 | 分桶内最低 ask 价格 |
| `close_ask` | `number \| null` | 是 | 分桶内最后一个 ask 价格 |
| `ask_volume` | `integer \| null` | 是 | 分桶内最后观测到的 ask 成交量 |
| `open_bid` | `number \| null` | 是 | 分桶内第一个 bid 价格 |
| `high_bid` | `number \| null` | 是 | 分桶内最高 bid 价格 |
| `low_bid` | `number \| null` | 是 | 分桶内最低 bid 价格 |
| `close_bid` | `number \| null` | 是 | 分桶内最后一个 bid 价格 |
| `sample_count` | `integer` | 是 | 聚合到此分桶的底层 5 分钟观测数量 |
| `open_time` | `string (date-time) \| null` | 是 | 此分桶内第一次观测的时间戳。不同于 `bucket`（间隔边界）。 |
| `close_time` | `string (date-time) \| null` | 是 | 此分桶内最后一次观测的时间戳。不同于 `bucket`（间隔边界）。 |

## 饰品 Schema

### SchemaItem

一条目录记录，在顶层 `items` 映射中按 `market_hash_name` 键控。不适用于该饰品的字段会被省略。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 规范的 Steam market hash name（与价格端点一致）。 |
| `category` | `string` | 是 | 饰品类别（例如 `skin`、`sticker`、`container`、`agent`）。 |
| `image` | `string` | 是 | `cs2.sh` 自有图片 URL。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确饰品来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。 |
| `is_tradable` | `boolean` | 是 | 该饰品是否可交易。 |
| `rarity` | `object` | 否 | 饰品稀有度：`name`、`tier` 和 `color`。 |
| `collections` | `string[]` | 否 | 饰品所属的收藏品。没有时省略。 |
| `containers` | `string[]` | 否 | 掉落该饰品的容器。没有时省略。 |
| `ids` | `object` | 否 | 已知的市场目录 id。 |
| `def_index` | `integer` | 否 | 饰品定义索引。 |
| `base_name` | `string` | 否 | 不含外观后缀的基础饰品名称。仅限皮肤。 |
| `weapon` | `string` | 否 | 武器名称。仅限皮肤。 |
| `finish` | `string` | 否 | 涂装名称。仅限皮肤。 |
| `paint_index` | `integer` | 否 | 涂装索引。仅限皮肤；Doppler 和 Gamma Doppler 基础饰品会省略。 |
| `wears` | `string[]` | 否 | 该饰品存在的外观。仅限有外观分级的饰品。 |
| `has_stattrak` | `boolean` | 否 | 是否存在 StatTrak 版本。仅限有外观分级的饰品。 |
| `has_souvenir` | `boolean` | 否 | 是否存在 Souvenir 版本。仅限有外观分级的饰品。 |
| `float_range` | `object` | 否 | 该饰品的磨损上下界。仅限有外观分级的饰品。 |
| `wear` | `string` | 否 | 该饰品的外观（例如 `Field-Tested`）。仅限有外观分级的饰品。 |
| `wear_float_range` | `object` | 否 | 该外观行自身的磨损上下界，即 `float_range` 截取到该外观区间后的范围。仅限有外观分级的饰品。 |
| `stattrak` | `boolean` | 否 | 该行是否为 StatTrak 版本。 |
| `souvenir` | `boolean` | 否 | 该行是否为 Souvenir 版本。 |
| `variants` | [SchemaItemVariant[]](/zh-cn/docs/objects#schemaitemvariant) | 否 | 该基础饰品的 Doppler / Gamma Doppler 相位或 Case Hardened 分层。 |
| `variant` | `object` | 否 | 变体行回链到其基础饰品。 |
| `phase` | `string` | 否 | 相位或宝石名称。仅限 Doppler 和 Gamma Doppler 变体行。 |
| `color` | `string` | 否 | 十六进制强调色。仅限 Doppler 和 Gamma Doppler 变体行。 |

### SchemaItemVariant

列在基础饰品 `variants` 下的一个 Doppler / Gamma Doppler 相位或 Case Hardened 分层。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `market_hash_name` | `string` | 是 | 完整的变体 `market_hash_name`。 |
| `family` | `string` | 是 | 允许值: `doppler`, `gamma_doppler`, `case_hardened`. 变体家族。 |
| `name` | `string` | 是 | 变体名称（例如 `Phase 2`、`Ruby`、`Tier 1`）。 |
| `phase` | `string` | 否 | 相位或宝石名称。Case Hardened 会省略。 |
| `color` | `string` | 否 | 十六进制强调色。Case Hardened 会省略。 |
| `paint_index` | `integer` | 否 | 该变体的涂装索引。 |
| `image` | `string` | 是 | `cs2.sh` 自有图片 URL。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确变体来源已得到独立证明时提供。缺少该字段不会移除必需的自有 `image`。 |

### SchemaCollection

收藏品元数据。在顶层 `collections` 映射中按收藏品名称键控。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | 收藏品名称。 |
| `kind` | `string` | 是 | 收藏品类型（例如 `weapon`、`sticker`）。 |
| `release_date` | `string` | 否 | 发布日期（`YYYY-MM-DD`），已知时提供。饰品的发布日期即其收藏品的发布日期；饰品带有 `collections`，请据此关联，而不要指望每件饰品自带日期。 |
| `released_at` | `string` | 否 | 发布该收藏品的 Valve 公告的确切发布时刻（RFC 3339 UTC）。仅在该公告已知时提供。 |
| `update_name` | `string` | 否 | Valve 对该次更新的自有名称，例如 `Season 5, Armory, and More`。 |
| `announcement_url` | `string` | 否 | 该次更新的规范 Steam 公告地址。 |
| `image` | `string` | 否 | 由 `cs2.sh` 提供的自有图片 URL，可用时提供。 |
| `steam_image` | `string` | 否 | 可选的 Valve Economy/static 官方图片 URL；仅在精确来源已得到独立证明时提供。 |

### SchemaRarity

一个稀有度分层。列在顶层 `rarities` 数组中，并由饰品层的 `rarity` 引用。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `key` | `string` | 是 | 稳定的稀有度键（例如 `ancient`、`legendary`）。 |
| `name` | `string` | 是 | 显示名称（例如 `Covert`、`Classified`）。 |
| `tier` | `integer` | 是 | 数值稀有度分层，随稀有度递增。 |
| `color` | `string` | 是 | 该稀有度的十六进制颜色。 |

## 健康状态

### HealthResponse

cs2.sh 数据来源和公共数据集的当前健康状态。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `status` | `string` | 是 | 允许值: `up`, `degraded`, `down`. API 数据的整体健康状态。 |
| `last_refreshed_at` | `string (date-time)` | 是 | 此健康快照的生成时间。 |
| `schema_ready` | `boolean` | 是 | 饰品 schema 是否可用。 |
| `sources` | [`Record<string, HealthEntry>`](/zh-cn/docs/objects#healthentry) | 是 | 按来源键控的市场健康状态。 |
| `variants` | [`Record<string, HealthEntry>`](/zh-cn/docs/objects#healthentry) | 是 | 按来源采集器键控的变体价格健康状态。 |
| `endpoints` | [`Record<string, HealthEntry>`](/zh-cn/docs/objects#healthentry) | 是 | 按端点名称键控的数据集健康状态。 |
| `stats` | [HealthStats](/zh-cn/docs/objects#healthstats) | 是 | 上次健康状态刷新时的数据库汇总计数。 |

### HealthEntry

单个来源、变体采集器或端点数据集的新鲜度和状态。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `updated_at` | `string (date-time)` | 是 | 此条目所代表数据的最新来源时间。 |
| `collected_at` | `string (date-time)` | 是 | cs2.sh 最近采集或生成此数据集的时间。 |
| `status` | `string` | 是 | 允许值: `up`, `degraded`, `down`. 根据数据集预期刷新频率计算的健康状态。 |

### HealthStats

上次健康状态刷新时的数据库汇总计数。

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `total_events` | `integer` | 是 | 已存储的市场数据事件总数。 |
| `market_hash_names` | `integer` | 是 | 当前市场数据中唯一饰品名称的数量。 |
| `variant_items` | `integer` | 是 | 当前市场数据中唯一变体饰品名称的数量。 |

## 错误

### ItemError

部分成功响应中特定饰品的错误

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `item` | `string` | 是 | 失败的请求饰品名称 |
| `code` | `string` | 是 | 允许值: `unknown_item`, `not_in_cache`, `invalid_format`, `not_in_archive`, `unsupported_variant`, `unsupported_source`. 错误代码 |
| `message` | `string` | 是 | 人类可读错误消息 |

### ErrorResponse

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `error` | `string` | 是 | 错误代码（例如 validation_error、unauthorized、rate_limited） |
| `message` | `string` | 是 | 人类可读错误消息 |
| `request_id` | `string (uuid)` | 否 | 用于支持的唯一请求标识符 |
| `details` | `object` | 否 | 额外错误详情（结构因错误类型而异） |