Convert API

Mit der Convert API können Sie Währungen innerhalb Ihres Händlerguthabens zum aktuellen Marktpreis tauschen — dieselbe Engine, die den Swap-Tab im Händler-Dashboard antreibt, jetzt aus Ihrem Backend aufrufbar.

Konvertierungspreis abrufen

{
  "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"

Konvertierung ausführen

{
  "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"

Fehler

Bei einem Fehlschlag hat die Antwort state: 1 und einen error_code — gemeinsam für /v1/convert/price und /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."
  }
}

Automatische Umrechnung eingehender Zahlungen

Auto-convert ist eine Projekteinstellung für eingehende invoice und statische Wallet-Gutschriften. Sie wird im merchant Dashboard konfiguriert, nicht durch Hinzufügen von Feldern zu /v1/payment. Jede Regel wählt eine oder mehrere Quellwährungen und eine Zielwährung aus.

Nach Abschluss der Umrechnung können Zahlungsinformationen und merchant webhooks Folgendes enthalten:

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

Die Betragsbereiche sind absichtlich getrennt:

• payment_amount — was in der Quellzahlungswährung in der Blockchain erkannt wurde;
• merchant_amount — der Nettoquellbetrag, der der merchant vor der Umrechnung zugeordnet werden kann;
• convert.amount — der Betrag, der in convert.to_currency gutgeschrieben wurde;
• convert.rate und convert.commission — das durchgeführte Umrechnungsergebnis, nicht ein Preis, den Sie lokal neu berechnen sollten.

Fehler bei Auto-convert und fallback

Die Umrechnung erfolgt nach dem Empfang der Blockchain-Zahlung. Marktverfügbarkeit, Mindestbestellmengen, Präzisionsgrenzen, Exchange-Timeouts und unzureichende ausführbare Liquidität können die Umrechnung verzögern oder verhindern.

• Einzahlungen unterhalb des globalen/projektbezogenen Minimums umgehen die Umrechnungspipeline und werden der Quellwährung gutgeschrieben.
• Vorübergehende Fehler können asynchron erneut versucht werden.
• Große oder nicht handelbare Einzahlungen können nach Ausschöpfen der retry-Richtlinie auf eine Gutschrift in Quellwährung zurückfallen.
• Eine Zahlung kann daher gültig sein, selbst wenn die gewünschte Umrechnung in die Zielwährung nicht erfolgt ist.

Ihre Integration sollte zunächst die überprüfte Zahlung speichern und dann die tatsächlich gutgeschriebene Währung aus den Zahlungsinformationen, dem optionalen convert-Block und merchant Salden abstimmen. Blockieren Sie nicht die Bestätigung der Zahlung webhook, während Sie auf Ihre eigenen Analysen oder Benachrichtigungssysteme warten.

Auto-convert Akzeptanztests

Testen Sie mindestens: erfolgreiche direkte Umwandlung, Brücken-/Mehrfach-Umwandlung, dust unter dem Minimum, vorübergehendes retry, fallback in Quellwährung, Unterzahlung, Überzahlung, doppelte webhook, fehlende convert und reconciliation nach einem mehrdeutigen timeout.

Manuelle Umwandlungs-Edge-Cases

• /v1/convert/price ist eine indikative Vorschau; Marktentwicklungen können das Ausführungsergebnis ändern.
• amount_type: from korrigiert die Anforderung auf der Quellseite, während amount_type: to einen Betrag auf der Zielseite anfordert. Tauschen Sie die Bedeutung nicht, wenn die Bestätigungs-Oberfläche angezeigt wird.
• Ein Paar ohne direkten Markt kann über eine Zwischengeldwährung geleitet werden. Wenn nur ein Teil abgeschlossen wird, meldet partially_completed die Zwischenbuchung.
• Wenn ein Ausführungsaufruf ein Timeout hat, führen Sie vor dem erneuten Versuch einen Abgleich durch. Eine Marktorder kann ausgeführt werden, auch wenn ihre HTTP-Antwort verloren geht.
• Behandeln Sie failed als einen Status zur Abstimmung, nicht als Erlaubnis, einen lokalen Ausgleichseintrag vorzunehmen; die Plattform verwaltet die Debit-/Rückerstattungsbuchhaltung.