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

# 稳定币兑换 API

> 稳定币兑换 API：汇率与报价、法币充值、转账换汇，共 10 个接口。

版本：v1.0（2026-09-29） · Base URL：`https://api.stablepay.co` · 前缀：`/api/v1` · HTTPS / JSON / UTF-8

## 概述与能力范围

稳定币兑换 API 负责汇率与报价、法币充值（兑换的资金来源）以及三类换汇转账：法币兑换稳定币、稳定币兑换法币、稳定币互换（含跨链），并通过 Webhook 推送对应的事件。所有接口以 /api/v1 为前缀，商户身份由凭证确定：商户 App 不需要传 `merchant_id`，服务商 App 通过 `merchant_id` 指定作用商户。

| 方法 | 路径 | 用途 |
| :- | :- | :- |
| GET | [`/quote/pairs`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-quote-pairs) | 查询支持的汇率对 |
| GET | [`/quote/exchange_rate`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-quote-exchange-rate) | 查询交易对当前汇率 |
| POST | [`/quote`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/post-quote) | 创建报价并锁定汇率 |
| GET | [`/quote/{quote_id}`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-quote-quote-id) | 查询报价 |
| GET | [`/fiat/account_details`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-fiat-account-details) | 查询法币收款详情与归因码 |
| GET | [`/fiat/deposits`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-fiat-deposits) | 法币充值记录列表 |
| GET | [`/fiat/deposits/{fiat_deposit_id}`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-fiat-deposits-fiat-deposit-id) | 查询单条法币充值记录 |
| GET | [`/fiat/deposit_balance`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-fiat-deposit-balance) | 查询可用于兑换的法币充值余额 |
| POST | [`/transfer`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/post-transfer) | 创建转账（法币兑换稳定币、稳定币兑换法币、稳定币互换） |
| GET | [`/transfer/{transfer_id}`](https://docs.stablepayfi.ai/zh/api/stablecoin-exchange/get-transfer-transfer-id) | 查询转账 |

金额统一使用账本最小单位整数，法币与 USDT、USDC 均为 2 位小数；汇率为十进制字符串。转账用到的收款人、转出与入账账户属于全球账户能力。

## 认证与签名

所有请求携带 API Key 与签名三件套，规则与 StablePay 公共认证规范一致。

| 请求头 | 必填 | 说明 |
| :- | :- | :- |
| Authorization | 是 | Bearer `{api_key}` |
| `X-StablePay-Timestamp` | 是 | Unix 秒，与服务端时间相差不超过 5 分钟 |
| `X-StablePay-Nonce` | 是 | 防重放随机串，16 到 64 个字符，每次请求唯一 |
| `X-StablePay-Signature` | 是 | HMAC-SHA256 签名，小写十六进制 |

签名串为 `{timestamp}.{nonce}.{requestBody}`。GET 与 DELETE 没有请求体，`{requestBody}` 取空字符串，签名串以点号结尾；POST 与 PUT 使用实际发送的原始 JSON 字符串，计算签名后不要再重排字段或格式化。完整算法与多语言示例见 集成前准备。

凭证属于 App：商户 App 对应单一商户，请求不带 `merchant_id`；服务商 App 经商户授权后可服务多个商户，可在报价、法币充值、转账与收款人接口的 Query 或 Body 中传 `merchant_id` 指定作用商户。未授权或无权访问目标商户时返回 403 `permission_denied`。签名密钥只保存在服务端，重试时必须重新生成 timestamp 与 nonce。

## 数据约定

| 项目 | 约定 | 示例 |
| :- | :- | :- |
| 资源 ID | `xxx_id` 一律为 10 位数字字符串：`merchant_id`、`fiat_deposit_id`、`quote_id`、`recipient_id`、`transfer_id`、`event_id`、`request_id` | "9000000070" |
| 账户编号 | `account_no` 为 8 位数字字符串，前导零有含义；所有涉及账户的请求参数与响应字段都使用该编号 | "00000001" |
| 金额 | 整数，为该币种最小单位；法币与 USDT、USDC 统一为 2 位小数 | 1050 表示 10.50 USD；125000 表示 1,250.00 USDC |
| 币种 | 大写；法币为 ISO 4217，稳定币为资产代码 | USD、SGD、USDT、USDC |
| 网络 | ethereum、tron、solana、base、polygon、arbitrum、bsc | solana |
| 时间 | Unix 秒整数 | 1718726400 |
| 比例 | 汇率等比例值为十进制字符串，不使用浮点数 | "0.9998" |
| 空字段 | 不适用的可选字段不返回 | — |

列表类接口统一采用游标分页：limit 默认 20、最大 100，响应返回 `next_cursor`，最后一页不返回该字段。账户查询类接口例外：账户列表一次返回全部账户，不支持分页与筛选。

创建类接口支持两种幂等方式：请求头 `Idempotency-Key`，以及请求体中的 `external_xxx_id`（与 `merchant_id` 共同构成幂等键，同一商户内唯一）。相同 Key 携带不同参数时返回 409 `idempotency_conflict`；网络超时重试请沿用同一幂等标识。

## 事件

事件记录商户名下资源的状态变化，由 StablePay 以 Webhook 推送到商户配置的地址。事件查询接口暂不对外提供，商户侧以推送内容与对账查询为准。

### 事件类型

| 事件 | 说明 |
| :- | :- |
| `fiat_deposit.credited` | 法币充值入账，data 为法币充值记录 |
| quote.created / used / expired | 报价生命周期 |
| transfer.processing / `payment_submitted` / completed / `funds_refunded` / `bounced_back` | 转账生命周期 |

推送请求头携带 `X-StablePay-Event-Type` 与 `X-StablePay-Event-ID`；推送失败自动重试 10 次，指数退避从 2 分钟起、最长间隔 1024 分钟。同一事件可能重复送达，商户侧应以 `X-StablePay-Event-ID` 幂等去重，并以转账与报价查询核对最终状态。

## 错误响应与错误码

错误响应统一信封：error 对象（type、code、message、param）、`request_id` 与 timestamp。排查问题时请提供 `request_id`。

错误响应示例

```json theme={"system"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "The amount must be greater than zero.",
    "param": "amount"
  },
  "request_id": "9000000099",
  "timestamp": 1718726400
}
```

| 状态码 | 错误码 | 说明 |
| :- | :- | :- |
| 400 | `invalid_parameter` | 参数缺失或取值不合法，如金额为 0、币种或网络不支持 |
| 401 | `invalid_api_key` | API Key 缺失、无效或已吊销，或签名校验失败 |
| 403 | `permission_denied` | 商户未授权该 App，或 App 无权访问目标商户 |
| 404 | `resource_not_found` | 资源不存在或不属于目标商户 |
| 409 | conflict | 业务状态冲突：`idempotency_conflict`、`insufficient_funds`、`quote_expired`、`quote_not_open` |
| 429 | `rate_limit_exceeded` | 请求频率超限，退避后重试 |
| 500 | `internal_error` | 平台内部错误，凭 `request_id` 联系排查 |
| 503 | — | 余额查询服务暂时不可用，用新的 timestamp、nonce 与签名重试 |

error.type 取值：`api_error`、`invalid_request_error`、`authentication_error`、`permission_error`、`resource_not_found`、conflict、`rate_limit_error`。param 仅在能定位到具体参数时返回。重试时务必重新生成 timestamp 与 nonce；401 不要盲目重试。

## 按错误码处理

| 错误码 | 是否重试 | 建议处理 |
| :- | :- | :- |
| `invalid_parameter` | 否 | 按 param 定位参数并修正后重新提交；金额为 0、币种或网络不支持都会命中 |
| `invalid_api_key` | 否 | 检查 Key、签名串结尾点号与服务端时间 |
| `permission_denied` | 否 | 服务商 App 检查 `merchant_id` 是否在已授权范围 |
| `resource_not_found` | 否 | 核对报价、充值记录、转账或交易对是否存在并属于该商户 |
| `idempotency_conflict` | 否 | 同一幂等键换了参数：复用原参数或换新键 |
| `insufficient_funds` | 否 | 转出账户可用余额不足，先查 `available_amount` |
| `quote_not_open` / `quote_expired` | 否 | 报价已被使用或已过期：重新创建报价，或改用 `rate_type`=fixed 内联锁汇 |
| `rate_limit_exceeded` | 是 | 退避重试并降低并发 |
| `internal_error` / 503 | 是 | 换新的 timestamp、nonce 与签名后退避重试，持续失败附 `request_id` 排查 |

换汇属于资金操作，重试时务必沿用同一幂等标识，并在重试前先查询转账状态，避免重复兑换。

## 版本与变更记录

| 版本 | 变更 |
| :- | :- |
| 2026-09-29 | 首个公开版本：汇率与报价、法币充值、转账换汇共 10 个接口；事件通过 Webhook 推送，不提供事件查询接口。 |

## 接口边界

* 账户开立、账户重命名与商户管理在商户后台完成，不通过本 API。
* 本 API 只返回当前商户自己的账户与交易数据，跨商户查询不可用。
* 跨商户转账与平台账户收款由 Payouts 产品提供。
* 汇率接口只返回当前中间市场汇率，不构成成交承诺。
* 商户 KYB / KYC 资料提交与审核状态查询不通过本 API。

## 相关文档

* [全球账户产品文档](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.