使用 API

本页介绍 cs2.sh API 各端点共享的约定，包括认证、请求类型、响应对象、变体、时间戳、缺失数据、部分成功、错误和限制。

• 想在指引下发起第一个请求，请从快速开始开始。
• 关于市场字段、刷新频率和历史覆盖范围，见数据覆盖范围。
• 各端点页面记录了各自精确的参数和响应字段。

认证#

公开 API 基础 URL 为 https://api.cs2.sh。

所有 /v1 端点都需要 Bearer API 密钥。每个 /v1 请求还必须接受 gzip 压缩，POST 请求还应包含 Content-Type: application/json：

成功的 /v1 响应是 gzip 编码的。大多数 HTTP 客户端会自动解压。错误响应以纯 JSON 返回。

在仪表盘中轮换 API 密钥会生成一个新密钥，并立即使旧密钥失效。

GET 与 POST 请求#

cs2.sh 使用两种主要的请求模式：

• GET 快照：获取某个端点完整的当前数据集。
• POST 查询：请求最多 100 件指定饰品的数据，并附带日期、来源或间隔等端点特定参数。

例如，下面的请求获取完整的当前价格快照：

GET /v1/prices/latest

下面的请求获取两件指定饰品的当前价格：

POST /v1/prices/latest
Content-Type: application/json

{
  "items": [
    "USP-S | Printstream (Factory New)",
    "AK-47 | Redline (Field-Tested)"
  ]
}

GET 快照可能很大，但很有用，因为你可以保存一次响应，之后在本地进行查询。当你需要针对一组已知饰品获得有界响应时，POST 请求更合适。历史端点也使用 POST 请求来限制响应大小。

饰品#

POST 端点使用 market_hash_name 标识饰品：

{
  "items": [
    "USP-S | Printstream (Factory New)"
  ]
}

GET /v1/schema 按所有端点所接受的同一 market_hash_name 返回每一件受支持的饰品。它还包含饰品元数据、市场 id、图片、外观、磨损区间和变体。

POST 端点在一次请求中最多接受 100 件饰品。

响应#

大多数饰品端点返回一个以 market_hash_name 为键的 items 对象。

{
  "response_time": "2026-07-26T18:54:04.041Z",
  "currency": "USD",
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)",
      "buff": {
        "updated_at": "2026-07-26T18:50:53Z",
        "collected_at": "2026-07-26T18:53:10.67Z",
        "ask": 109.72,
        "ask_volume": 463,
        "bid": 106.17,
        "bid_volume": 41
      }
    }
  }
}

常见的顶层字段包括：

当前价格饰品对每个市场包含一个对象。历史端点使用相同的 items 映射，时间序列数据嵌套在每件饰品之内。

完整的响应 schema 见 API 对象。

变体#

带有受支持的 Doppler、Gamma Doppler 或 Case Hardened 变体的饰品可以包含 variants 对象。

{
  "market_hash_name": "★ Karambit | Doppler (Factory New)",
  "buff": {
    "ask": 1336.26,
    "bid": 1281.77
  },
  "variants": {
    "Ruby": {
      "market_hash_name": "★ Karambit | Doppler (Factory New)",
      "name": "★ Karambit | Doppler (Factory New) | Ruby",
      "display_name": "Ruby",
      "version": "ruby",
      "buff": {
        "ask": 7671.41,
        "bid": 7287.47
      },
      "csfloat": {
        "ask": 7590,
        "bid": 7220
      }
    }
  }
}

在变体对象上：

版本代码#

变体饰品支持的 version 代码：

变体的可用性取决于市场和端点。变体支持情况见数据覆盖范围，每件饰品所附带的变体见 GET /v1/schema。

时间戳#

当前市场价格对象可以包含三个不同的时间戳：

response_time 并不表示某个市场价格的采集时间。检查新鲜度时，请使用该市场对象内部的时间戳。

刷新频率是近似值，并因市场而异。各端点和来源的预期刷新频率见数据覆盖范围。

历史响应分桶#

prices/history 和 market/buff/history 返回固定的、UTC 对齐的 OHLC 分桶。分桶内的每个市场对象都包含以下观测字段：

ask_volume 和 bid_volume 是分桶内最后观测到的值。

并非每个历史端点都返回 OHLC。market/steam/history 返回采样的 Steam 订单簿历史，归档端点则返回各自端点页面所记录的数据。关于 OHLC、采样和归档历史之间的区别，见数据覆盖范围。

缺失数据#

缺失的价格不等于价格为零。

在当前价格的基础饰品上，市场对象可能存在，但不可用字段被设为 null：

{
  "skinport": {
    "updated_at": null,
    "collected_at": null,
    "ask": null,
    "ask_volume": null
  }
}

变体和历史响应对象可能是稀疏的。当某个市场对该变体或区间没有数据时，该市场对象可能不存在。

某些历史端点在所请求范围内不存在数据时，会省略有效的饰品。相关端点页面记录了其精确的空数据行为。

部分成功#

POST 端点会独立校验请求的饰品。一次请求可以在同一个 200 响应中返回成功的饰品和逐饰品错误。

{
  "items": {
    "USP-S | Printstream (Factory New)": {
      "market_hash_name": "USP-S | Printstream (Factory New)"
    }
  },
  "errors": [
    {
      "item": "Invalid Item Name",
      "code": "unknown_item",
      "message": "item not found"
    }
  ]
}

errors 中的条目仅适用于所请求的那件饰品。它不会使成功返回的饰品失效。

饰品错误码#

相关端点页面记录了它可能返回哪些饰品错误码。完整对象见 ItemError。

饰品错误与请求级错误不同。

请求错误#

请求级错误使用共享的 JSON 对象：

{
  "error": "validation_error",
  "message": "items must contain at most 100 entries",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

部分错误还包含 details 对象。

request_id 标识失败的请求，联系支持时应一并提供。

请先修正 400、401、403、404 和 405 错误再重试。对 429 和临时性的 5xx 错误，请以有界延迟重试。

各端点页面记录了该端点特有的其他错误行为。

限制#

历史端点还有按间隔划分的最大请求范围。这些记录在数据覆盖范围和相关端点页面中。

完整的 GET 快照可能很大。当你需要反复访问同一个当前数据集时，请缓存它们，并对更小的、针对指定饰品的请求使用 POST 端点。

OpenAPI#

完整的 OpenAPI 3.1 规范可在 cs2.sh/openapi.zh-CN.yaml 获取。

它包含端点参考所使用的请求参数、响应 schema、枚举和示例。