> ## 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.
# GET /v1/balance — 账户余额与交易状态
> 查询您的 CSBoard 美元余额，已结算和冻结的金额，以及您的 API 密钥是否启用了交易。
balance 端点返回您当前以美元计的余额，以及对自动化购买至关重要的明细：有多少是**已结算**（不可撤销且可用于不可撤销购买）的，以及当前有多少处于**冻结**状态。请使用 `trading_enabled` 在尝试下单之前确认该密钥已开启购买功能。
**需要身份验证。** 请将密钥作为 `Authorization: Bearer csb_pub_...` 发送。
## 参数
此端点不接受任何查询参数。
## 响应字段
始终为 `"USD"`。所有金额均以美元计价。
您以美元计的总余额。
此 API 密钥是否启用了购买功能。如果为 `false`，购买端点将返回 `trading_not_enabled`。
您余额中已结算且不可撤销的部分。这部分余额可用于不可撤销的购买，例如 `POST /v1/market/buy`。
您余额中当前处于冻结状态的部分。
冻结部分解冻时的 ISO 8601 时间戳；如果没有冻结金额，则为 `null`。
## 示例请求
```bash theme={null}
curl https://csboard.com/v1/balance \
-H "Authorization: Bearer csb_pub_..."
```
## 示例响应
```json theme={null}
{
"currency": "USD",
"balance_usd": 1240.55,
"trading_enabled": true,
"settled_balance_usd": 980.10,
"held_usd": 260.45,
"held_until": "2026-07-06T12:00:00Z"
}
```
## 错误代码
| HTTP 状态码 | 代码 | 含义 |
| -------- | ------------------------------------- | --------------------------------- |
| 401 | `missing_api_key` / `invalid_api_key` | API 密钥缺失或无效。 |
| 429 | `rate_limit_exceeded` | 请求过多。请按照 `Retry-After` 响应头中的秒数退避。 |
在调用不可撤销的购买端点之前，请检查 `settled_balance_usd` 而非 `balance_usd`——冻结资金无法用于此类购买。
## OpenAPI
````yaml GET /balance
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:
/balance:
get:
tags:
- Account
summary: Account balance and trading status
description: >-
Your current balance in USD, plus how much of it is settled
(reversal-safe) versus held. Use `settled_balance_usd` to know what is
available for reversal-safe spending, and `trading_enabled` to check
whether buying is turned on for this key.
operationId: getBalance
responses:
'200':
description: Current balance and trading status.
content:
application/json:
schema:
$ref: '#/components/schemas/Balance'
example:
currency: USD
balance_usd: 1240.55
trading_enabled: true
settled_balance_usd: 980.1
held_usd: 260.45
held_until: '2026-07-06T12:00:00Z'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
components:
schemas:
Balance:
type: object
properties:
currency:
type: string
example: USD
balance_usd:
type: number
description: Total balance in USD.
trading_enabled:
type: boolean
description: Whether buying is enabled for this key.
settled_balance_usd:
type: number
description: >-
Portion of the balance that is settled (reversal-safe) and spendable
on reversal-safe purchases.
held_usd:
type: number
description: Portion of the balance currently held.
held_until:
type:
- string
- 'null'
format: date-time
description: When the held portion clears, or null if nothing is held.
required:
- currency
- balance_usd
- trading_enabled
- settled_balance_usd
- held_usd
- held_until
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.
````