> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询账户余额

> 获取可用的 YCloud 账户余额和币种。

## 概述

Balance API 返回已认证 YCloud 账户的可用余额。可用于运维监控、账单告警以及身份验证检查。

## 准备工作

* 安全存储您的 YCloud API 密钥。
* 确定您的应用程序需要获取余额信息的频率。
* 根据预期的发送量定义告警阈值。

## 运作方式

该端点为只读接口，且始终作用于 API 密钥所标识的账户。它不支持在路径或请求体中传入账户 ID。

请在监控任务中使用它，而不是在每次发送消息前调用。频繁在单条消息发送前检查余额会增加延迟，且不会预留资金。

## 请求

`GET /balance`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.ycloud.com/v2/balance \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"
```

## 响应

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 190.0765,
  "currency": "USD"
}
```

| 字段 | 说明 |
| - | - |
| `amount` | 可用账户余额。 |
| `currency` | 账户所使用的币种。 |

## 监控建议

* 在余额达到可能中断生产
  流量的水平之前发出告警。
* 在仪表板和告警中包含币种信息。
* 为 API 故障设置单独的告警，避免将检查失败
  误判为余额为零。
* 严格限制对余额数据的访问权限，将其视为财务信息。

## 限制与排错

* 成功的余额响应可验证 API 密钥和 Base URL 的有效性。
* 即使 API 身份验证成功，
  余额不足也会影响计费消息产品的发送。
* 请勿假定金额单位为美元（USD）；请读取 `currency`。
* 避免在监控日志输出中记录 API 密钥。

<Card title="Balance API 参考" icon="wallet" href="/api-reference/balance/retrieve-balance">
  查看完整的响应结构并测试只读请求。
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.