> ## 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 — Account Balance and Trading Status
> Check your CSBoard balance in USD, how much is settled versus held, and whether trading is enabled for your API key.
The balance endpoint returns your current balance in USD along with the breakdown that matters for automated buying: how much is **settled** (reversal-safe and available to spend on reversal-safe purchases) versus how much is currently **held**. Use `trading_enabled` to confirm buying is turned on for the key before you attempt an order.
**Authentication required.** Send your key as `Authorization: Bearer csb_pub_...`.
## Parameters
This endpoint takes no query parameters.
## Response fields
Always `"USD"`. All amounts are denominated in US dollars.
Your total balance in USD.
Whether buying is enabled for this API key. If `false`, purchase endpoints return `trading_not_enabled`.
The portion of your balance that is settled and reversal-safe. This is what you can spend on reversal-safe purchases such as `POST /v1/market/buy`.
The portion of your balance currently held.
ISO 8601 timestamp of when the held portion clears, or `null` if nothing is held.
## Example request
```bash theme={null}
curl https://csboard.com/v1/balance \
-H "Authorization: Bearer csb_pub_..."
```
## Example response
```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"
}
```
## Error codes
| HTTP status | Code | Meaning |
| ----------- | ------------------------------------- | --------------------------------------------------------------- |
| 401 | `missing_api_key` / `invalid_api_key` | Missing or invalid API key. |
| 429 | `rate_limit_exceeded` | Too many requests. Back off for the `Retry-After` header value. |
Check `settled_balance_usd`, not `balance_usd`, before calling reversal-safe purchase endpoints — held funds cannot be spent there.
## 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.
````