https://api.stablepay.co · 前缀：/api/v1 · HTTPS / JSON / UTF-8
概述与能力范围
稳定币兑换 API 负责汇率与报价、法币充值（兑换的资金来源）以及三类换汇转账：法币兑换稳定币、稳定币兑换法币、稳定币互换（含跨链），并通过 Webhook 推送对应的事件。所有接口以 /api/v1 为前缀，商户身份由凭证确定：商户 App 不需要传merchant_id，服务商 App 通过 merchant_id 指定作用商户。
金额统一使用账本最小单位整数，法币与 USDT、USDC 均为 2 位小数；汇率为十进制字符串。转账用到的收款人、转出与入账账户属于全球账户能力。
认证与签名
所有请求携带 API Key 与签名三件套，规则与 StablePay 公共认证规范一致。
签名串为
{timestamp}.{nonce}.{requestBody}。GET 与 DELETE 没有请求体，{requestBody} 取空字符串，签名串以点号结尾；POST 与 PUT 使用实际发送的原始 JSON 字符串，计算签名后不要再重排字段或格式化。完整算法与多语言示例见 集成前准备。
凭证属于 App：商户 App 对应单一商户，请求不带 merchant_id；服务商 App 经商户授权后可服务多个商户，可在报价、法币充值、转账与收款人接口的 Query 或 Body 中传 merchant_id 指定作用商户。未授权或无权访问目标商户时返回 403 permission_denied。签名密钥只保存在服务端，重试时必须重新生成 timestamp 与 nonce。
数据约定
列表类接口统一采用游标分页：limit 默认 20、最大 100，响应返回
next_cursor，最后一页不返回该字段。账户查询类接口例外：账户列表一次返回全部账户，不支持分页与筛选。
创建类接口支持两种幂等方式：请求头 Idempotency-Key，以及请求体中的 external_xxx_id（与 merchant_id 共同构成幂等键，同一商户内唯一）。相同 Key 携带不同参数时返回 409 idempotency_conflict；网络超时重试请沿用同一幂等标识。
事件
事件记录商户名下资源的状态变化，由 StablePay 以 Webhook 推送到商户配置的地址。事件查询接口暂不对外提供，商户侧以推送内容与对账查询为准。事件类型
推送请求头携带
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。
错误响应示例
error.type 取值：
api_error、invalid_request_error、authentication_error、permission_error、resource_not_found、conflict、rate_limit_error。param 仅在能定位到具体参数时返回。重试时务必重新生成 timestamp 与 nonce；401 不要盲目重试。
按错误码处理
换汇属于资金操作，重试时务必沿用同一幂等标识，并在重试前先查询转账状态，避免重复兑换。
版本与变更记录
接口边界
- 账户开立、账户重命名与商户管理在商户后台完成，不通过本 API。
- 本 API 只返回当前商户自己的账户与交易数据，跨商户查询不可用。
- 跨商户转账与平台账户收款由 Payouts 产品提供。
- 汇率接口只返回当前中间市场汇率，不构成成交承诺。
- 商户 KYB / KYC 资料提交与审核状态查询不通过本 API。