> ## 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 — Buy CS2 Listings from Your Balance
> Buy 1–10 CS2 listings by ID in a single atomic request, debited from your CSBoard balance. Requires a trading-enabled API key and linked Steam account.
The orders endpoint lets you buy between 1 and 10 listings in a single atomic request. The charge is debited from your CSBoard balance at the **live** asking price at the moment of execution — not at the price you saw when you queried `/v1/listings`. To protect yourself from price movements between lookup and purchase, always include `max_price_usd` as a total ceiling. The endpoint is idempotent: retrying with the same `Idempotency-Key` replays the original order rather than creating a duplicate charge.
**Authentication required.** Send your key as `Authorization: Bearer csb_pub_...`.
**Trading capability required.** The API key must have buying enabled. Configure this in your CSBoard profile.
## Prerequisites
Before placing an order, ensure:
1. **Trading-enabled key** — buying must be turned on for your API key in your CSBoard profile settings.
2. **Linked Steam account and trade URL** — your CSBoard account must have a Steam account connected with a valid trade URL so items can be delivered.
3. **Sufficient balance** — your CSBoard balance must cover the total cost of the items at their live prices.
## Request headers
Optional. A unique string (e.g. a UUID) that identifies this order attempt. If you retry a request with the same key, the server replays the original order response instead of executing a second purchase. Use this to safely retry on network timeouts without risk of double-charging.
## Request body
Array of 1–10 unique listing IDs to purchase. Obtain these from the `id` field of `GET /v1/listings` responses. Each ID must appear only once per request.
Total price ceiling in USD, enforced atomically at execution time. If the live total of all items exceeds this value, the entire order is rejected with a `price_moved` error and you are not charged. **Strongly recommended** — without it you have no overcharge protection.
Alternative to the `Idempotency-Key` header. If both are provided, the header takes precedence. Use one or the other, not both.
## Response fields
Unique identifier for this order, e.g. `ord_01J9Z3K8Q2`.
Current order status: `processing`, `completed`, or `failed`.
Per-item breakdown of the order.
The listing ID that was purchased.
The amount charged for this specific item at its live price.
Delivery mode for this item: `instant` (transferred immediately) or `hold` (subject to Steam trade hold).
Sum of all per-item charges. This is the total amount debited from your balance.
Your CSBoard balance immediately after the debit.
ISO 8601 timestamp of when the order was created.
## Example request
```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
}'
```
## Example response
```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"
}
```
## Error codes
| HTTP status | Code | Meaning |
| ----------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 409 | `price_moved` | The live total of your items exceeded `max_price_usd`. Order rejected; no charge made. The response includes `current_total_usd` showing the actual price. |
| 402 | `insufficient_balance` | Your balance is too low to cover the order total. |
| 400 | `steam_account_required` | No linked Steam account or valid trade URL on your CSBoard account. |
| 403 | `trading_not_enabled` | The API key does not have buying enabled. Enable it in your profile. |
| 401 | `unauthorized` | Missing or invalid API key. |
| 429 | `rate_limit_exceeded` | Over 30 requests/min. Wait for the `Retry-After` header value before retrying. |
Always include `max_price_usd` in your request. Prices on a live marketplace can change between the moment you query `/v1/listings` and the moment your order executes. Without this ceiling, your balance could be debited at a higher price than you intended, and there is no automatic rollback.
Items delivered via `hold` are subject to a Steam trade hold. Check the `tradable_at` field on the original listing (from `GET /v1/listings`) to see exactly when a held item will become tradable in your Steam inventory.
## 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.
````