# Balance Query — OfoxAI OpenAPI

Source: https://ofox.ai/docs/api/openapi/balance

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

```http
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:

```http
Authorization: Bearer sk-xxx
```

Use a user-level API key (created in the [Dashboard](https://app.ofox.ai/manage/api-keys)). Do not use internal / gateway keys.

## Request Example

**cURL**

```bash filename="Terminal"
curl https://api.ofox.ai/v1/user/balance \
  -H "Authorization: Bearer $OFOX_API_KEY"
```

**Python**

```python filename="balance.py" showLineNumbers
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**

```typescript filename="balance.ts" showLineNumbers
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`:

```json
{
  "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:

```json
{
  "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](https://github.com/farion1231/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