# getBalance 잔액 조회

> POST /getBalance로 계정 잔액(포인트, 1,000포인트 = ¥1)과 개발자 수익 배분·추천 보상 잔액을 조회해요. 포인트가 차감되지 않아 clientKey를 확인하는 데 쓸 수 있어요.

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

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/get-balance/

`getBalance`는 계정의 남은 포인트(1,000포인트 = ¥1)와 개발자 수익 배분 및 추천 보상 잔액(위안)을 반환해요. 포인트가 차감되지 않아서 `clientKey`가 올바른지 확인할 때 자주 써요.

- POST `https://api.yescaptcha.com/getBalance` (글로벌 엔드포인트)
- POST `https://cn.yescaptcha.com/getBalance` (중국 엔드포인트)

## 요청 파라미터

| 필드 | 타입 | 필수 | 설명 |
| --- | --- | --- | --- |
| `clientKey` | string | 예 | 계정의 ClientKey |

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

## 반환 결과

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

| 필드 | 타입 | 설명 |
| --- | --- | --- |
| `balance` | integer | 계정 잔액이며 단위는 포인트(1,000포인트 = ¥1)예요. 작업을 만들려면 10포인트보다 커야 해요 |
| `softBalance` | number | 개발자 수익 배분 잔액이며 단위는 위안이에요. [개발자 수익 배분](https://docs.yescaptcha.com/ko/account/developer.md)을 참고하세요 |
| `inviteBalance` | number | 추천 보상 잔액이며 단위는 위안이에요. [추천 보상](https://docs.yescaptcha.com/ko/account/referral.md)을 참고하세요 |
| `inviteBy` | integer | 나를 추천해 가입시킨 사용자의 ID이며, 없으면 0이에요 |
| `keyQuotaRemaining` | integer | 이 `clientKey`의 현재 주기에 남은 사용 한도이며 단위는 포인트예요. 한도를 설정한 `clientKey`에만 이 필드가 있고, 이때 `balance`는 계정 잔액과 남은 한도 중 작은 값이에요. 한도를 설정하지 않았다면 이 필드는 없어요 |

`clientKey`가 올바르지 않으면 `ERROR_KEY_DOES_NOT_EXIST`를 반환해요. `clientKey`에 IP 화이트리스트가 설정되어 있는데 요청을 보낸 IP가 목록에 없으면 `ERROR_KEY_IP_NOT_ALLOWED`를 반환해요. `getBalance`는 [자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)의 영향을 받아요. 일시 중지 중에는 `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);
}
```