Skip to main content
POST
Buy listings from your balance
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 余额必须能够覆盖所有商品按实时价格的总成本。

请求头

string
可选,8–128 个字符(例如 UUID),用于标识本次下单尝试。如果您使用相同的键重试请求,服务器将返回 200、附带 Idempotent-Replayed: true 响应头以及原始订单响应,而不会执行第二次购买。若第一次请求仍在处理中,重试将返回 409 idempotency_in_progress。借此可在网络超时时安全重试而无重复扣款风险。

请求体

string[]
必填
1–10 个唯一的挂单 ID 数组。请从 GET /v1/listings 响应的 id 字段获取。每个 ID 在一次请求中只能出现一次。
number
美元总价上限,将在执行时原子地强制执行。如果所有商品的实时总额超过该值,整个订单将以 price_moved 错误被拒绝,且不会扣款。强烈建议使用——若无此值,您将无任何超额扣款保护。
string
Idempotency-Key 请求头的替代方案。如果两者都提供,则以请求头为准。请二选一使用,不要同时使用。
integer
默认值:"730"
item_ids 所属的游戏:730 = CS2,570 = Dota 2,252490 = Rust。不传则为 CS2。请使用您从 GET /v1/listings 读取这些 id 时所用的同一个 appId。查看 GET /v1/games 中的 tradable,了解您的密钥可以在哪些游戏中购买。

响应字段

新订单返回 201 Created。幂等重放返回 200,响应体相同。
string
必填
本次订单的唯一标识符。将其传给 GET /v1/orders/{id} 以跟踪交付。
string
必填
生成响应时订单的内部状态,例如 paid 或 pending_delivery。这不是 GET /v1/orders 中规范化的 status 取值——请在那里或通过 Webhooks 跟踪订单。
string
必填
始终为 USD。
number
必填
从您余额中扣除的总额,单位美元。
integer
订单中的商品数量。
object[]
每件购买的商品一条记录。
string | null
必填
已知时的交付方式:instant(机器人交付)或 pending(仍需卖家或供应商发起交易)。Dota 2 和 Rust 订单始终返回 pending。
integer | null
必填
可给出时的大致交付时间(分钟)。Dota 2 和 Rust 订单始终为 null。
datetime
订单创建时的 ISO 8601 时间戳。
datetime | null
订单最后一次变更的 ISO 8601 时间戳。

示例请求

示例响应

错误代码

请始终在请求中包含 max_price_usd。实时市场上的价格可能在您查询 /v1/listings 到订单执行之间发生变化。若没有此上限,您的余额可能以高于预期的价格被扣除,且没有自动回滚机制。
通过 hold 交付的商品受 Steam 交易冻结约束。请查看原始挂单(来自 GET /v1/listings)上的 tradable_at 字段,了解被冻结的商品何时能在您的 Steam 库存中可交易。
Dota 2 和 Rust。 appId 为 570 或 252490 的订单会进入交付队列,并返回 delivery: "pending" 和 expected_minutes: null。请通过 GET /v1/orders/{id} 跟踪。价格上限、余额检查和幂等性与 CS2 完全相同。

授权

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, 8–128 characters. A retried request with the same key replays the original order (200 with Idempotent-Replayed: true) instead of buying twice; while the first request is still running it answers 409 idempotency_in_progress.

请求体

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.

必填范围: x <= 1000000
idempotency_key
string

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

Required string length: 8 - 128
autoclaim
boolean

Sticky per-account setting (not per-order). Send true once to switch your key into auto-claim mode: every held order is then auto-released the moment its hold clears (your bot must auto-accept the Steam trade offer within ~15 minutes). Send false to switch back to manual claiming via POST /orders/{id}/claim. Omit to leave the setting unchanged.

appId
enum<integer>
默认值:730

Game the item_ids belong to: 730 = CS2 (the default), 570 = Dota 2, 252490 = Rust. Send the same appId you read the ids with from GET /listings. A game this key may not buy in answers 400 unsupported_game — tradable in GET /games tells you in advance.

可用选项:
730,
570,
252490

响应

Idempotent replay: a request with an Idempotency-Key (or idempotency_key) already used for a completed order returns that original response body, with the header Idempotent-Replayed: true. Nothing new is bought.

The order as it stands the moment it was created. status here is the internal state at that instant (for example paid or pending_delivery), not the normalised vocabulary of GET /orders — read the order there, or subscribe to webhooks, to follow it.

order_id
string
必填

Order id. Use it with GET /orders/{id}.

status
string
必填

Internal order state when the response was built, e.g. paid or pending_delivery. Poll GET /orders/{id} for the public status.

currency
enum<string>
必填
可用选项:
USD
charged_total_usd
number
必填

Total debited from your balance, in USD.

delivery
enum<string> | null
必填

How the order is being delivered, when known: instant (bot delivery) or pending (a seller or supplier still has to send the trade). Dota 2 and Rust orders always answer pending.

可用选项:
instant,
pending,
null
expected_minutes
integer | null
必填

Rough delivery estimate in minutes, when we can state one. Always null for Dota 2 and Rust orders.

item_count
integer

Number of items in the order.

items
object[]

One entry per item bought.

created_at
string<date-time>
updated_at
string<date-time> | null