跳转到主要内容
你可以使用汇率查询,在创建换汇或跨币种出款前确认 UQPAY 是否为某个货币对提供当前汇率。List Current Rates接口会返回一个或多个货币对的最新可用汇率,并列出请求中当前不可用的货币对。 汇率查询适用于能力发现、价格预览和运营检查。它不会创建 quote_id,也不会为后续交易锁定汇率。要执行换汇或跨币种出款,请在提交交易前立即创建报价。

何时使用汇率查询

当你需要完成以下操作时,调用 List Current Rates
  • 在你的 UI 中展示可用 FX 货币对。
  • 在调用 Create Quote 前,检查某个货币对当前是否支持。
  • 为资金或运营团队刷新参考买入价和卖出价。
  • 通过 unavailable_currency_pairs 识别不支持或暂时不可用的货币对。
  • 在主账户或子账户创建换汇、出款前做价格检查。
如果需要可执行汇率,请使用 Create Quote。报价响应会返回 quote_id、计算后的 buy_amountsell_amount,以及有效期窗口。

汇率查询与报价的区别

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

步骤1:查询当前汇率

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

查询指定货币对

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

查询全部可用汇率

如果需要获取当前全部可用货币对,请省略 currency_pairs
如果要查询某个子账户的汇率,请在 x-on-behalf-of 中传入子账户 ID。

步骤2:读取响应

成功响应会将结果包裹在 data 对象中:可用汇率在 data.rates 中,请求中不可用的货币对在 data.unavailable_currency_pairs 中,汇率更新时间在 data.last_updated 中。
如果某个请求货币对出现在 unavailable_currency_pairs 中,不要继续为该货币对创建报价。请向用户展示清晰提示,或引导交易改用其他支持的货币对。

步骤3:在创建报价前使用汇率

你可以先用 List Current Rates 做前置检查,再在用户或系统准备执行交易时调用 Create Quote。 推荐流程:
  1. 查询计划使用货币对的当前汇率。
  2. 如果货币对不可用,停止流程并要求用户选择其他货币对。
  3. 如果货币对可用,展示汇率预览或继续进入你的审批流程。
  4. 在执行前立即调用 Create Quote
  5. 在报价有效期内,使用返回的 quote_id 提交 Create ConversionCreate Payout

子账户定价上下文

该接口支持 x-on-behalf-of。当你需要查询特定子账户的汇率上下文时,请使用该 Header:
  • 对于主账户操作,省略 x-on-behalf-of
  • 对于子账户操作,将 x-on-behalf-of 设置为子账户的 account_id
  • 后续调用 Create Quote 和对应创建接口时,使用相同的账户上下文。
保持相同账户上下文,可以避免 FX 产品配置、币种开通和定价不一致。

常见校验问题