# POST /v1/archive/youpin

Youpin 成交价格样本，提供独立的 1h、4h 和 12h 序列。

返回三个独立时间间隔的 Youpin 成交价格历史。

- `12h` 频率自 2025 年 11 月 12 日起
- `4h` 频率自 2026 年 6 月 27 日起
- `1h` 频率自 2026 年 7 月 20 日起

Youpin 每个采样分桶只提供一笔成交，也不提供成交量。因此，1h 序列每天最多有 24 个点，4h 序列最多 6 个，12h 序列最多 2 个。

同一笔成交可以出现在多条序列中：

```text
12:42 的成交
  -> 1h 序列:  12:00 分桶
  -> 4h 序列:  12:00 分桶
  -> 12h 序列: 12:00 分桶
```

由于同一笔成交可能出现在多条序列中，建议将 `1h`、`4h` 和 `12h` 视为数据的不同视图。

目前采集约 16,000 件流动性较高的饰品，以及已映射的 Doppler、Gamma Doppler 和 Case Hardened 变体。数据每天约更新 1-2 次。每次请求最多 100 个饰品。

## 访问

需要 Scale 或 Enterprise API 密钥。

## 支持的间隔

| 间隔 | 采样分桶 |
| --- | --- |
| `1h` | 每小时一笔成交 |
| `4h` | 每 4 小时一笔成交 |
| `12h` | 每 12 小时一笔成交 |

所有被观测到的间隔都在每件饰品的 `intervals` 映射下一并返回，各自是一条独立序列。

## 请求

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

**curl**

```bash
curl -X POST https://api.cs2.sh/v1/archive/youpin \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Accept-Encoding: gzip" --compressed \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    "★ Karambit | Doppler (Factory New)"
  ],
  "start": "2026-01-29",
  "end": "2026-07-28"
}'
```

**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-01-29",
    "end": "2026-07-28",
}

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

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-01-29",
        "end": "2026-07-28",
    }
    body, _ := json.Marshal(payload)
    req, _ := http.NewRequest("POST", "https://api.cs2.sh/v1/archive/youpin", 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-01-29",
  end = "2026-07-28"
)

resp <- request("https://api.cs2.sh/v1/archive/youpin") |>
  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）。默认 180 天前。向下取整到整点。 |
| `end` | `string` | 否 | 结束日期（YYYY-MM-DD 或 RFC3339）。默认现在。向上取整到整点。 |

## 响应

```json
{
  "response_time": "2026-07-28T16:20:41.318204951Z",
  "currency": "USD",
  "start": "2026-01-29T00:00:00Z",
  "end": "2026-07-28T00:00:00Z",
  "items": {
    "★ Karambit | Doppler (Factory New)": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "intervals": {
        "1h": {
          "count": 120,
          "data": [
            {
              "bucket": "2026-07-21T16:00:00Z",
              "time": "2026-07-21T16:52:38.307Z",
              "price": 1314.88
            },
            {
              "bucket": "2026-07-21T23:00:00Z",
              "time": "2026-07-21T23:42:05.008Z",
              "price": 1920.6
            }
          ]
        },
        "4h": {
          "count": 180,
          "data": [
            {
              "bucket": "2026-06-27T16:00:00Z",
              "time": "2026-06-27T18:37:02.696Z",
              "price": 1971.09
            },
            {
              "bucket": "2026-06-27T20:00:00Z",
              "time": "2026-06-27T23:59:41.06Z",
              "price": 1995.59
            }
          ]
        },
        "12h": {
          "count": 353,
          "data": [
            {
              "bucket": "2026-01-29T16:00:00Z",
              "time": "2026-01-30T03:34:33.138Z",
              "price": 2256.76
            },
            {
              "bucket": "2026-01-30T16:00:00Z",
              "time": "2026-01-31T03:51:57.426Z",
              "price": 1438.64
            }
          ]
        }
      },
      "variants": {
        "Phase 2": {
          "market_hash_name": "★ Karambit | Doppler (Factory New)",
          "name": "★ Karambit | Doppler (Factory New) | Phase 2",
          "display_name": "Phase 2",
          "version": "p2",
          "intervals": {
            "12h": {
              "count": 356,
              "data": [
                {
                  "bucket": "2026-01-29T04:00:00Z",
                  "time": "2026-01-29T15:46:01.526Z",
                  "price": 2296.22
                }
              ]
            }
          }
        }
      }
    }
  }
}
```

## 响应字段

[ArchiveYoupinResponse](/zh-cn/docs/objects#archiveyoupinresponse) 字段:

| 字段 | 类型 | 必需 | 描述 |
| --- | --- | --- | --- |
| `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) | 否 | 与成功结果并存的按饰品失败（部分成功）。 |

## 序列

| 字段 | 描述 |
| --- | --- |
| `items.<name>.intervals` | 以 `1h`、`4h`、`12h` 为键的映射；每个键是一条独立序列。 |
| `intervals.<width>.count` | 该时间窗内的成交点数量。 |
| `intervals.<width>.data[]` | 采样的成交点。 |
| `data[].bucket` | 采样分桶边界。 |
| `data[].time` | 实际成交时间。 |
| `data[].price` | 成交价，USD，按成交日期的汇率转换。 |
| `items.<name>.variants` | 每个变体的相同结构。 |

- 只有当该宽度在时间窗内被观测过时，对应的间隔键才会出现；`count: 0` 表示已观测但没有成交。
- `count` 是该条序列中的数据点数量，不是成交量。
- 请求的有效饰品若没有 Youpin 成交历史则返回 `not_in_archive`。

完整结构：[ArchiveYoupinItem](/zh-cn/docs/objects#archiveyoupinitem)、[ArchiveYoupinSeries](/zh-cn/docs/objects#archiveyoupinseries)、[ArchiveYoupinPoint](/zh-cn/docs/objects#archiveyoupinpoint)。

### ArchiveYoupinItem

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

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

### 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`。 |

## 错误

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