# getBalance 查询余额

> POST /getBalance 查询账户余额（点数，1 元 = 1000 点）以及开发者分成、邀请奖励余额，不扣点，可以用来验证 clientKey。

Source: https://docs.yescaptcha.com/zh/api/get-balance/ · Last verified: 2026-10-15

`getBalance` 返回账户的剩余点数（1 元 = 1000 点），以及开发者分成和邀请奖励的余额（元）。不扣点，常用来确认 `clientKey` 是否正确。

- POST `https://api.yescaptcha.com/getBalance` (国际节点)
- POST `https://cn.yescaptcha.com/getBalance` (国内节点)

## 请求参数

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `clientKey` | string | 是 | 账户密钥 |

```json
{ "clientKey": "YOUR_CLIENT_KEY" }
```

## 返回结果

```json
{
  "errorId": 0,
  "balance": 1071810,
  "softBalance": 36.0098,
  "inviteBalance": 0,
  "inviteBy": 0
}
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `balance` | integer | 账户余额，单位是点（1 元 = 1000 点）。必须大于 10 点才能创建任务 |
| `softBalance` | number | 开发者分成余额，单位是元，见 [开发者分成](https://docs.yescaptcha.com/zh/account/developer/) |
| `inviteBalance` | number | 邀请奖励余额，单位是元，见 [邀请奖励](https://docs.yescaptcha.com/zh/account/referral/) |
| `inviteBy` | integer | 邀请你注册的人的用户 ID，没有时为 0 |

`clientKey` 不对时返回 `ERROR_KEY_DOES_NOT_EXIST`。`getBalance` 受 [自动暂停](https://docs.yescaptcha.com/zh/api/rate-limits/) 影响：暂停期间返回 `ERROR_IP_BLOCKED_5MIN`。

## 示例

**curl**

get-balance.sh

```bash
#!/usr/bin/env bash
# Check the balance. getBalance is free and is a quick way to verify your clientKey
set -euo pipefail
curl -s https://api.yescaptcha.com/getBalance \
  -H 'Content-Type: application/json' \
  -d "{\"clientKey\": \"${YESCAPTCHA_CLIENT_KEY}\"}"
echo
```

**Python**

get_balance.py

```python
"""Check the balance. getBalance is free and is a quick way to verify your clientKey."""
import os

import requests

CLIENT_KEY = os.environ["YESCAPTCHA_CLIENT_KEY"]

r = requests.post(
    "https://api.yescaptcha.com/getBalance",
    json={"clientKey": CLIENT_KEY},
    timeout=30,
)
data = r.json()
if data.get("errorId"):
    # e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
    print("error:", data.get("errorCode"), data.get("errorDescription"))
else:
    print("balance (points):", data["balance"])
```

**Node.js**

get-balance.mjs

```js
// Check the balance. getBalance is free and is a quick way to verify your clientKey. Node.js 18+
const CLIENT_KEY = process.env.YESCAPTCHA_CLIENT_KEY;

const res = await fetch('https://api.yescaptcha.com/getBalance', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ clientKey: CLIENT_KEY }),
});
const data = await res.json();
if (data.errorId) {
  // e.g. ERROR_KEY_DOES_NOT_EXIST when the clientKey is wrong
  console.log('error:', data.errorCode, data.errorDescription);
} else {
  console.log('balance (points):', data.balance);
}
```