API reference
Wallet
Read-only wallet balance and active reserved USD.
Get wallet balance
GET/api/v1/wallet
API key or token
Balance and USD currently reserved by jobs, workflow runs and turns.
Example request
curl "https://api.cognichem.com/api/v1/wallet" \
-H "X-Api-Key: $COGNICHEM_API_KEY"from cognichem_client import CogniChem
client = CogniChem.from_env()
result = client.wallet.balance()
print(result)Python SDK pip install cognichem-client (1.1 or later). from_env() reads COGNICHEM_API_KEY.
Responses
Successful Response · application/json · WalletBalanceResponse
| Field | Type | Description |
|---|---|---|
active_reservedrequired | number | |
balancerequired | number |
{
"active_reserved": 0.75,
"balance": 12.5
}Errors are RFC 7807 problem details (application/problem+json) with status, title, detail, request_id, and a retryability hint (validation, auth, quota, conflict, upstream, timeout, or terminal). Handling errors
| Status | When |
|---|---|
400 | Invalid input or business rule violation. |
401 | Missing or invalid credentials. |
402 | Wallet cannot cover the Assistant turn hold. |
403 | Authenticated but not allowed to access the resource. |
404 | Resource not found or not owned by the user. |
409 | Conflict (e.g. idempotency key reuse with a different body). |
413 | Request body or workflow spec exceeds size caps. |
422 | Request body or query failed validation. |
429 | Rate limit exceeded. |
500 | Unexpected server error. |
503 | Dependency temporarily unavailable. |