Fiatside
fr

Developers

API 文档

一个返回与网站相同费用明细的API，逐行列出，无隐藏加价。本页描述所有端点共用的约定，并明确说明当前开放的内容。

当前开放的内容

1端点实际暴露并可调用：报价。其他5端点作为合约发布，因此您可以在它们开放前进行构建，且每个端点都带有明确的徽章。

我们提前编写文档是因为这有助于集成。让您误以为它已连接则不然：每个端点都标明其状态，开放端点的示例响应是实际获取的响应，而非模拟。

01

基础URL和版本管理

两个基础并存：一个响应当前请求，另一个是随已签发密钥推出的带版本API。

当前
/api Live
带版本API
/api/v1 Published contract, not open

版本位于路径中，而非标头中：URL必须能在粘贴到工单后仍然有效。破坏性变更——移除字段、更改类型、不同语义——会开启新版本；旧版本至少继续服务六个月，其结束日期在变更日志中公布。添加字段不属于破坏性变更：您的客户端必须忽略其不认识的字段。

02

约定

这些约定适用于每个端点，无论开放还是即将推出。其中大多数存在的原因只有一个：绝不在传输中损失一分钱。

金额为字符串或最小单位整数

绝不用浮点数。在JSON中，0.1 + 0.2不等于0.3，且大金额在序列化时会丢失最小单位。因此，主单位金额以字符串形式发送，内部金额以最小单位整数及其小数位数形式发送。

{
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2
}

小数位数取决于货币

欧元有两位小数，西非法郎和越南盾没有小数。不要硬编码“× 100”：请读取currencyDecimals，或参考数据中的decimals字段。

{ "amount": "125000", "currency": "XOF", "currencyDecimals": 0 }

加密货币金额以基础单位表示

存款返回时带有其小数位数：比特币为8，USDT为6，以太币为18。同一代码可能因网络不同而有不同的小数位数：请相信字段，而非您的记忆。

{ "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 } }

时间戳

日期为ISO 8601 UTC格式。一个刻意的例外：rateAsOf是毫秒级的Unix时间戳，因为它用于年龄计算，而非显示。它携带市场数据（而非您的请求）的日期：这一区别使得过时价格可被检测。

{ "rateAsOf": 1788356981608, "rateSource": "coingecko" }

标识符稳定

资产、通道或国家标识符永不更改，也永不被重新分配。已关闭的通道保留其标识符，并附有阶段和原因：您的集成可以看到它为何从您的选项中消失，而不是发现一个空洞。

面向用户的消息为双语

拒绝原因在同一对象中以法语和英语返回。您显示与您的用户匹配的那个，无需在您这边维护翻译表。

{ "reason": { "fr": "…", "en": "…" } }
03

首次调用

报价无需密钥。此调用可直接使用。

请求bash
curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "sepa_instant",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'
响应——真实示例json
{
  "deposit": { "amount": "1000.000000", "ticker": "USDT", "decimals": 6 },
  "gross": "921.68",
  "net": "912.28",
  "currency": "EUR",
  "currencyDecimals": 2,
  "midRate": "0.92168430",
  "effectiveRate": "0.91228000",
  "totalCostBps": 102,
  "lines": [
    { "code": "network", "amount": "1.11", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "8.29", "basis": "0.90 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 1, "p95Minutes": 12 },
  "lockSeconds": 1800,
  "rateAsOf": 1788356981608,
  "rateSource": "mock",
  "limitError": null
}

rateSource字段说明价格来源。值“mock”是确定性开发源，无法在生产环境中启动：进程拒绝启动，而非报价冻结价格。

04

章节

05

API不会做什么

API的限制与其功能同样值得了解。

  • 不支持第三方支付。收款人姓名必须与订单持有人的已验证身份匹配，支付通道现在会核对姓名与账户。
  • 不支持通过API创建账户或进行身份验证。这些步骤在用户看到其接受内容的流程中完成。
  • URL参数中不带密钥。URL最终会出现在日志、引用标头和历史记录中：以这种方式传递的密钥是需要撤销的密钥。
  • 我方不缓存报价。响应带有Cache-Control: no-store，您的集成不应绕过它：缓存的报价是过时价格被当作实价呈现。
  • 无加密货币购买端点。服务单向运行，从数字资产到法定货币。