适用场景
- 客户以法币汇款入账后，按需换成 USDT、USDC 用于收款结算或对外付款。
- 把稳定币换成本地法币，并直接打款到供应商或个人的银行账户。
- 在不同链之间搬移稳定币，例如把 Solana 上的 USDC 换成 TRON 上的 USDT。
- 需要先向客户展示价格，再在实际执行时沿用同一个汇率。
核心概念
汇率。汇率接口返回当前中间市场价，以十进制字符串表示，例如 0.9998。汇率不区分区块链网络，同一个交易对在各链上使用同一价格。 报价（Quote）。报价把汇率与费用一起锁定一段时间，是单次使用的凭据：被一笔转账引用后即用尽，超过有效期未使用会自动过期。需要先给客户报价、或整个流程跨越较长时间时使用报价；只是即时执行一笔兑换，可以跳过报价，在转账请求里直接锁汇。 转账（Transfer）。一次兑换的执行记录。三类兑换统一通过创建转账接口提交，由transfer_type 区分，并共用同一套状态机。
三种汇率方式
执行兑换时，汇率有三种指定方式，每次只能选一种。三类兑换
法币兑换稳定币。按法币充值记录整笔兑换：一条充值记录只能兑换一次，且必须一次兑完全部金额，请求金额要与记录金额一致。可以指定目标币种与网络，兑换结果默认进入该稳定币的主账户，也可以指定入账账户，或直接打给稳定币地址收款人。 稳定币兑换法币。换汇与银行打款一步完成：兑换后的法币直接打给收款人的银行账户，不在商户账户中间落地。因此必须指定法币银行的收款人，且收款人币种要与目标币种一致。 稳定币互换。支持同链与跨链：指定卖出币种与网络、买入币种与网络；可选把兑换结果直接打给稳定币地址收款人，不指定则进入商户账户。法币充值
法币兑换稳定币的资金来源是法币充值记录。收款详情接口返回本地清算账户信息与归因码，付款方在汇款附言中填写归因码，资金到账后自动归因到商户并生成一条充值记录。兑换前可以先查可用于兑换的法币充值余额，它是尚未兑换的充值记录金额之和，按币种汇总。费用、到账与状态
费用以源币种计收，报价与转账记录都会给出费用金额与费用币种。转账记录中的卖出金额不含费用，实际借记为卖出金额加费用；使用 floating 时目标金额是估算值，最终以执行结果为准。网络费由平台承担。 三类转账共用一条状态链：processing（处理中）→payment_submitted（资金链路已发出）→ completed（完成）。终态还包括 funds_refunded（退回）与 bounced_back（拒收退回），原因写在失败原因字段中。
事件与通知
与兑换相关的事件包括法币充值入账、报价生命周期与转账生命周期。事件由 StablePay 推送到商户配置的 Webhook 地址；同一事件可能重复送达，需要按事件 ID 幂等去重，并以转账与报价查询核对最终状态。 处理建议：转账类事件只表示状态变化，金额与最终状态以GET /transfer/{transfer_id} 为准；收到 transfer.completed 前不要对外宣称到账，收到 funds_refunded 或 bounced_back 后按失败原因调整业务侧状态。报价类事件用于清理已过期或已用的报价，避免重复引用。