Fiatside
fr

Developers

报价操作

报价是当前唯一开放的端点，也是最重要的端点：它返回网站显示的逐行明细。它不需要密钥。

POST/api/quoteLive

报价操作

返回一次出售的完整明细：所使用的中间市场汇率、每项费用单独一行、净金额以及实际获得的实际汇率。各行之和恰好等于毛额与净额之间的差额——在响应离开前会检查该不变性，绝不会返回不平衡的响应。

身份验证： 今日无。报价端点开放：报价不透露个人数据。

参数

参数
字段类型描述
assetId必需string存入资产的标识符，例如“btc”、“usdt”、“sol”。
railId必需string支付方式的标识符，例如“sepa_instant”、“br_pix”、“ke_mpesa”。
networkIdstring存入网络。可选：默认使用该资产的第一个网络。不同网络的费用差异很大，因此此字段会改变净金额。
direction必需"sell" | "receive"输入方向。“sell”：金额是您存入的金额。“receive”：金额是您希望收到的金额，所需存入金额通过二分搜索确定。
amount必需string以主要单位表示的金额，以字符串形式发送。JSON浮点数在大额时会丢失小数单位：字符串是客户端和服务器在分币上达成一致的唯一格式。
请求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
}
  • 响应带有Cache-Control: no-store。缓存的报价是作为确定报价提供的过时价格。
  • 通道限额超出不是HTTP错误：报价会返回一个limitError对象，携带below_min或above_max代码以及确切限额，因此您的界面无需第二次调用即可显示正确的消息。
  • rateSource说明价格来源。值“mock”是确定性开发源：它无法在生产环境中启动，在生产环境中进程拒绝启动而不是报价冻结价格。

可能的错误： invalid_request, unknown_asset_or_rail, rail_not_open, asset_not_offered, invalid_amount, rate_stale, rate_unavailable, quote_failed. 完整目录

01

阅读明细

lines数组包含每个真实费用的一项。零行不返回：显示“通道费：0.00”毫无意义，只会使界面杂乱。

阅读明细
code接收方内容
network区块链网络资产转移成本，在转换前从存款中按实物扣除。它随所选网络而变化，有时差异很大：这就是networkId改变净额的原因。
spread我们我们的利润，以转换金额的百分比表示。这是唯一属于我们收入的条目。
rail支付机构支付方式费用，固定、按比例或两者兼有。当通道不收费时（大多数开放通道如此），此条目不存在。
fx外汇当发生额外转换时，为明确的兑换点差保留的条目。在通道货币即报价货币的通道上，此条目不出现。

使表格可核查的不变式

毛额减去各行之和恰好等于净额，精确到最小货币单位。每次报价在响应发出前都会检查此等式；若不平衡，则存在未申报的利润，引擎会报错而非返回。您可以重新计算：这正是目的。

02

一个包含通道费用的示例

将相同金额发送到收取发送费用的通道，会引出第三行。真实响应，来自确定性开发源。

请求bash
curl -sS -X POST https://fiatside.com/api/quote \
  -H 'Content-Type: application/json' \
  -d '{
    "assetId": "usdt",
    "railId": "ke_mpesa",
    "networkId": "tron",
    "direction": "sell",
    "amount": "1000"
  }'
响应——真实示例json
{
  "gross": "129525.90",
  "net": "128141.44",
  "currency": "KES",
  "totalCostBps": 107,
  "lines": [
    { "code": "network", "amount": "155.44", "basis": "Cout reseau tron, preleve en USDT" },
    { "code": "spread",  "amount": "582.17", "basis": "0.45 % du montant converti" },
    { "code": "rail",    "amount": "646.85", "basis": "0.50 % du montant converti" }
  ],
  "settlement": { "p50Minutes": 2, "p95Minutes": 45 },
  "limitError": null
}

三行，三个不同的接收方：网络、我们、支付机构。totalCostBps 字段给出了与中间市场汇率的总偏差（以基点计）——这是服务之间唯一值得比较的数字，因为它涵盖了一切，包括原本可能隐藏在汇率中的部分。

03

通道限额

超出通道范围的金额不会产生 HTTP 错误：报价会被返回，并带有一个 limitError 对象。因此，您的界面可以同时显示金额和确切原因，无需第二次调用。

响应摘录——真实示例json
{
  "net": "3.47",
  "currency": "EUR",
  "limitError": { "code": "below_min", "limit": "20.00" }
}

可能的值是 below_min 和 above_max，limit 保存以通道货币主单位表示的界限。注意：该界限适用于净额，而非存入金额——受益人收到的金额必须符合通道限额。

04

有效期窗口

lockSeconds 字段说明订单创建后汇率将被冻结多长时间。这取决于资产：稳定币较长，波动性资产较短。

  • 报价本身并非确定：在订单创建之前仅为指示性。汇率在订单创建时锁定，而非在报价调用时锁定。
  • 该窗口涵盖您的决策时间，而非网络确认时间。比特币存款可能需要一小时的确认：锁定保护您在决策和存款期间免受市场波动影响。
  • 如果存款在到期后到达，订单将重新报价，新金额必须被接受。静默地重新定价在结构上是不可能的。
  • 不要缓存报价来掩盖过期汇率错误。缓存的报价是以确定价格呈现的过期价格，这正是拒绝代码所防止的问题。