> ## 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.

# 闪兑

> 币种兑换支持商户直接使用支付账户余额完成币种转换，是多币种运营和余额管理中的关键能力。

## 概述

换汇服务支持以下场景：

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

有关请求头、签名规则和回调验签，请参见 [认证与安全](/essentials/version/100/cn/common/authentication)。

## 接入流程

标准换汇流程如下：

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

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

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

**接口:** `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`  | 字符串 | 最终卖出金额                   |

#### 请求示例

```json theme={null}
{
  "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`).

有关其他产品的回调信息，请参见 [通知与回调](/essentials/version/100/cn/common/notification)。

## 错误处理

有关完整错误码和处理步骤，请参见 [错误码与最佳实践](/essentials/version/100/cn/common/error)。

## 接入检查清单

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

## 相关文档

* [认证与安全](/essentials/version/100/cn/common/authentication)
* [账户查询与对账](/essentials/version/100/cn/common/balance)
* [错误码与最佳实践](/essentials/version/100/cn/common/error)
* [接入总览](/essentials/version/100/cn/common/overview)