跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

换汇服务支持以下场景：
  • 收款后换汇：将收到的款项转换为结算币种
  • 统一结算币种：以单一币种维护账户余额
  • 余额再平衡：优化各账户之间的币种分布
有关请求头、签名规则和回调验签，请参见 认证与安全。

​
接入流程

标准换汇流程如下： 
查询可交易范围 → 获取报价 → 创建闪兑订单 → 查询结果
下文将对每一步进行详细说明。

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

接口: 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兑换失败，资金已退回原账户

​
重试与错误处理

​
处理不确定响应

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

​
常见失败场景

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

​
回调行为

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

​
错误处理

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

​
接入检查清单

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

​
相关文档