Track DeepSeek API spend and get warned before balance hits zero

How DeepSeek balance and account limits work

DeepSeek doesn't bill you at the end of the month based on usage. You have to top up your account balance in advance, and every API call draws down that prepaid balance until nothing remains.

The biggest issue for teams running production workloads is access control. DeepSeek has no read-only keys, so any key you generate to query your account balance can also call models and generate completions. Every single key in your account shares one balance pool, which means a background batch job, a test script, and your customer-facing API all pull from the exact same funds.

Can you cap a single key? No. DeepSeek has no per-key spending limits, so you can't isolate an experimental project or give a staging environment a strict ten-dollar cap. If a script gets stuck in a tight loop, it burns down the credit pool for the entire workspace. And because there are no granular key roles, if a key leaks, you have to delete it on platform.deepseek.com immediately.

Calling the DeepSeek balance endpoint

To inspect your funds programmatically, DeepSeek provides a dedicated balance endpoint. You make an HTTP GET request to https://api.deepseek.com/user/balance and pass your secret key in the standard bearer token format.

Here is how you call the endpoint using curl:

curl --silent --show-error --max-time 60 "https://api.deepseek.com/user/balance" \
  --header "Authorization: Bearer ${DEEPSEEK_API_KEY}"

It runs silently. When the call succeeds, DeepSeek returns an HTTP 200 status code with user balance info formatted as application/json. Notice the --max-time 60 flag; DeepSeek's official curl and Python documentation examples explicitly set a 60-second request timeout on this endpoint. If your monitoring worker runs without an explicit timeout, a stalled management request can hang your monitoring process indefinitely.

Reading the balance response fields

A successful HTTP 200 response contains an is_available boolean and an array of objects named balance_infos.

Here is an example response payload:

{
  "is_available": true,
  "balance_infos": [
    {
      "currency": "CNY",
      "total_balance": "110.00",
      "granted_balance": "10.00",
      "topped_up_balance": "100.00"
    }
  ]
}

The is_available boolean indicates whether the user's balance is sufficient for API calls. If this is false, your account cannot make model calls, period.

Inside the balance_infos array, each object includes four fields:

• currency: a string indicating the balance currency, with possible values of CNY or USD.
• total_balance: a decimal string showing the total available balance, which is the sum of the granted balance and the topped-up balance (such as "110.00").
• granted_balance: a decimal string showing the total not expired granted balance (such as "10.00").
• topped_up_balance: a decimal string showing the total topped-up balance (such as "100.00").

Don't parse them loosely. Because total_balance, granted_balance, and topped_up_balance arrive as decimal strings rather than native JSON numbers, your parsing logic must cast them to decimal or floating-point types before running numeric threshold checks in code.

What happens at zero balance and API error handling

When your account balance hits zero, DeepSeek doesn't throttle you gracefully or queue your requests. Your API calls immediately fail with error code 402 - Insufficient Balance.

The documented cause for a 402 is simply that you have run out of balance. The documented solution is to check your account's balance and go to the Top up page to add funds. If you don't monitor your balance proactively, you only find out your credits are gone when your production error logs start lighting up with 402 responses.

Your error-handling logic should also recognize DeepSeek's other documented error codes:

• 400 - Invalid Format: The request body format is invalid.
• 401 - Authentication Fails: Authentication fails due to the wrong API key.
• 422 - Invalid Parameters: Your request contains invalid parameters.
• 429 - Rate Limit Reached: You are sending requests too quickly, or have exceeded a concurrency or QPS limit.
• 500 - Server Error: DeepSeek's server encounters an issue.
• 503 - Server Overloaded: The server is overloaded due to high traffic.

When you see a 429 or 503, retrying with backoff makes sense. But when a 402 occurs, retries won't fix it (it just wastes compute), because no call will succeed until somebody manually tops up the account.

Setting up custom balance alerts

To get warned before your balance runs out and triggers 402 - Insufficient Balance errors, you can poll the balance endpoint on a schedule. If you prefer running your own infrastructure, you can write a lightweight Python script to query the endpoint and check the balance against a threshold:

import os
import requests

response = requests.get(
    "https://api.deepseek.com/user/balance",
    headers={"Authorization": f"Bearer {os.environ['DEEPSEEK_API_KEY']}"},
    timeout=60,
)

if response.status_code == 200:
    data = response.json()
    if not data.get("is_available"):
        print("Alert: DeepSeek balance is insufficient for calls!")
    for info in data.get("balance_infos", []):
        currency = info.get("currency")
        total = float(info.get("total_balance", "0.0"))
        print(f"Currency: {currency}, Total Balance: {total}")

How often should you poll? If you poll once a day, an unexpected traffic spike can wipe out your credits hours before your next check runs. But if you poll too often from ephemeral jobs, you have to manage secrets, alerts, and cron failures yourself.

Tracking DeepSeek spend automatically with Costbrake

If you don't want to maintain your own balance-checking cron jobs, Costbrake tracks your balances and spend across 23 providers, including DeepSeek, OpenAI, Anthropic, AWS, and Google Cloud. Read our guide on How do I monitor spend across OpenAI, Anthropic, Gemini and other AI APIs in one place? to see how multi-provider tracking fits together.

Because DeepSeek only reports an account balance, Costbrake reads the balance endpoint and counts drops in balance between checks as spend, spreading that spend evenly over those hours. A top-up between two checks hides the spend inside that window, and currently only the USD balance is tracked (accounts that pay in CNY aren't supported yet).

DeepSeek has no read-only keys and no per-key limits, so there is no killswitch (brakes aren't available for DeepSeek). You connect the key you already use to call models. Stored credentials are encrypted with AES-256-GCM.

Costbrake gives you several distinct alert types:

• Budget alerts: Default warnings when your spend reaches 50%, 80%, and 100% of your budget.
• Spike alerts: Triggered when an hour costs more than 3x your usual hour (based on a 7-day baseline) and at least $5 more than usual.
• Forecast alerts: Triggered when month-to-date spend plus your pace over the last 72 hours is projected to pass your budget by month-end.
• New-charge alerts: Triggered when a new service first appears this month above $1.

On the Free plan ($0 flat), Costbrake checks your balance hourly, keeps 30 days of history, supports 3 budgets, 1 seat, and 2 provider connections with email alerts. The Pro plan costs $12 a month (or $120 a year) and provides 5-minute checks (every 2 minutes for DeepSeek during an active spike), 10 connections, 3 seats, 12 months of history, 50 budgets, brakes for supported providers, and alerts over Slack, Discord, and signed webhooks. Team is $39 a month or $390 a year for 50 connections, unlimited seats, 36 months of history, 500 budgets, PagerDuty, and a REST API. You can review all tier details on our Costbrake pricing page.

Every new workspace starts with a 14-day Pro trial without needing a credit card. You can connect by hand at https://app.costbrake.com/signin or tell your coding tool to run the agent setup.