闪兑 - Gate Pay DOCS

概述

换汇服务支持以下场景：

收款后换汇：将收到的款项转换为结算币种
统一结算币种：以单一币种维护账户余额
余额再平衡：优化各账户之间的币种分布

有关请求头、签名规则和回调验签，请参见认证与安全。

接入流程

标准换汇流程如下：

查询可交易范围 → 获取报价 → 创建闪兑订单 → 查询结果

下文将对每一步进行详细说明。

第一步：查询可交易币种范围（可选）

接口: GET /v1/pay/convert/currency 获取可用于兑换的币种列表。该步骤为可选，但建议用于用户界面初始化和校验。

查询参数

参数	类型	必填	说明
`side`	字符串	否	按 `buy` 或 `sell` 方向筛选

响应字段

响应会包含可用币种及其精度和金额限制：

minBuyAmount: 最小买入金额（适用字段精度规则）
maxBuyAmount: 最大买入金额（适用字段精度规则）
minSellAmount: 最小卖出金额（适用字段精度规则）
maxSellAmount: 最大卖出金额（适用字段精度规则）

步骤 2: 查询可用币种交易对（可选）

接口: GET /v1/pay/convert/pair 获取支持的交易对和汇率信息。

查询参数

参数	类型	必填	说明
`currency`	字符串	否	按基础币种筛选交易对
`side`	字符串	否	按 `buy` 或 `sell` 方向筛选

步骤 3: 获取报价

接口: POST /v1/pay/convert/preview 生成币种兑换报价。报价包含过期时间戳；已过期报价不能用于创建订单。

请求参数

字段	类型	必填	说明
`buyCurrency`	字符串	是	要买入的目标币种
`sellCurrency`	字符串	是	要卖出的来源币种
`buyAmount`	字符串	有条件	要买入的金额 (与以下字段互斥： `sellAmount`)
`sellAmount`	字符串	有条件	要卖出的金额 (与以下字段互斥： `buyAmount`)

注意: 请传入 buyAmount 或 sellAmount，不能同时传入。

响应字段

字段	类型	说明
`quoteId`	字符串	唯一报价标识；创建订单时必填
`exchangeRate`	字符串	当前汇率
`buyAmount`	字符串	目标币种金额
`sellAmount`	字符串	来源币种金额
`expirationTime`	时间戳	报价过期时间戳

步骤 4: 创建闪兑订单

接口: POST /v1/pay/convert 使用有效报价创建币种兑换订单。该接口具备幂等性：多次提交相同 clientReqId 会返回相同业务结果。

请求参数

字段	类型	必填	说明
`quoteId`	字符串	是	步骤 3 返回的报价 ID
`buyCurrency`	字符串	是	目标币种
`sellCurrency`	字符串	是	来源币种
`buyAmount`	字符串	是	要买入的金额
`sellAmount`	字符串	是	要卖出的金额
`clientReqId`	字符串	是	商户生成的唯一请求 ID，用于幂等控制

响应字段

字段	类型	说明
`orderId`	字符串	用于查询的平台订单号
`clientReqId`	字符串	与请求中一致
`status`	字符串	初始订单状态（通常为 `processing`）
`buyAmount`	字符串	最终买入金额
`sellAmount`	字符串	最终卖出金额

请求示例

{
  "quoteId": "QUOTE_abc123",
  "buyCurrency": "BTC",
  "sellCurrency": "USDT",
  "buyAmount": "0.5",
  "sellAmount": "21500",
  "clientReqId": "SWAP_20240101_001"
}

步骤 5: 查询闪兑订单

接口: GET /v1/pay/convert/order 查询闪兑订单的状态和详情。支持多个查询键以提高灵活性。

查询参数

参数	类型	必填	说明
`orderId`	字符串	有条件	平台订单号
`clientReqId`	字符串	有条件	商户生成的请求 ID

注意: 请传入 orderId 或 clientReqId（不要求两者都传，但至少传一个）。

响应字段

字段	类型	说明
`orderId`	字符串	平台订单号
`clientReqId`	字符串	商户请求 ID
`status`	字符串	订单状态（见下方枚举）
`buyCurrency`	字符串	目标币种
`sellCurrency`	字符串	来源币种
`buyAmount`	字符串	最终买入金额
`sellAmount`	字符串	最终卖出金额
`completionTime`	时间戳	订单完成时间戳

Swap 订单状态枚举

状态	说明
`processing`	订单处理中，请稍后查询
`success`	兑换已成功完成，资金已进入账户
`failure`	兑换失败，资金已退回原账户

重试与错误处理

处理不确定响应

如果发生网络超时或响应不确定：

先查询: 使用 clientReqId 或 orderId 调用 GET /v1/pay/convert/order 确认最终状态
仅在必要时重试: 仅当查询结果仍不确定时，才复用相同 clientReqId 创建订单
保持幂等性: 保持 clientReqId 不变，以确保获得相同业务结果

常见失败场景

失败原因	说明	处理建议
余额不足	账户中卖出币种余额不足	充值账户或降低卖出金额
不支持的交易对	币种交易对不可用	使用其他币种交易对
报价已过期	报价有效期已过	使用以下接口生成新报价： `POST /v1/pay/convert/preview`
数量精度非法	金额不符合币种精度规则	按精度要求调整金额
金额超出限制	金额超过币种限制	通过以下接口查看限制： `GET /v1/pay/convert/currency`

回调行为

闪兑能力不提供异步回调。最终订单确认必须通过查询 API 获取 (GET /v1/pay/convert/order). 有关其他产品的回调信息，请参见通知与回调。

错误处理

有关完整错误码和处理步骤，请参见错误码与最佳实践。

接入检查清单

从以下接口获取可用币种交易对： GET /v1/pay/convert/pair
实现报价获取与过期处理
为每个闪兑请求生成唯一 clientReqId
使用有效报价创建闪兑订单
实现订单确认的查询兜底
妥善处理所有失败场景
存储订单 ID 以便后续对账
监控兑换汇率和限额

​概述

​接入流程

​第一步：查询可交易币种范围（可选）

​查询参数

​响应字段

​步骤 2: 查询可用币种交易对（可选）

​查询参数

​步骤 3: 获取报价

​请求参数

​响应字段

​步骤 4: 创建闪兑订单

​请求参数

​响应字段

​请求示例

​步骤 5: 查询闪兑订单

​查询参数

​响应字段

​Swap 订单状态枚举

​重试与错误处理

​处理不确定响应

​常见失败场景

​回调行为

​错误处理

​接入检查清单

​相关文档

概述

接入流程

第一步：查询可交易币种范围（可选）

查询参数

响应字段

步骤 2: 查询可用币种交易对（可选）

查询参数

步骤 3: 获取报价

请求参数

响应字段

步骤 4: 创建闪兑订单

请求参数

响应字段

请求示例

步骤 5: 查询闪兑订单

查询参数

响应字段

Swap 订单状态枚举

重试与错误处理

处理不确定响应

常见失败场景

回调行为

错误处理

接入检查清单

相关文档