# 查询余额

> 本节将介绍如何通过 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 位小数，便于前端展示小额单位。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.openkey.cloud/tool/balance.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.