Balance Query

Query your DeepSeek API account balance to check available credits and currency information.

Through the balance query API, you can retrieve the current balance information for your DeepSeek API account, including total available balance, granted balance, and topped-up balance. Checking your balance before running long-duration tasks or batch calls helps avoid interruptions due to insufficient funds.

Basic Usage

Get your account balance via the model instance's balance() method:

import { createModel } from 'deepseek-kit'

const model = createModel({ model: 'deepseek-v4-flash' })

const response = await model.balance()

console.log(response.is_available)
console.log(response.balance_infos)

Balance Information Details

The response contains two fields: is_available and balance_infos:

const response = await model.balance()

if (response.is_available) {
  for (const info of response.balance_infos) {
    console.log(`Currency: ${info.currency}`)
    console.log(`Total balance: ${info.total_balance}`)
    console.log(`Granted balance: ${info.granted_balance}`)
    console.log(`Topped-up balance: ${info.topped_up_balance}`)
  }
}
else {
  console.log('Insufficient account balance for API calls')
}

Balance Field Descriptions

FieldDescription
currencyCurrency type, 'CNY' or 'USD'
total_balanceTotal available balance, including granted and topped-up balances
granted_balanceUnexpired granted balance
topped_up_balanceTopped-up balance

Balance Check Utility

Check your balance before executing batch tasks to ensure sufficient funds:

import { createModel } from 'deepseek-kit'

const model = createModel({ model: 'deepseek-v4-flash' })

async function checkBalanceBeforeRun() {
  const response = await model.balance()

  if (!response.is_available) {
    throw new Error('Insufficient balance. Please top up before retrying.')
  }

  const cnyInfo = response.balance_infos.find(b => b.currency === 'CNY')
  if (cnyInfo) {
    const total = Number.parseFloat(cnyInfo.total_balance)
    if (total < 1) {
      console.warn(`Warning: Balance is only ${cnyInfo.total_balance} ${cnyInfo.currency}. Consider topping up.`)
    }
  }

  return response
}

await checkBalanceBeforeRun()

Custom Configuration

The balance() method supports passing custom configuration to override the default API Key, Base URL, or timeout:

const response = await model.balance({
  timeout: 10000,
})

API Reference

model.balance() Parameters

apiKeystring
API key. Defaults to the model instance's configuration.
baseURLstring
API base URL. Defaults to the model instance's configuration.
timeoutnumber
Request timeout in milliseconds.

UserBalanceResponse

is_availableboolean
Whether the account has sufficient balance for API calls.
balance_infosBalanceInfo[]
Balance information list, displayed by currency type.

BalanceInfo

currency'CNY' | 'USD'
Currency type.
total_balancestring
Total available balance, including granted and topped-up balances.
granted_balancestring
Unexpired granted balance.
topped_up_balancestring
Topped-up balance.
Model List
Query the list of available models on the DeepSeek API, retrieving model identifiers and ownership information.
Integration Overview
deepseek-kit can work alongside frameworks like AI SDK and LangChain — embedding DeepSeek agents as subagents in other frameworks, or bringing other frameworks' agents in as tools for deepseek-kit.