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

# 货币兑换

> 用报价锁定汇率、执行兑换，并跟踪至结算。

[Stablecoin Account API 发布方声明](/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

兑换是把账户中的一种货币换成另一种 —— 加密货币换法币、法币换加密货币或加密货币互换 —— 汇率在执行前预先锁定。流程固定为两次调用：先创建**报价**，再在报价失效前创建引用它的**兑换**。

<Info>
  **前置条件**

  * 通过 `x-auth-token` 请求头发送的 API token
  * 卖出币种有足够的 `available_balance`
</Info>

<h2 id="step-1-create-a-quote">
  步骤 1：创建报价
</h2>

调用 [Create Quote](/zh/stablecoin-account/v1.6/api-reference/create-quote)，传入币种对、金额，以及金额固定在哪一侧：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/ramp/conversion/quote \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sell_currency": "USDT",
    "buy_currency": "SGD",
    "amount": "100",
    "fixed_currency": "USDT"
  }'
```

`fixed_currency` 指定 `amount` 作用于哪一侧 —— 固定卖出侧表示花费确定的金额，固定买入侧表示收到确定的金额。

<Note>
  币种对限制：加密货币互换只允许 USDT 与另一种支持的币种配对。若任一侧是波动性资产（例如 BTC 或 ETH），固定币种只能是 USDT。
</Note>

**响应：**

```json theme={null}
{
  "code": 200,
  "message": "Success",
  "data": {
    "quote_id": "958813b7-8523-4b93-862e-46eddb87b56d",
    "sell_currency": "USDT",
    "sell_amount": "100",
    "buy_currency": "SGD",
    "buy_amount": "133.84",
    "currency_pair": "USDTSGD",
    "direct_rate": "1.3384723",
    "inverse_rate": "0.74712043",
    "processing_fee": "0",
    "network_fee": "0",
    "valid_from": "2026-04-27T10:47:26+08:00",
    "valid_to": "2026-04-27T10:50:26+08:00"
  }
}
```

报价汇率在 `valid_from` 至 `valid_to` 期间有效。若在执行前窗口已过，请重新获取报价 —— 过期的 `quote_id` 会被拒绝。

<h2 id="step-2-execute-the-conversion">
  步骤 2：执行兑换
</h2>

调用 [Create Conversion](/zh/stablecoin-account/v1.6/api-reference/create-conversion)，传入 `quote_id` 和与报价完全一致的金额，并携带幂等键：

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/ramp/conversion \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "958813b7-8523-4b93-862e-46eddb87b56d",
    "sell_currency": "USDT",
    "sell_amount": "100",
    "buy_currency": "SGD",
    "buy_amount": "133.84",
    "reason": "treasury rebalance"
  }'
```

响应返回兑换订单 —— `order_id`、`short_order_id`、`status`、买卖双方币种、使用的 `quote_price` 以及费用。`order_type` 依方向为 `Sell` 或 `Buy`。

<h2 id="step-3-track-the-conversion">
  步骤 3：跟踪兑换
</h2>

兑换状态从 `Submitted` / `Pending` 流转到 `Success`、`Failed` 或 `Submit Failed`。更新通过[换汇 webhook](/zh/stablecoin-account/v1.6/webhooks/conversion) 推送：

| 事件类型                              | 含义    |
| --------------------------------- | ----- |
| `ramp.conversion.trade.pending`   | 兑换进行中 |
| `ramp.conversion.trade.completed` | 兑换已完成 |
| `ramp.conversion.trade.failed`    | 兑换失败  |

可随时用 [Retrieve Conversion](/zh/stablecoin-account/v1.6/api-reference/retrieve-conversion) 查询，或用 [List Conversions](/zh/stablecoin-account/v1.6/api-reference/list-conversions) 对账（按 `order_status`、`order_id` 或 `balance_currency` 过滤）。已完成的兑换带有 `settle_time`。

<h2 id="related">
  相关页面
</h2>

* [Create Quote API](/zh/stablecoin-account/v1.6/api-reference/create-quote)
* [Create Conversion API](/zh/stablecoin-account/v1.6/api-reference/create-conversion)
* [换汇 webhook](/zh/stablecoin-account/v1.6/webhooks/conversion)
* [管理资产余额](/zh/stablecoin-account/v1.6/guide/manage-asset-balances) —— 兑换在流水中显示为 `Sell` / `Buy` / `Swap`