> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablepayfi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 稳定币兑换

> 了解法币与稳定币兑换、汇率与报价、费用、到账状态及事件通知。

把资金从一种资产换成另一种资产：法币换稳定币、稳定币换法币、稳定币互换。

稳定币兑换负责把资金从一种资产搬到另一种资产。它包含三类操作：法币兑换稳定币、稳定币兑换法币、稳定币互换（含跨链）。每一笔兑换都按锁定的汇率与费用折算，兑换结果默认进入商户对应的稳定币账户，也可以在指定收款人的情况下直接打款出去，不必先在商户账户里落地。

兑换与全球账户是同一套账本的两面：全球账户管理「钱放在哪个币种账户」，兑换负责「把余额在币种之间搬动」。转出账户、入账账户与收款人都在全球账户中维护，本文档只描述汇率、报价与兑换本身。

## 适用场景

* 客户以法币汇款入账后，按需换成 USDT、USDC 用于收款结算或对外付款。

* 把稳定币换成本地法币，并直接打款到供应商或个人的银行账户。

* 在不同链之间搬移稳定币，例如把 Solana 上的 USDC 换成 TRON 上的 USDT。

* 需要先向客户展示价格，再在实际执行时沿用同一个汇率。

## 核心概念

汇率。汇率接口返回当前中间市场价，以十进制字符串表示，例如 0.9998。汇率不区分区块链网络，同一个交易对在各链上使用同一价格。

报价（Quote）。报价把汇率与费用一起锁定一段时间，是单次使用的凭据：被一笔转账引用后即用尽，超过有效期未使用会自动过期。需要先给客户报价、或整个流程跨越较长时间时使用报价；只是即时执行一笔兑换，可以跳过报价，在转账请求里直接锁汇。

转账（Transfer）。一次兑换的执行记录。三类兑换统一通过创建转账接口提交，由 `transfer_type` 区分，并共用同一套状态机。

## 三种汇率方式

执行兑换时，汇率有三种指定方式，每次只能选一种。

| 方式 | 说明 | 目标金额 |
| :- | :- | :- |
| fixed | 请求时锁汇，平台自动创建报价并在转账记录中回传报价 ID | 确定 |
| `quote_id` | 引用一条可用报价，汇率与费用以报价为准，不再二次询价 | 确定 |
| floating | 按处理时的市场汇率执行 | 估算值 |

## 三类兑换

法币兑换稳定币。按法币充值记录整笔兑换：一条充值记录只能兑换一次，且必须一次兑完全部金额，请求金额要与记录金额一致。可以指定目标币种与网络，兑换结果默认进入该稳定币的主账户，也可以指定入账账户，或直接打给稳定币地址收款人。

稳定币兑换法币。换汇与银行打款一步完成：兑换后的法币直接打给收款人的银行账户，不在商户账户中间落地。因此必须指定法币银行的收款人，且收款人币种要与目标币种一致。

稳定币互换。支持同链与跨链：指定卖出币种与网络、买入币种与网络；可选把兑换结果直接打给稳定币地址收款人，不指定则进入商户账户。

## 法币充值

法币兑换稳定币的资金来源是法币充值记录。收款详情接口返回本地清算账户信息与归因码，付款方在汇款附言中填写归因码，资金到账后自动归因到商户并生成一条充值记录。兑换前可以先查可用于兑换的法币充值余额，它是尚未兑换的充值记录金额之和，按币种汇总。

## 费用、到账与状态

费用以源币种计收，报价与转账记录都会给出费用金额与费用币种。转账记录中的卖出金额不含费用，实际借记为卖出金额加费用；使用 floating 时目标金额是估算值，最终以执行结果为准。网络费由平台承担。

三类转账共用一条状态链：processing（处理中）→ `payment_submitted`（资金链路已发出）→ completed（完成）。终态还包括 `funds_refunded`（退回）与 `bounced_back`（拒收退回），原因写在失败原因字段中。

## 事件与通知

与兑换相关的事件包括法币充值入账、报价生命周期与转账生命周期。事件由 StablePay 推送到商户配置的 Webhook 地址；同一事件可能重复送达，需要按事件 ID 幂等去重，并以转账与报价查询核对最终状态。

处理建议：转账类事件只表示状态变化，金额与最终状态以 `GET /transfer/{transfer_id}` 为准；收到 transfer.completed 前不要对外宣称到账，收到 `funds_refunded` 或 `bounced_back` 后按失败原因调整业务侧状态。报价类事件用于清理已过期或已用的报价，避免重复引用。

## 与其他产品的关系

收银台、二维码支付与收款链接负责把钱收进来，兑换负责把余额在币种之间搬动，全球账户负责余额的记账与查询。对外打款可以走全球账户的提现能力，也可以走 Payouts 产品，两者都不改变本文档描述的汇率与报价规则。

## 常见问题

| 问题 | 说明 |
| :- | :- |
| 报价可以重复使用吗？ | 不可以。报价是单次凭据，被一笔转账引用后即用尽；已用或已过期再次引用会返回 409。 |
| floating 的金额什么时候确定？ | 执行时确定，响应中的目标金额是估算值；需要确定金额请使用 fixed 或报价。 |
| 一条法币充值可以分批兑换吗？ | 不可以。一条充值记录只能兑换一次，且必须整笔兑换。 |
| 稳定币兑换法币的资金会进入商户账户吗？ | 不会。换汇与银行打款一步完成，资金直接打给指定的收款人。 |
| 跨链互换的网络费由谁承担？ | 由平台承担，商户侧只体现为兑换手续费。 |
| 汇率接口返回的价格能直接成交吗？ | 不能。汇率接口只用于展示参考价，要锁定汇率请创建报价或在转账中锁汇。 |

## 相关页面

* [全球账户产品文档](https://docs.stablepayfi.ai/zh/product/Global-Accounts.md)
* [全球账户 API 文档](https://docs.stablepayfi.ai/zh/api/global-accounts/overview)
* [稳定币兑换产品文档](https://docs.stablepayfi.ai/zh/product/Stablecoin-Exchange.md)
* [稳定币兑换 API 文档](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/overview)
* [集成前准备](https://docs.stablepayfi.ai/zh/api/getting-started.md)
* [Webhook 通知](https://docs.stablepayfi.ai/zh/api/webhook-notifications.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.