# 查询余额

> 本节将介绍如何通过 OpenKey.Cloud 提供的系统内部 API 接口来查询**账号/令牌**的余额信息。
>
> ```bash
> # 查询账户余额
> GET /v2/account/balance
>
> # 查询令牌余额
> GET /v2/token/balance
> ```

***

### 1. 查询账号余额（Account Balance）

#### 请求

```
GET /v2/account/balance
Host: https://openkey.cloud
Authorization: Bearer {token}
Content-Type: application/json
```

**请求头（Headers）**

| 名称            | 必须 | 类型     | 说明                |
| ------------- | -- | ------ | ----------------- |
| Authorization | ✅  | string | Bearer token，用于鉴权 |
| Content-Type  | ✅  | string | 格式说明              |

#### 响应

```json
{
  "type": "account",
  "balance": {
    "remained_cash": 8161.976,
    "used_cash":     274584.265,
    "currency":      "USD"
  },
  "timestamp": 1762259843
}
```

**字段说明**

| 字段                     | 类型      | 说明                      |
| ---------------------- | ------- | ----------------------- |
| type                   | string  | 本次查询对象类型，应为 `"account"` |
| balance.remained\_cash | float64 | 可用余额（单位：USD）            |
| balance.used\_cash     | float64 | 已使用余额（单位：USD）           |
| balance.currency       | string  | 币种，一般为 `"USD"`          |
| timestamp              | int64   | Unix 秒级时间戳              |

***

### 2. 查询令牌余额（Token Balance）

#### 请求

```
GET /v2/token/balance
Host: https://openkey.cloud
Authorization: Bearer {token}
Content-Type: application/json
```

**请求头（Headers）**

| 名称            | 必须 | 类型     | 说明                |
| ------------- | -- | ------ | ----------------- |
| Authorization | ✅  | string | Bearer token，用于鉴权 |
| Content-Type  | ✅  | string | 格式说明              |

#### 响应

```json
{
  "type": "token",
  "balance": {
    "remained_cash": 500.000,
    "used_cash":     0.000,
    "currency":      "USD"
  },
  "timestamp": 1762259865
}
```

**字段说明**

字段与“账号余额”一致，但 `type` 值为 `"token"`，表示查询的是当前令牌的余额。

***

### 3. 错误码与说明

* `401 Unauthorized`：鉴权失败或令牌非法。
* `429 Too Many Requests`：超过限流规则。
* `500 Internal Server Error`：服务器内部错误。
* `400 Bad Request`：请求头或参数有误。

***

### 4. 限流与使用说明

* 每个令牌每 60 秒最多允许 60 次调用，所有 `/v2` 共享容量，超出则返回 `429`。
* 保留 3 位小数显示余额，单位为 USD。

***

### 5. 示例 cURL

#### 查询账号余额

```bash
curl -H "Authorization: Bearer sk-XXXX" \
     -H "Content-Type: application/json" \
     https://openkey.cloud/v2/account/balance
```

#### 查询令牌余额

```bash
curl -H "Authorization: Bearer sk-XXXX" \
     -H "Content-Type: application/json" \
     https://openkey.cloud/v2/token/balance
```

***

### 6. 注意事项

* 确保 `Authorization` 使用正确的 Bearer token。
* 返回中的 `timestamp` 为客户端获取响应时的 Unix 秒级时间戳，可用于同步或对账。
* 余额数值保留 3 位小数，便于前端展示小额单位。