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."
  }
}

受信支払いの自動変換

自動変換は、受信請求書およびスタティックウォレットクレジットのためのプロジェクト設定です。これは /v1/payment にフィールドを追加することで設定するのではなく、マーチャントダッシュボードで設定されます。各ルールは、1つ以上のソース通貨と1つのターゲット通貨を選択します。

変換が完了すると、支払い情報およびマーチャントのWebhookには以下の情報が含まれる場合があります：

{
  "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 — 変換前にマーチャントに帰属する純ソース金額;
• convert.amount — convert.to_currency にクレジットされた金額;
• convert.rate と convert.commission — 実行された換算結果であり、ローカルで再計算すべき価格ではありません。

自動換算失敗およびフォールバック

換算はブロックチェーン支払いの受領の下流で行われます。市場の可用性、最小注文サイズ、精度の制限、取引所のタイムアウト、実行可能な流動性の不足が、換算を遅延または妨げることがあります。

• グローバル／プロジェクトの最小値未満の入金は換算パイプラインをバイパスし、ソース通貨をクレジットします。
• 一時的な失敗は非同期でリトライすることができます。
• 大きなまたは取引不可能な預金は、リトライポリシーが尽きた後、元の通貨でのクレジットに戻ることがあります。
• したがって、目的の通貨換算が行われなかった場合でも、支払いは有効であり得ます。

統合ではまず検証済みの支払いを永続化し、その後、支払い情報、任意のconvertブロック、ならびに加盟店残高から実際にクレジットされた通貨を照合する必要があります。自身の分析や通知システムを待っている間に、支払いウェブフックの確認をブロックしてはいけません。

自動変換受入テスト

少なくとも次の項目をテストしてください：成功した直接変換、ブリッジ／マルチホップ変換、最小値以下のダスト、一時的な再試行、ソース通貨へのフォールバック、支払い不足、過剰支払い、重複ウェブフック、convertの欠落、および曖昧なタイムアウト後の照合。

手動変換のエッジケース

• /v1/convert/priceは参考用のプレビューです。市場の動きにより実行結果が変わる可能性があります。
• amount_type: fromはソース側のリクエストを修正し、amount_type: toはターゲット側の金額をリクエストします。確認UIを表示する際に意味を入れ替えないでください。
• 直接取引のない通貨ペアは、仲介通貨を経由してルーティングできます。一方の取引だけが完了した場合、partially_completedは中間クレジットを報告します。
• 実行呼び出しがタイムアウトした場合は、再試行する前に調整してください。HTTPレスポンスが失われても、成行注文は実行される可能性があります。
• failedはローカルの補償残高エントリを適用する権限としてではなく、調整すべき状態として扱ってください。プラットフォームが借方/返金の会計を管理します。