查询余额

本节将介绍如何通过 OpenKey.Cloud 提供的系统内部 API 接口来查询账号/令牌的余额信息。

# 查询账户余额
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	格式说明

响应

{
  "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	格式说明

响应

{
  "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

查询账号余额

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

查询令牌余额

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

---

6. 注意事项

• 确保 Authorization 使用正确的 Bearer token。

• 返回中的 timestamp 为客户端获取响应时的 Unix 秒级时间戳，可用于同步或对账。

• 余额数值保留 3 位小数，便于前端展示小额单位。