跳转到主要内容
POST
/
orders
Buy listings from your balance
curl --request POST \
  --url https://csboard.com/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "item_ids": [
    "itm_8841201",
    "itm_8841340"
  ],
  "max_price_usd": 30,
  "idempotency_key": "6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
'
{
  "order_id": "ord_01J9Z3K8Q2",
  "status": "processing",
  "items": [
    {
      "item_id": "itm_8841201",
      "charged_usd": 14.37,
      "delivery": "hold"
    },
    {
      "item_id": "itm_8841340",
      "charged_usd": 12.1,
      "delivery": "instant"
    }
  ],
  "total_charged_usd": 26.47,
  "balance_after_usd": 73.53,
  "created_at": "2026-06-29T17:12:04Z"
}
orders 端点允许您在单次原子请求中购买 1 到 10 件挂单。扣款将以执行当时的实时报价从您的 CSBoard 余额中划扣——而非您查询 /v1/listings 时看到的价格。为防止查询与下单之间的价格波动，请始终包含 max_price_usd 作为总价上限。该端点是幂等的：使用相同的 Idempotency-Key 重试会重放原始订单，而非产生重复扣款。 需要身份验证。 请将密钥作为 Authorization: Bearer csb_pub_... 发送。 需要交易能力。 API 密钥必须启用购买功能。请在您的 CSBoard 个人资料中进行配置。

​
前置条件

下单前，请确保：
  1. 启用交易的密钥——必须在您的 CSBoard 个人资料设置中为该 API 密钥开启购买功能。
  2. 已绑定的 Steam 账户与交易链接——您的 CSBoard 账户必须已绑定 Steam 账户并配置有效的交易链接，以便商品可以交付。
  3. 充足的余额——您的 CSBoard 余额必须能够覆盖所有商品按实时价格的总成本。

​
请求头

​
Idempotency-Key
string
可选。用于标识本次下单尝试的唯一字符串（例如 UUID）。如果您使用相同的键重试请求，服务器将重放原始订单响应，而不会执行第二次购买。借此可在网络超时时安全重试而无重复扣款风险。

​
请求体

​
item_ids
string[]
必填
1–10 个唯一的挂单 ID 数组。请从 GET /v1/listings 响应的 id 字段获取。每个 ID 在一次请求中只能出现一次。
​
max_price_usd
number
美元总价上限，将在执行时原子地强制执行。如果所有商品的实时总额超过该值，整个订单将以 price_moved 错误被拒绝，且不会扣款。强烈建议使用——若无此值，您将无任何超额扣款保护。
​
idempotency_key
string
Idempotency-Key 请求头的替代方案。如果两者都提供，则以请求头为准。请二选一使用，不要同时使用。

​
响应字段

​
order_id
string
必填
本次订单的唯一标识符，例如 ord_01J9Z3K8Q2。
​
status
string
必填
当前订单状态：processing、completed 或 failed。
​
items
object[]
订单的逐件商品明细。
​
total_charged_usd
number
必填
所有逐件扣款的合计。这是从您余额中划扣的总金额。
​
balance_after_usd
number
扣款后您的 CSBoard 余额。
​
created_at
datetime
订单创建时的 ISO 8601 时间戳。

​
示例请求

curl -X POST https://csboard.com/v1/orders \
  -H "Authorization: Bearer csb_pub_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f" \
  -d '{
    "item_ids": ["itm_8841201", "itm_8841340"],
    "max_price_usd": 30.00
  }'

​
示例响应

{
  "order_id": "ord_01J9Z3K8Q2",
  "status": "processing",
  "items": [
    {
      "item_id": "itm_8841201",
      "charged_usd": 14.37,
      "delivery": "hold"
    },
    {
      "item_id": "itm_8841340",
      "charged_usd": 12.10,
      "delivery": "instant"
    }
  ],
  "total_charged_usd": 26.47,
  "balance_after_usd": 73.53,
  "created_at": "2026-06-29T17:12:04Z"
}

​
错误代码

HTTP 状态码代码含义
409price_moved商品的实时总额超过了 max_price_usd。订单被拒绝；未扣款。响应中包含 current_total_usd，显示实际价格。
402insufficient_balance余额过低，无法覆盖订单总额。
400steam_account_required您的 CSBoard 账户上未绑定 Steam 账户或没有有效的交易链接。
403trading_not_enabled该 API 密钥未启用购买功能。请在您的个人资料中启用。
401unauthorizedAPI 密钥缺失或无效。
429rate_limit_exceeded超过 30 次/分钟。请在重试前等待 Retry-After 响应头中的秒数。
请始终在请求中包含 max_price_usd。实时市场上的价格可能在您查询 /v1/listings 到订单执行之间发生变化。若没有此上限，您的余额可能以高于预期的价格被扣除，且没有自动回滚机制。
通过 hold 交付的商品受 Steam 交易冻结约束。请查看原始挂单（来自 GET /v1/listings）上的 tradable_at 字段，了解被冻结的商品何时能在您的 Steam 库存中可交易。

授权

​
Authorization
string
header
必填

Send your key as a Bearer token on every request: Authorization: Bearer csb_pub_.... Generate keys in your CSBoard profile.

请求头

​
Idempotency-Key
string

Optional. A retried request with the same key replays the original order instead of buying twice.

请求体

application/json
​
item_ids
string[]
必填

1–10 unique ids from /v1/listings. Some items can't be combined in a single order — if so the order is rejected and you can split it.

Required array length: 1 - 10 elements
​
max_price_usd
number

Total ceiling in USD. Strongly recommended — your overcharge protection, enforced atomically inside the locked debit.

​
idempotency_key
string

Optional; or send the Idempotency-Key header. Replays the original order on retry.

响应

Order accepted and debited.

​
order_id
string
必填
​
status
enum<string>
必填
可用选项:
processing,
completed,
failed
​
total_charged_usd
number
必填
​
items
object[]
​
balance_after_usd
number
​
created_at
string<date-time>