Convert API

Convert API 允许您按当前市场价格在商户余额持有的各币种之间进行兑换 — 与商户后台「兑换」标签页背后使用的是同一套引擎，现在可以从您的后端直接调用。

获取兑换报价

{
  "state": 0,
  "result": {
    "success": true,
    "from_currency": "BTC",
    "to_currency": "USDT",
    "amount_type": "from",
    "from_amount": "0.01000000",
    "to_amount": "947.86690000",
    "effective_rate": "94786.69000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87"
  }
}

curl -X POST https://api.2328.io/api/v1/convert/price \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

执行兑换

{
  "state": 0,
  "result": {
    "id": 12345,
    "type": "manual",
    "status": "completed",
    "from_currency": "BTC",
    "to_currency": "USDT",
    "from_amount": "0.01000000",
    "requested_from_amount": "0.01000000",
    "refund_amount": null,
    "to_amount": "947.86690000",
    "exchange_rate": "94786.69000000",
    "fee_amount": "0.00000000",
    "from_amount_usd": "947.87",
    "to_amount_usd": "947.87",
    "processed_at": "2026-01-20T15:30:24Z",
    "created_at": "2026-01-20T15:30:22Z"
  }
}

curl -X POST https://api.2328.io/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

错误

失败时响应中 state 为 1，并包含 error_code —— /v1/convert/price 与 /v1/convert 共用：

🔴 422 / 400 · application/json

{
  "state": 1,
  "error_code": "amount_too_small",
  "errors": {
    "amount": "Amount is too small for this conversion. Please increase the amount and try again."
  }
}

收款自动转换

Auto-convert 是传入 invoice 和静态钱包积分的项目设置。它是在 merchant 仪表板中配置的，而不是通过向 /v1/payment 添加字段来配置的。每个规则选择一种或多种源货币和目标货币。

转换完成后，付款信息和 merchant webhooks 可以包括：

{
  "payment_amount": "0.14800000",
  "merchant_amount": "0.146520000000000000",
  "payer_currency": "XMR",
  "convert": {
    "to_currency": "USDT",
    "commission": "0.09000000",
    "rate": "323.21000000",
    "amount": "47.262015740000000000"
  }
}

金额域有意分开：

• payment_amount — 在源支付货币中在链上检测到的内容；
• merchant_amount — 换算前归属于 merchant 的净来源金额；
• convert.amount — convert.to_currency 中贷记的金额；
• convert.rate 和 convert.commission — 执行的转换结果，而不是您应该在本地重新计算的价格。

Auto-convert 故障和 fallback

转换是接收区块链付款的下游。市场可用性、最小订单规模、精度限制、交易超时和可执行流动性不足可能会延迟或阻止转换。

• 低于全球/项目最低限额的存款绕过转换管道并记入源货币。
• 瞬时失败可以异步重试。
• 在 retry 政策用尽后，大额或不可交易的存款可以回落至源货币信用。
• 因此，即使未发生所需的目标货币转换，付款也可能有效。

您的集成应首先保留已验证的付款，然后根据付款信息、可选的 convert 块和 merchant 余额协调实际记入的货币。在等待您自己的分析或通知系统时，请勿阻止付款 webhook 的确认。

Auto-convert 验收测试

至少测试：成功的直接转换、桥接/多跳转换、dust 低于最小值、瞬时 retry、fallback 到源货币、支付不足、支付过多、重复 webhook、缺失 convert 以及reconciliation 在模棱两可的 timeout 之后。

手动转换边箱

• /v1/convert/price 是指示性预览；市场变动可以改变执行结果。
• amount_type: from 修复源端请求，而 amount_type: to 请求目标端金额。呈现确认 UI 时请勿交换含义。
• 没有直接市场的货币对可以通过中间货币进行路由。如果仅完成一条腿，则 partially_completed 报告中间信用。
• 如果执行调用超时，请在重试之前进行协调。即使 HTTP 响应丢失，市价订单也可以执行。
• 将 failed 视为要调节的状态，而不是允许应用本地补偿余额条目；该平台拥有借记/退款会计。