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

# 汇率查询

> 在创建换汇或跨币种出款前查询当前 FX 汇率。

你可以使用汇率查询，在创建换汇或跨币种出款前确认 UQPAY 是否为某个货币对提供当前汇率。[List Current Rates](/zh/global-account/v1.6/api-reference/list-current-rates)接口会返回一个或多个货币对的最新可用汇率，并列出请求中当前不可用的货币对。

汇率查询适用于能力发现、价格预览和运营检查。它不会创建 `quote_id`，也不会为后续交易锁定汇率。要执行换汇或跨币种出款，请在提交交易前立即创建报价。

<h2 id="when-to-use-exchange-rates">
  何时使用汇率查询
</h2>

当你需要完成以下操作时，调用 [List Current Rates](/zh/global-account/v1.6/api-reference/list-current-rates)：

* 在你的 UI 中展示可用 FX 货币对。
* 在调用 [Create Quote](/zh/global-account/v1.6/api-reference/create-quote) 前，检查某个货币对当前是否支持。
* 为资金或运营团队刷新参考买入价和卖出价。
* 通过 `unavailable_currency_pairs` 识别不支持或暂时不可用的货币对。
* 在主账户或子账户创建换汇、出款前做价格检查。

如果需要可执行汇率，请使用 [Create Quote](/zh/global-account/v1.6/api-reference/create-quote)。报价响应会返回 `quote_id`、计算后的 `buy_amount` 或 `sell_amount`，以及有效期窗口。

<h2 id="exchange-rates-versus-quotes">
  汇率查询与报价的区别
</h2>

| 能力                                     | List Current Rates             | Create Quote              |
| -------------------------------------- | ------------------------------ | ------------------------- |
| 主要用途                                   | 检查当前可用汇率和货币对可用性。               | 锁定用于执行交易的参数。              |
| 返回 `quote_id`                          | 否                              | 是                         |
| 计算准确交易金额                               | 否                              | 是                         |
| 是否有有效期窗口                               | 响应包含 `last_updated`，但没有交易执行窗口。 | 报价必须在 `validity` 窗口内使用。   |
| 是否用于 Create Conversion 或 Create Payout | 否，仅用于前置检查。                     | 是，将返回的 `quote_id` 传入创建请求。 |

`buy_price` 和 `sell_price` 仅用于汇率预览和货币对可用性检查。它们不是可执行汇率，也不会锁定最终交易金额。客户确认换汇或跨币种出款时，请调用 Create Quote，并使用返回的 `quote_id` 和计算金额。

<h2 id="step-1-query-current-rates">
  步骤1：查询当前汇率
</h2>

你可以查询指定货币对，也可以不传 `currency_pairs`，返回全部可用货币对。

<h3 id="query-selected-currency-pairs">
  查询指定货币对
</h3>

将 `currency_pairs` 作为逗号分隔的列表传入。每个货币对必须是 6 位大写代码，例如 `USDEUR` 或 `USDJPY`。单次最多可请求 100 个货币对。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDEUR,USDJPY,JPYKRW' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

<h3 id="query-all-available-rates">
  查询全部可用汇率
</h3>

如果需要获取当前全部可用货币对，请省略 `currency_pairs`。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}'
```

如果要查询某个子账户的汇率，请在 `x-on-behalf-of` 中传入子账户 ID。

```bash theme={null}
curl --location 'https://api-sandbox.uqpaytech.com/api/v1/exchange/rates?currency_pairs=USDSGD' \
  --header 'Accept: application/json' \
  --header 'x-auth-token: {{token}}' \
  --header 'x-on-behalf-of: {{sub_account_id}}'
```

<h2 id="step-2-read-the-response">
  步骤2：读取响应
</h2>

成功响应会将结果包裹在 `data` 对象中：可用汇率在 `data.rates` 中，请求中不可用的货币对在 `data.unavailable_currency_pairs` 中，汇率更新时间在 `data.last_updated` 中。

```json theme={null}
{
  "data": {
    "rates": [
      {
        "currency_pair": "USDEUR",
        "buy_price": "0.8688",
        "sell_price": "0.8757"
      },
      {
        "currency_pair": "USDJPY",
        "buy_price": "161.4914",
        "sell_price": "162.7986"
      }
    ],
    "unavailable_currency_pairs": [
      "JPYKRW"
    ],
    "last_updated": "2026-07-16T16:15:58+08:00"
  }
}
```

| 字段                           | 含义                                   |
| ---------------------------- | ------------------------------------ |
| `rates`                      | 当前可用于请求货币对的汇率记录；如果未传筛选条件，则返回全部可用货币对。 |
| `currency_pair`              | 汇率适用的货币对。顺序可能遵循市场惯例，因此请始终读取响应中的实际值。  |
| `buy_price`                  | 当前买入价，四舍五入到 4 位小数。                   |
| `sell_price`                 | 当前卖出价，四舍五入到 4 位小数。                   |
| `unavailable_currency_pairs` | 请求中当前不支持或暂无可用汇率的货币对。                 |
| `last_updated`               | 最近一次汇率更新时间，格式为 ISO 8601。             |

如果某个请求货币对出现在 `unavailable_currency_pairs` 中，不要继续为该货币对创建报价。请向用户展示清晰提示，或引导交易改用其他支持的货币对。

<h2 id="step-3-use-rates-before-creating-a-quote">
  步骤3：在创建报价前使用汇率
</h2>

你可以先用 List Current Rates 做前置检查，再在用户或系统准备执行交易时调用 Create Quote。

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant UQPAY

    Client->>UQPAY: List Current Rates
    UQPAY-->>Client: 可用汇率和不可用货币对
    Client->>Client: 展示汇率预览或校验货币对
    Client->>UQPAY: Create Quote
    UQPAY-->>Client: quote_id、计算金额、有效期窗口
    Client->>UQPAY: 使用 quote_id 创建 Conversion 或 Payout
```

推荐流程：

1. 查询计划使用货币对的当前汇率。
2. 如果货币对不可用，停止流程并要求用户选择其他货币对。
3. 如果货币对可用，展示汇率预览或继续进入你的审批流程。
4. 在执行前立即调用 [Create Quote](/zh/global-account/v1.6/api-reference/create-quote)。
5. 在报价有效期内，使用返回的 `quote_id` 提交 [Create Conversion](/zh/global-account/v1.6/api-reference/create-conversion) 或 [Create Payout](/zh/global-account/v1.6/api-reference/create-payout)。

<h2 id="sub-account-pricing">
  子账户定价上下文
</h2>

该接口支持 `x-on-behalf-of`。当你需要查询特定子账户的汇率上下文时，请使用该 Header：

* 对于主账户操作，省略 `x-on-behalf-of`。
* 对于子账户操作，将 `x-on-behalf-of` 设置为子账户的 `account_id`。
* 后续调用 Create Quote 和对应创建接口时，使用相同的账户上下文。

保持相同账户上下文，可以避免 FX 产品配置、币种开通和定价不一致。

<h2 id="common-validation-issues">
  常见校验问题
</h2>

| 问题                                      | 处理方式                                         |
| --------------------------------------- | -------------------------------------------- |
| `currency_pairs` 包含小写值                  | 发送 6 位大写货币对，例如 `USDEUR`。                     |
| 请求超过 100 个货币对                           | 将请求拆分为多次调用。                                  |
| 某个货币对返回在 `unavailable_currency_pairs` 中 | 不要为该货币对创建报价。请选择其他支持的货币对，或稍后重试。               |
| 汇率查询显示可用，但 Create Quote 失败              | 确认账户上下文、FX 产品配置、报价 `transaction_type` 和换汇日期。 |
| 展示汇率与报价汇率不同                             | 报价才是可执行汇率。请刷新预览，并在执行前创建新报价。                  |

<h2 id="related-api-reference">
  相关 API Reference
</h2>

* [List Current Rates](/zh/global-account/v1.6/api-reference/list-current-rates)
* [Create Quote](/zh/global-account/v1.6/api-reference/create-quote)
* [Create Conversion](/zh/global-account/v1.6/api-reference/create-conversion)
* [Create Payout](/zh/global-account/v1.6/api-reference/create-payout)

<h2 id="related-guides">
  相关指南
</h2>

* [通过 API 创建换汇](/zh/global-account/v1.6/guide/create-conversion-via-api)
* [跨币种出款指南](/zh/global-account/v1.6/guide/cross-currency-payout-guide)