Metadata-Version: 2.4
Name: check-balance
Version: 0.1.0
Summary: 一键查询当前 AI 服务的账户余额，支持 14 个主流 AI 提供商
Project-URL: Homepage, https://github.com/hanmumuHL/check_balance
Project-URL: Repository, https://github.com/hanmumuHL/check_balance
Project-URL: Issues, https://github.com/hanmumuHL/check_balance/issues
Author-email: Han_new_new <hanmumuHL@users.noreply.github.com>
License: MIT
License-File: LICENSE
Keywords: ai,api,balance,claude,deepseek,mcp,openai,opencode
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# check-balance

[中文文档](README_zh.md)

One-click balance checker for your AI API services. Supports 14 mainstream AI providers with automatic detection. Works as an MCP server or standalone CLI.

## Features

- **MCP Server** — Integrates with opencode, Claude Code, Cursor, Claude Desktop
- **CLI Tool** — Run `check-balance` in any terminal
- **Auto-detection** — Reads opencode config and environment variables
- **14 Providers** — China (￥) and International ($) regions
- **Cross-platform** — Linux, macOS, Windows (WSL supported)
- **Zero config** — Just set your API keys and go

## Supported Providers

### China Region (￥)

| Provider | API Key Env | Balance API | Status |
|----------|-------------|-------------|--------|
| DeepSeek | `DEEPSEEK_API_KEY` | `GET /user/balance` | ✅ Direct query |
| Moonshot / Kimi | `MOONSHOT_API_KEY` | `GET /v1/users/me/balance` | ✅ Direct query |
| MiniMax | `MINIMAX_API_KEY` | `GET /v1/token_plan/remains` | ✅ Direct query |
| StepFun | `STEP_API_KEY` | `GET /v1/accounts` | ✅ Direct query |
| Zhipu / GLM | `ZHIPU_API_KEY` | Quota API | ~ Quota info |
| DashScope / Qwen | `DASHSCOPE_API_KEY` | — | ⚠️ Console only |
| Baichuan | `BAICHUAN_API_KEY` | — | ⚠️ Console only |

### International Region ($)

| Provider | API Key Env | Balance API | Status |
|----------|-------------|-------------|--------|
| OpenAI | `OPENAI_API_KEY` | Usage/Cost API | ~ Usage + cost |
| Anthropic / Claude | `ANTHROPIC_API_KEY` | Admin Key Cost API | ~ Usage + cost |
| xAI / Grok | `XAI_API_KEY` | Balance API | ✅ Direct query |
| Together AI | `TOGETHER_API_KEY` | Usage API | ~ Usage + cost |
| Mistral | `MISTRAL_API_KEY` | — | ⚠️ Console only |
| Groq | `GROQ_API_KEY` | — | ⚠️ Console only |
| Cohere | `COHERE_API_KEY` | — | ⚠️ Console only |

> **Note:** Cursor subscription balance is not supported as Cursor uses its own proxy and does not expose API keys.

## Installation

```bash
pip install check-balance
```

## Usage

### As CLI

```bash
check-balance
# or
python -m check_balance
```

### As MCP Server

#### opencode

Add to your `opencode.json`:

```json
{
  "mcp": {
    "check-balance": {
      "type": "local",
      "command": ["python", "-m", "check_balance.mcp_server"],
      "enabled": true
    }
  }
}
```

Then type `/balance` in opencode or ask "check my AI balance".

#### Claude Code

Create `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}
```

Or add to `~/.claude/mcp.json` for global access.

#### Cursor

Create `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}
```

Or add to `~/.cursor/mcp.json` for global access.

#### Claude Desktop

Edit `claude_desktop_config.json`:

| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

```json
{
  "mcpServers": {
    "check-balance": {
      "command": "python",
      "args": ["-m", "check_balance.mcp_server"]
    }
  }
}
```

## How It Works

1. **Auto-detection** — Reads `opencode.json` to identify your current model/provider, then scans environment variables for all configured API keys
2. **Balance query** — Calls each provider's balance/usage API
3. **Formatted output** — Shows results with ￥ (China) or $ (International) currency

## Output Example

```
AI 服务余额查询
==================================================
 * DeepSeek (中国)
     余额: ￥ 142.50

   Moonshot (中国)
     余额: ￥ 3.00

   OpenAI (海外)
     OpenAI 未开放余额查询 API，近 30 天用量: $ 18.32
     控制台: https://platform.openai.com/usage

   Mistral (海外)
     未开放余额查询 API
     控制台: https://console.mistral.ai/usage

* 标记为当前使用的服务
```

## Development

```bash
git clone https://github.com/hanmumuHL/check_balance.git
cd check_balance
pip install -e ".[dev]"
pytest
```

## License

MIT
