> ## 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 в USD, сколько средств подтверждено, а сколько удерживается, а также включена ли торговля для вашего API-ключа.
Эндпоинт balance возвращает ваш текущий баланс в USD вместе с разбивкой, которая важна для автоматических покупок: сколько средств **подтверждено** (защищено от реверса и доступно для покупок, безопасных к реверсу) и сколько в данный момент **удерживается**. Используйте `trading_enabled`, чтобы убедиться, что покупки включены для ключа, прежде чем оформлять заказ.
**Требуется аутентификация.** Отправьте ключ как `Authorization: Bearer csb_pub_...`.
## Параметры
Этот эндпоинт не принимает query-параметров.
## Поля ответа
Всегда `"USD"`. Все суммы выражены в долларах США.
Ваш общий баланс в 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.
````