> ## Documentation Index
> Fetch the complete documentation index at: https://api.csboard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /v1/orders — 使用余额购买 CS2 挂单
> 在单次原子请求中按 ID 购买 1–10 件 CS2 挂单，从您的 CSBoard 余额中扣款。需要启用交易的 API 密钥以及已绑定的 Steam 账户。
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 余额必须能够覆盖所有商品按实时价格的总成本。
## 请求头
可选。用于标识本次下单尝试的唯一字符串（例如 UUID）。如果您使用相同的键重试请求，服务器将重放原始订单响应，而不会执行第二次购买。借此可在网络超时时安全重试而无重复扣款风险。
## 请求体
1–10 个唯一的挂单 ID 数组。请从 `GET /v1/listings` 响应的 `id` 字段获取。每个 ID 在一次请求中只能出现一次。
美元总价上限，将在执行时原子地强制执行。如果所有商品的实时总额超过该值，整个订单将以 `price_moved` 错误被拒绝，且不会扣款。**强烈建议使用**——若无此值，您将无任何超额扣款保护。
`Idempotency-Key` 请求头的替代方案。如果两者都提供，则以请求头为准。请二选一使用，不要同时使用。
## 响应字段
本次订单的唯一标识符，例如 `ord_01J9Z3K8Q2`。
当前订单状态：`processing`、`completed` 或 `failed`。
订单的逐件商品明细。
被购买的挂单 ID。
按实时价格对该具体商品扣除的金额。
该商品的交付模式：`instant`（即时转移）或 `hold`（受 Steam 交易冻结约束）。
所有逐件扣款的合计。这是从您余额中划扣的总金额。
扣款后您的 CSBoard 余额。
订单创建时的 ISO 8601 时间戳。
## 示例请求
```bash theme={null}
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
}'
```
## 示例响应
```json theme={null}
{
"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 状态码 | 代码 | 含义 |
| -------- | ------------------------ | ---------------------------------------------------------------------- |
| 409 | `price_moved` | 商品的实时总额超过了 `max_price_usd`。订单被拒绝；未扣款。响应中包含 `current_total_usd`，显示实际价格。 |
| 402 | `insufficient_balance` | 余额过低，无法覆盖订单总额。 |
| 400 | `steam_account_required` | 您的 CSBoard 账户上未绑定 Steam 账户或没有有效的交易链接。 |
| 403 | `trading_not_enabled` | 该 API 密钥未启用购买功能。请在您的个人资料中启用。 |
| 401 | `unauthorized` | API 密钥缺失或无效。 |
| 429 | `rate_limit_exceeded` | 超过 30 次/分钟。请在重试前等待 `Retry-After` 响应头中的秒数。 |
请始终在请求中包含 `max_price_usd`。实时市场上的价格可能在您查询 `/v1/listings` 到订单执行之间发生变化。若没有此上限，您的余额可能以高于预期的价格被扣除，且没有自动回滚机制。
通过 `hold` 交付的商品受 Steam 交易冻结约束。请查看原始挂单（来自 `GET /v1/listings`）上的 `tradable_at` 字段，了解被冻结的商品何时能在您的 Steam 库存中可交易。
## OpenAPI
````yaml POST /orders
openapi: 3.1.0
info:
title: CSBoard API
version: 1.0.0
description: >-
Market data over the CSBoard marketplace — live listings, floats, stickers,
minAsk prices, FX rates — plus opt-in buying straight from your balance.
Free to read, key-gated, built for automation.
contact:
name: CSBoard
url: https://csboard.com/docs
servers:
- url: https://csboard.com/v1
description: Production
security:
- bearerAuth: []
tags:
- name: Status
description: Liveness and freshness probes.
- name: Market data
description: Read the live catalog, prices, and FX rates.
- name: Trading
description: Buy listings from your CSBoard balance. Opt-in, key-gated.
- name: Account
description: Your balance, settled funds, and trading status.
paths:
/orders:
post:
tags:
- Trading
summary: Buy listings from your balance
description: >-
Buy 1–10 listings by id, debited from your CSBoard balance. Requires
trading enabled on the key + a linked Steam account and trade URL. Buys
are charged at the LIVE price at execution; always send `max_price_usd`
as an atomic overcharge ceiling. Idempotent via the `Idempotency-Key`
header or `idempotency_key` in the body.
operationId: createOrder
parameters:
- name: Idempotency-Key
in: header
description: >-
Optional. A retried request with the same key replays the original
order instead of buying twice.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderRequest'
example:
item_ids:
- itm_8841201
- itm_8841340
max_price_usd: 30
idempotency_key: 6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f
responses:
'200':
description: Order accepted and debited.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreated'
example:
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'
'400':
description: Invalid request (e.g. price moved past your ceiling).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
price_moved:
summary: Live price exceeded max_price_usd
value:
code: price_moved
message: Live total 31.20 exceeds max_price_usd 30.00.
current_total_usd: 31.2
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: Insufficient balance.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: insufficient_balance
message: Balance 10.00 is below order total 26.47.
'403':
description: Trading not enabled on this key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: trading_not_enabled
message: Enable buying for this key in your profile.
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
OrderRequest:
type: object
properties:
item_ids:
type: array
items:
type: string
minItems: 1
maxItems: 10
uniqueItems: true
description: >-
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.
max_price_usd:
type: number
description: >-
Total ceiling in USD. Strongly recommended — your overcharge
protection, enforced atomically inside the locked debit.
idempotency_key:
type: string
description: >-
Optional; or send the Idempotency-Key header. Replays the original
order on retry.
required:
- item_ids
OrderCreated:
type: object
properties:
order_id:
type: string
status:
type: string
enum:
- processing
- completed
- failed
items:
type: array
items:
type: object
properties:
item_id:
type: string
charged_usd:
type: number
delivery:
type: string
enum:
- instant
- hold
total_charged_usd:
type: number
balance_after_usd:
type: number
created_at:
type: string
format: date-time
required:
- order_id
- status
- total_charged_usd
Error:
type: object
description: >-
All errors return { code, detail }. Some carry extra fields (e.g.
price_moved adds current_total_usd, insufficient_balance adds
required_usd/current_usd).
properties:
code:
type: string
description: >-
Machine-readable error code, e.g. rate_limit_exceeded,
trading_not_enabled, price_moved.
detail:
type: string
description: Human-readable explanation.
required:
- code
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: unauthorized
message: Missing or invalid API key.
RateLimited:
description: Rate limit exceeded. Includes a Retry-After header.
headers:
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
code: rate_limit_exceeded
message: Too many requests.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Send your key as a Bearer token on every request: `Authorization: Bearer
csb_pub_...`. Generate keys in your CSBoard profile.
````