Balance Query

Returns the balance status of the account that owns the current API key, including available balance, lifetime credits and lifetime spend.

This endpoint is part of the OfoxAI OpenAPI and is protocol-agnostic (independent of OpenAI / Anthropic / Gemini). Any valid OfoxAI API key can call it; the response shape is compatible with cc-switch and similar third-party tools.

Endpoint


GET https://api.ofox.ai/v1/user/balance

The same endpoint is also exposed via the Anthropic / Gemini entries, so clients already configured with a different Base URL can reuse it:

URL
`https://api.ofox.ai/v1/user/balance`
`https://api.ofox.ai/anthropic/user/balance`
`https://api.ofox.ai/gemini/user/balance`

All three URLs return identical response structures.

Authentication

Pass any valid OfoxAI API key (sk-...) via the Authorization: Bearer header:


Authorization: Bearer sk-xxx

Use a user-level API key (created in the Dashboard ). Do not use internal / gateway keys.

Request Example

cURL

Terminal


curl https://api.ofox.ai/v1/user/balance \
  -H "Authorization: Bearer $OFOX_API_KEY"

Python

balance.py


import os
import requests
 
resp = requests.get(
    "https://api.ofox.ai/v1/user/balance",
    headers={"Authorization": f"Bearer {os.environ['OFOX_API_KEY']}"},
)
data = resp.json()
print(f"Available balance: ${data['balance']:.4f} {data['currency']}")

TypeScript

balance.ts


const resp = await fetch('https://api.ofox.ai/v1/user/balance', {
  headers: { Authorization: `Bearer ${process.env.OFOX_API_KEY}` },
})
const data = await resp.json()
console.log(`Available balance: $${data.balance.toFixed(4)} ${data.currency}`)

Response Format

Successful response 200 OK:


{
  "is_active": true,
  "balance": 42.1357,
  "total": 100.0000,
  "used": 57.8643,
  "currency": "USD"
}

Response Fields

Field	Type	Description
`is_active`	boolean	Whether the account is usable. Returns `true` once authentication passes; `false` on auth failure
`balance`	number	Current available balance, equal to `total - used`
`total`	number	Lifetime credits: top-ups + bonuses + gift cards
`used`	number	Lifetime spend: total consumption across all calls
`currency`	string	Currency unit, fixed to `"USD"`

All amounts are in USD as 64-bit floats. Internally we track to NanoDollar precision (10⁻⁹ USD), so values are accurate down to sub-cent fractions.

Error Response

On auth failure or service error, a non-200 response is returned with a body compatible with cc-switch:


{
  "error": "unauthenticated",
  "is_active": false
}

Status	`error`	Description
`401`	`unauthenticated`	API key is invalid, disabled, or expired
`500`	`internal error`	Internal service error — please retry

Third-Party Tool Compatibility

The response shape is compatible with the cc-switch balance-query template and works as a drop-in balance provider for cc-switch:

is_active for status checks
balance maps to cc-switch’s remaining field
total / used drive the usage-progress UI