POST /v1/orders — 使用余额购买 CS2 挂单

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"
}
'

import requests

url = "https://csboard.com/v1/orders"

payload = {
    "item_ids": ["itm_8841201", "itm_8841340"],
    "max_price_usd": 30,
    "idempotency_key": "6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    item_ids: ['itm_8841201', 'itm_8841340'],
    max_price_usd: 30,
    idempotency_key: '6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
  })
};

fetch('https://csboard.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://csboard.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'item_ids' => [
        'itm_8841201',
        'itm_8841340'
    ],
    'max_price_usd' => 30,
    'idempotency_key' => '6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://csboard.com/v1/orders"

	payload := strings.NewReader("{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://csboard.com/v1/orders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://csboard.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}"

response = http.request(request)
puts response.read_body

{
  "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 个人资料中进行配置。

前置条件

下单前，请确保：

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

请求头

string

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

请求体

string[]

必填

1–10 个唯一的挂单 ID 数组。请从 GET /v1/listings 响应的 id 字段获取。每个 ID 在一次请求中只能出现一次。

number

美元总价上限，将在执行时原子地强制执行。如果所有商品的实时总额超过该值，整个订单将以 price_moved 错误被拒绝，且不会扣款。强烈建议使用——若无此值，您将无任何超额扣款保护。

string

Idempotency-Key 请求头的替代方案。如果两者都提供，则以请求头为准。请二选一使用，不要同时使用。

响应字段

string

必填

本次订单的唯一标识符，例如 ord_01J9Z3K8Q2。

string

必填

当前订单状态：processing、completed 或 failed。

object[]

订单的逐件商品明细。

显示 Item object

string

被购买的挂单 ID。

number

按实时价格对该具体商品扣除的金额。

string

该商品的交付模式：instant（即时转移）或 hold（受 Steam 交易冻结约束）。

number

必填

所有逐件扣款的合计。这是从您余额中划扣的总金额。

number

扣款后您的 CSBoard 余额。

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 状态码	代码	含义
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 库存中可交易。

授权

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.

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.

响应

Order accepted and debited.

order_id

string

必填

status

enum<string>

必填

可用选项:

processing,

completed,

failed

total_charged_usd

number

必填

items

object[]

Show child attributes

balance_after_usd

number

created_at

string<date-time>

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"
}
'

import requests

url = "https://csboard.com/v1/orders"

payload = {
    "item_ids": ["itm_8841201", "itm_8841340"],
    "max_price_usd": 30,
    "idempotency_key": "6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    item_ids: ['itm_8841201', 'itm_8841340'],
    max_price_usd: 30,
    idempotency_key: '6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
  })
};

fetch('https://csboard.com/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://csboard.com/v1/orders",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'item_ids' => [
        'itm_8841201',
        'itm_8841340'
    ],
    'max_price_usd' => 30,
    'idempotency_key' => '6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://csboard.com/v1/orders"

	payload := strings.NewReader("{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://csboard.com/v1/orders")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://csboard.com/v1/orders")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"item_ids\": [\n    \"itm_8841201\",\n    \"itm_8841340\"\n  ],\n  \"max_price_usd\": 30,\n  \"idempotency_key\": \"6f9c2b10-1a2b-4c3d-8e4f-5a6b7c8d9e0f\"\n}"

response = http.request(request)
puts response.read_body

{
  "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"
}

​前置条件

​请求头

​请求体

​响应字段

​示例请求

​示例响应

​错误代码

授权

请求头

请求体

响应

前置条件

请求头

请求体

响应字段

示例请求

示例响应

错误代码