Convert API

La Convert API vous permet d'échanger entre les devises détenues dans le solde de votre commerce au prix de marché actuel — le même moteur qui alimente l'onglet Swap du tableau de bord commerçant, désormais accessible depuis votre backend.

Obtenir une cotation de conversion

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

Exécuter une conversion

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

Erreurs

En cas d'échec, la réponse a state: 1 et un error_code — commun à /v1/convert/price et /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."
  }
}

Conversion automatique des paiements entrants

La conversion automatique est un paramètre de projet pour les factures entrantes et les crédits de portefeuille statique. Il est configuré dans le tableau de bord du commerçant, et non pas en ajoutant des champs à /v1/payment. Chaque règle sélectionne une ou plusieurs devises sources et une devise cible.

Une fois la conversion terminée, les informations de paiement et les webhooks du commerçant peuvent inclure :

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

Les domaines des montants sont intentionnellement séparés :

• payment_amount — ce qui a été détecté sur la blockchain dans la devise de paiement source ;
• merchant_amount — le montant net source attribuable au commerçant avant conversion ;
• convert.amount — le montant crédité dans convert.to_currency ;
• convert.rate et convert.commission — le résultat de conversion exécuté, pas un prix que vous devriez recalculer localement.

Échec de la conversion automatique et retour en

La conversion est en aval de la réception du paiement blockchain. La disponibilité sur le marché, les tailles minimales de commande, les limites de précision, les délais d'échange et la liquidité exécutable insuffisante peuvent retarder ou empêcher la conversion.

• Les dépôts inférieurs au minimum global/projet contournent le pipeline de conversion et créditent la devise source.
• Les échecs transitoires peuvent être réessayés de manière asynchrone.
• Les dépôts importants ou non négociables peuvent revenir à un crédit en devise source après épuisement de la politique de réessai.
• Un paiement peut donc être valide même lorsque la conversion en devise cible souhaitée n'a pas eu lieu.

Votre intégration doit d'abord enregistrer le paiement vérifié, puis rapprocher la devise réellement créditée à partir des informations de paiement, du bloc optionnel convert et des soldes marchands. Ne bloquez pas la confirmation du webhook de paiement en attendant vos propres systèmes d'analyse ou de notification.

Tests d'acceptation de conversion automatique

Testez au moins : conversion directe réussie, conversion via un pont/multi-saut, poussière sous le minimum, nouvelle tentative transitoire, retour à la monnaie source, sous-paiement, trop-payé, webhook en double, convert manquant, et réconciliation après un timeout ambigu.

Cas limites de conversion manuelle

• /v1/convert/price est un aperçu indicatif ; le mouvement du marché peut changer le résultat de l'exécution.
• amount_type: from corrige la demande côté source, tandis que amount_type: to demande un montant côté cible. Ne changez pas le sens lors de la présentation de l'interface de confirmation.
• Une paire sans marché direct peut être acheminée via une devise intermédiaire. Si une seule étape se termine, partially_completed rapporte le crédit intermédiaire.
• Si un appel d'exécution expire, réconciliez avant de réessayer. Un ordre au marché peut s'exécuter même lorsque sa réponse HTTP est perdue.
• Traitez failed comme un état à réconcilier, et non comme une permission d'appliquer une écriture locale de solde compensatoire ; la plateforme possède la comptabilité des débits/remboursements.