Updated 2026-07-02
How to read DeepSeek's User Balance API before your workflows run out of budget
DeepSeek's official API reference includes a `GET /user/balance` endpoint for checking whether an account still has usable balance and how that balance is composed. This is not the same question as token pricing. Pricing tells you what the model costs; `/user/balance` tells you whether the account is still funded and whether the balance comes from granted credits or topped-up funds.
1. What the official User Balance endpoint returns
The official docs define `GET /user/balance` as a way to get the user's current balance. The response includes `is_available` plus a `balance_infos` array.
Each balance record includes `currency`, `total_balance`, `granted_balance`, and `topped_up_balance`. The docs list `CNY` and `USD` as the possible currency values.
That means the endpoint helps you separate two real account questions: do I still have enough balance to call the API, and how much of that balance comes from credits versus manual top-ups?
| Field | Official meaning | Operational use |
|---|---|---|
| is_available | Whether the balance is sufficient for API calls | Fast pass/fail check before starting jobs. |
| currency | Balance currency (`CNY` or `USD`) | Useful for finance and dashboard labeling. |
| total_balance | Total available balance | Top-level budget snapshot. |
| granted_balance | Not expired granted balance | Shows remaining credits or granted funds. |
| topped_up_balance | Manually topped-up balance | Shows paid funds separate from credits. |
curl https://api.deepseek.com/user/balance \
-H "Authorization: Bearer $DEEPSEEK_API_KEY"Sources checked
- DeepSeek official Get User Balance reference - Documents the schema for `GET /user/balance`.
2. `is_available` is a readiness signal, not a spend forecast
A common mistake is treating `is_available` as a budgeting model. It is not. The field tells you whether the balance is sufficient for API calls, but it does not estimate how long a large job will run or what the next request will cost.
For that second question, you still need the official pricing page plus your own token-usage estimates. In practice, `/user/balance` is the account readiness check, while pricing and token docs are the forecasting layer.
That split matters for batch jobs, coding agents, and scheduled workflows. Check `is_available` before you start, but do not assume a `true` value means every queued task is safely funded to completion.
Sources checked
- DeepSeek official Models & Pricing page - Use this to estimate model costs after balance verification.
- DeepSeek official Token & Token Usage page - Useful for translating prompt size into expected spend.
3. How to use balance checks in real DeepSeek workflows
The cleanest pattern is to call `/user/balance` before non-trivial jobs such as evaluation runs, long-context indexing, or coding-agent batches. Fail early if `is_available` is false, and log the returned balances for debugging or ops review.
This is also a good fit for dashboards and internal bots that need to warn before an account drains. Surface the `currency`, `granted_balance`, and `topped_up_balance` separately so operators can tell whether the account is living on expiring credits or on paid budget.
If you route traffic across multiple DeepSeek accounts, store balance snapshots alongside model routing data. That makes it easier to answer whether a failure came from bad credentials, empty balance, or an unrelated API issue.
const response = await fetch("https://api.deepseek.com/user/balance", {
headers: { Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}` },
});
const payload = await response.json();
if (!payload.is_available) {
throw new Error("DeepSeek balance unavailable for new jobs");
}
for (const info of payload.balance_infos) {
console.log(info.currency, info.total_balance, info.granted_balance, info.topped_up_balance);
}4. Keep account-balance checks separate from this site's stock rules
An account having DeepSeek balance does not mean this repo should list a new purchasable plan. The site's `/pricing` page is governed by actual stocked one-off Coding Plan inventory, not by generic API-account status.
That distinction matters because developers often mix up official API capability with local resale availability. `/user/balance` is an account introspection endpoint; it says nothing about this repo's stock, payment configuration, or plan cards.
For buyers, the useful next step after balance monitoring is usually operational: compare `/guides/deepseek-v4-pricing-per-million-tokens`, `/guides/deepseek-error-codes-guide`, and `/pricing` depending on whether the real problem is cost, failures, or access.
FAQ
What does `is_available` mean in DeepSeek `GET /user/balance`?
The official docs say it indicates whether the user's balance is sufficient for API calls.
What is the difference between `granted_balance` and `topped_up_balance`?
The docs separate not-expired granted balance from manually topped-up balance so you can see credits and paid funds independently.
Which currencies does DeepSeek document for balance info?
The official reference currently lists `CNY` and `USD` as possible currency values.
Does the User Balance endpoint tell me the cost of my next request?
No. It tells you whether balance is available and how the balance is composed. Use pricing and token-usage docs to estimate request cost.
DeepSeek's User Balance endpoint is the right preflight check for account readiness: read `is_available`, separate granted credits from topped-up funds, and combine that with pricing plus token usage instead of treating the balance API as a cost calculator.
Related model comparisons
Continue from this guide into structured DeepSeek-first comparison pages with model tables, routing advice, and pricing context.