Convert API

Met de Convert API kunt u wisselen tussen de valuta's in uw handelssaldo tegen de huidige marktprijs — dezelfde engine die het tabblad Swap in het handelsdashboard aandrijft, nu aan te roepen vanuit uw backend.

Conversieprijs opvragen

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

Conversie uitvoeren

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

Fouten

Bij een fout heeft de respons state: 1 en een error_code — gedeeld door /v1/convert/price en /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 conversie van inkomende betalingen

Automatisch converteren is een projectinstelling voor inkomende facturen en statische portemonnee-credits. Het wordt geconfigureerd in het merchant dashboard, niet door velden toe te voegen aan /v1/payment. Elke regel selecteert één of meer bronvaluta's en een doelvaluta.

Wanneer de conversie is voltooid, kunnen betalingsinformatie en merchant webhooks het volgende bevatten:

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

De bedrag-domeinen zijn opzettelijk gescheiden:

• payment_amount — wat op de blockchain is gedetecteerd in de bronbetalingsvaluta;
• merchant_amount — het netto-bronbedrag dat aan de merchant kan worden toegeschreven vóór conversie;
• convert.amount — het bedrag dat is bijgeschreven in convert.to_currency;
• convert.rate en convert.commission — het uitgevoerde conversieresultaat, niet een prijs die u lokaal zou moeten herberekenen.

Automatische conversiefout en terugval

Conversie vindt plaats na het ontvangen van de blockchain-betaling. Marktbeschikbaarheid, minimale ordergroottes, precisielimieten, time-outs bij beurzen en onvoldoende uitvoerbare liquiditeit kunnen conversie vertragen of verhinderen.

• Stortingen onder de globale/projectminimum worden omzeild in de conversiepijplijn en worden in de bronvaluta bijgeschreven.
• Tijdelijke fouten kunnen asynchroon opnieuw worden geprobeerd.
• Grote of niet verhandelbare stortingen kunnen terugvallen op een bronvalutakrediet nadat het herproefbeleid is uitgeput.
• Een betaling kan daarom geldig zijn, zelfs wanneer de gewenste conversie naar de doelvaluta niet heeft plaatsgevonden.

Uw integratie moet eerst de geverifieerde betaling opslaan en vervolgens de daadwerkelijk bijgeschreven valuta reconciliëren aan de hand van betalingsinformatie, het optionele convert-blok en de saldi van de handelaar. Blokkeer de bevestiging van de betalingswebhook niet terwijl u wacht op uw eigen analyse- of notificatiesystemen.

Automatische conversie acceptatietests

Test ten minste: succesvolle directe conversie, brug/multi-hop conversie, stof onder minimum, tijdelijke retry, terugval naar bronvaluta, onderbetaling, overbetaling, dubbele webhook, ontbrekende convert, en reconciliatie na een ambigu timeout.

Handmatige conversie edge cases

• /v1/convert/price is een indicatieve preview; marktbeweging kan het uitvoeringsresultaat veranderen.
• amount_type: from corrigeert het verzoek aan de bronzijde, terwijl amount_type: to een bedrag aan de doelzijde aanvraagt. Verwissel de betekenis niet bij het tonen van de bevestigings-UI.
• Een paar zonder directe markt kan via een tussenliggende valuta worden geleid. Als slechts één been voltooid is, rapporteert partially_completed de tussenliggende credit.
• Als een execute-aanroep time-out, reconcileer dan voordat u het opnieuw probeert. Een marktorder kan worden uitgevoerd, zelfs wanneer de HTTP-respons ervan verloren gaat.
• Behandel failed als een toestand om te reconciliëren, niet als toestemming om een lokale compenserende balansboeking toe te passen; het platform is eigenaar van debet/vergoedingsboekhouding.