Tovanix
Tovanix

Documentation API

Documentation d’intégration de l’API ouverte Tovanix, organisée par service : Paiement multichaîne, Location d’énergie, API SMTP, API IA, Carte virtuelle, E-mail, Stockage objet, Vérification et risque des transactions, Accès MCP. Laboratoires : Studio de contrats, Relecture des paiements, Laboratoire de routage IA.

  • Paiement multichaîne
  • Location d’énergie
  • API SMTP
  • API IA
  • Carte virtuelle
  • E-mail
  • Stockage objet
  • Vérification et risque des transactions
  • Accès MCP

USDT / USDC / ETH / TRX / BTC · TRON / EVM / Bitcoin · Double signature HMAC-SHA256 (paiement) + RSA-2048 (versement) · Notification de règlement en 30 secondes

Intégration en 3 étapes

  • 1 Créer un compte et une application Obtenez app_id et app_key dans « Mes applications » de la console, puis configurez notify_url S’inscrire gratuitement →
  • 2 Implémenter l’utilitaire de signature Les paiements utilisent HMAC-SHA256, symétrique, et les versements RSA-2048, asymétrique. Le SDK officiel encapsule les deux avec des exemples complets pour plusieurs langages.
  • 3 Choisir un mode et effectuer la première transaction Un-à-un : adresse associée à un utilisateur, idéale pour les portefeuilles et recharges. Rotation : adresse générée par commande, idéale pour le paiement e-commerce.

Vue d’ensemble

Tovanix prend en charge deux modes de paiement pouvant être activés simultanément :

Mode un-à-un

Les utilisateurs associent une adresse fixe ; toutes les rentrées sont notifiées automatiquement. Idéal pour les recharges et encaissements.

  • L’utilisateur associe une adresse de réception fixe
  • Notifications de rentrées en temps réel
  • Paiements répétés pris en charge
  • Vérification indépendante de signature

Mode rotation

Une adresse de réception est attribuée dynamiquement lors de la création d’une commande et récupérée à l’expiration. Idéal pour les paiements ponctuels.

  • Attribution dynamique d’adresse
  • Gestion de l’expiration des commandes
  • Conversion automatique du taux de change
  • Page de paiement

Algorithme de signature

Les notifications du mode un-à-un utilisent webhook_secret pour la signature, et non app_key.

1. Utilisez HMAC-SHA256 avec le secret comme paramètre de clé HMAC, sans l’ajouter à la chaîne

2. La signature est une chaîne hexadécimale de 64 caractères minuscules ; la comparaison est sensible à la casse

3. À la création d’une commande, formatez amount avec deux décimales, par exemple 100.00, et timeout comme chaîne entière. Même si timeout est omis, signez timeout=0 : le serveur inclut toujours timeout dans la chaîne de signature.

4. Les champs vides sont exclus du calcul de signature

Protection contre les attaques par rejeu

Pour empêcher le rejeu de requêtes interceptées, les requêtes signées peuvent inclure un horodatage et un nonce, tous deux signés. Fermer une commande, associer ou dissocier une adresse les exige et renvoie 400 s’ils manquent ; ils sont facultatifs pour les autres points de terminaison.

/api/v1/pay/close exige timestamp et nonce. /api/v1/pay/bind-address et /api/v1/pay/unbind-address exigent sign_ts et nonce ; l’horodatage accepte aussi le nom timestamp. /api/v1/pay/get-address utilise aussi sign_ts, mais facultativement. La création et consultation de commande et la configuration d’application utilisent timestamp, facultatif : avec horodatage et nonce, le serveur vérifie la fenêtre temporelle et le nonce ; avec un seul ou aucun, seule la signature est vérifiée.

timestamp doit se situer à moins de 300 secondes de l’heure du serveur ; synchronisez vos serveurs avec NTP. Un nonce ne peut être réutilisé pendant 5 minutes. Un horodatage hors fenêtre ou un nonce réutilisé est rejeté : création et consultation de commande renvoient HTTP 400, les autres points 401. Le champ message indique le motif.

Associer une adresse

POST /api/v1/pay/bind-address

Attribue une adresse de paiement fixe à un utilisateur. Renvoie l’adresse existante si elle est déjà associée.

Consulter l’association

POST /api/v1/pay/get-address

Consulte l’adresse de paiement associée à un utilisateur.

Dissocier l’adresse

POST /api/v1/pay/unbind-address

Dissocie l’adresse de paiement d’un utilisateur.

Créer une commande

POST /api/v1/pay/create

Crée une commande de paiement ; le système attribue automatiquement une adresse de réception.

Champs de réponse

amount accepte un nombre ou une chaîne : 100 ou "100". Pour signer, utilisez toujours deux décimales, par exemple "100.00".

Consulter la commande

GET /api/v1/pay/query

Consulte l’état de commande par votre identifiant de commande. Paramètres via la requête URL.

Fermer la commande

POST /api/v1/pay/close

Ferme manuellement une commande impayée ; l’adresse est récupérée. Seules les commandes en attente, status=0, peuvent être fermées.

Consulter la configuration de l’application

GET /api/v1/pay/app-config

Consulte les modes, jetons activés, configurations de notification et autres réglages de l’application, sans exposer de données sensibles.

Notification du mode un-à-un

Lorsqu’une adresse associée reçoit un transfert, le système envoie une requête POST à notify_url configurée.

Les notifications sont signées avec webhook_secret, consultable ou régénérable dans les détails de l’application.

Champs de notification

Retournez HTTP 200 ou {"code": 0} à réception ; sinon, le système réessaie automatiquement jusqu’à 10 fois avec attente exponentielle.

Notification de callback de commande

Après paiement d’une commande en mode rotation, le système envoie un callback à notify_url.

Les notifications de callback sont signées avec webhook_secret, consultable ou réinitialisable dans les détails de l’application.

Champs de callback

Tout statut 2xx vaut livraison ; le corps de la réponse n'est pas examiné (renvoyer {"code": 0} avec un statut non 2xx reste un échec). Un statut non 2xx, aucune réponse sous 10 secondes, une erreur de connexion ou une redirection comptent comme des échecs ; la plateforme réessaie après 30 secondes, 1, 2 et 5 minutes, puis toutes les 10 minutes, jusqu'à 10 fois. Les nouvelles tentatives gardent le même notify_id mais portent un sign_ts, un nonce et une signature neufs : dédupliquez sur notify_id.

Obtenir le taux de change

GET /api/v1/rate

Obtenez le taux de change en temps réel entre deux devises

Convertir le montant

POST /api/v1/convert

Convertissez un montant avec les taux de change en temps réel

Taux de change en lot

GET /api/v1/rates

Consultez les taux de plusieurs devises, codes séparés par des virgules

Tous les taux de change

GET /api/v1/rates/all

Obtenez la liste des taux de toutes les devises prises en charge

Taux de change fiduciaires

GET /api/v1/rates/fiat

Obtenez tous les taux fiduciaires à partir d’une devise donnée, plus de 30 devises regroupées par région

État des commandes

Les commandes passent par les états suivants :

Codes d’erreur

Codes d’erreur unifiés pour l’API de paiement (/api/v1/pay/*) ; ceux de l’API de versement figurent dans la Référence.

Vue d’ensemble des versements / Prérequis

L’API de décaissement permet de sortir les fonds du produit de paiement multichaîne — elle envoie par programmation vers des adresses externes les actifs déjà regroupés dans le portefeuille central. Signature mutuelle RSA-2048 + liste d’IP autorisées + diffusion différée + notifications multicanales permettant l’interception + rappel après confirmation sur la chaîne.

L’API de décaissement utilise uniquement les actifs regroupés dans le portefeuille central en mode de garde par le système. Si votre application utilise le mode de garde autonome — les fonds arrivent directement sur vos propres adresses sans regroupement par la plateforme — aucun solde « regroupé, en attente de décaissement » n’est produit. Les décaissements via cette API sont alors impossibles.

Activation en 4 étapes

  • Ouvrez les paramètres « Paiement multichaîne → Décaissement API » dans la console
  • Générez localement une paire de clés RSA-2048 et téléversez la clé publique sur notre plateforme
  • Ajoutez au moins une IP autorisée (obligatoire) ; configurez éventuellement une liste d’adresses autorisées, une limite par transaction ou un délai de décaissement
  • Activez l’interrupteur principal ; le système génère une paire de clés de plateforme pour le compte. Copiez la clé publique de la plateforme de votre côté pour vérifier les rappels

Signature · RSA-2048 (versement)

Tous les points d’accès /api/v1/withdraw* exigent les en-têtes suivants. Contrairement au HMAC symétrique de l’API de paiement, les décaissements utilisent RSA asymétrique : la plateforme ne conserve que votre clé publique ; le risque est donc une fuite de votre clé privée.

  • X-API-Key — Clé API de la plateforme (disponible dans la console, Outils et paramètres → Gestion des API) ; elle doit disposer de la capacité withdraw
  • X-Timestamp — Horodatage Unix actuel en ms ; l’écart avec l’horloge du serveur doit être ≤ 60 secondes
  • X-Nonce — Nonce à usage unique (uuid) ; ne peut pas être réutilisé dans les 5 minutes
  • X-Withdraw-Signature — RSA-PKCS1v15-SHA256(caller_private_key, signString), Base64

Règle de concaténation de la chaîne à signer

Ici, BODY est le corps HTTP brut (la chaîne JSON telle quelle — sans la sérialiser à nouveau). Pour les requêtes GET, BODY est une chaîne vide.

En plus de la signature RSA et de la liste d’IP du compte décrites ci-dessus, la clé API doit avoir la capacité withdraw et respecter sa propre liste d’IP sources : capacité absente = 403 / 4032, IP hors liste = 403 / 4033. Ces contrôles s’appliquent à /api/v1/withdraw, /api/v1/balance/withdrawable et /api/v1/fee/quote. Les clés antérieures reçoivent withdraw automatiquement ; pour les nouvelles, sélectionnez-la dans Outils et paramètres → Gestion des API. Consultez les capacités avec GET /api/v1/whoami (X-API-Key + X-Secret-Key ou signature HMAC).

Callback du résultat de versement

Vous pouvez fournir callback_url dans le corps lors de la création d’une commande ; quand le décaissement aboutit, échoue ou est annulé, la plateforme transmet le résultat à cette URL par POST.

  • Le corps du rappel est signé avec la clé privée de la plateforme ; la signature figure dans l’en-tête X-Platform-Signature
  • Vérifiez la signature avec la clé publique de la plateforme (copiable dans les paramètres) ; l’algorithme de vérification est le même que pour les requêtes
  • En cas d’échec, nouvelles tentatives après 1m / 5m / 30m / 2h / 6h / 24h — 6 au total — puis arrêt et transfert pour traitement manuel
  • Votre serveur doit renvoyer HTTP 2xx ; toute autre réponse est considérée comme un échec

En-têtes

  • X-Timestamp — Horodatage unix actuel en millisecondes
  • X-Platform-Signature — Base64(RSA-PKCS1v15-SHA256(clé privée de la plateforme, chaîne à signer))

Règle de concaténation de la chaîne à signer

PATH est le chemin de callback_url (sans hôte ni query string) et BODY le corps reçu tel quel — ne le resérialisez pas. Vérifiez avec la clé publique de la plateforme de la page de configuration.

status vaut completed / failed / failed_onchain / cancelled ; montants et frais sont des chaînes ; created_at et completed_at sont en secondes unix, 0 sans heure de fin. Le corps ne change pas entre les tentatives d'une même commande : dédupliquez sur order_id.

Lancer un versement

POST /api/v1/withdraw

Après création, la commande est pending ; un processus la diffuse automatiquement à l’expiration du délai. Pendant cette période, vous pouvez la mettre en pause, l’accélérer ou l’annuler dans la console.

Description des champs

  • chain — string — Oui — tron / eth / bsc / polygon / arbitrum / base / optimism / avax / xlayer / btc
  • symbol — string — Oui — USDT / TRX / ETH, etc.
  • amount — string — Oui — Jusqu’à 18 décimales ; utilisez une chaîne pour éviter les erreurs de virgule flottante
  • to_address — string — Oui — Adresse de destination (à ajouter d’abord dans la console si la liste d’adresses autorisées est activée)
  • memo — string — Non — Description (≤500 caractères) ; transmise au titulaire du compte avec la notification
  • callback_url — string — Non — URL de rappel du résultat ; aucun rappel si vide
  • request_id — string — Fortement recommandé — Clé d’idempotence ; la même valeur pour le même compte renvoie la commande initiale ; si la chaîne, le symbole, l’adresse ou le montant diffère, 409 est renvoyé et aucune commande n’est créée Sans lui, aucune protection d’idempotence : réessayer après un délai dépassé ou une réponse 5xx crée un second paiement réel.

Champs de réponse

  • order_id — string — ID de la commande de retrait ; utilisé pour consulter un retrait individuel
  • status — string — État actuel de la commande, avec les mêmes valeurs que status_label du point d’accès de consultation. Une nouvelle commande est pending (solde débité, en attente du délai de contrôle des risques et de la diffusion) ; réutiliser le même request_id renvoie son état réel, qui peut déjà être completed, failed, etc.
  • amount — string — Montant du retrait (chaîne)
  • fee — string — Frais prévus (figés lors de la commande)
  • fee_mode — string — in_amount = déduits du montant (reçu = amount − fee, solde débité de amount) ; out_amount = facturés séparément (reçu = amount, solde débité de amount + fee)
  • delayed_until — string | null — Date de diffusion prévue (délai de contrôle des risques) ; null = sans délai

Consulter l’état d’un décaissement

GET /api/v1/withdraw/:id

Renvoie les détails de la commande ; permet d’interroger périodiquement son état (l’utilisation des rappels reste recommandée).

Champs de réponse

  • id — string — ID de la commande de retrait
  • request_id — string — Clé d’idempotence que vous avez fournie
  • chain / symbol — string — Chaîne / symbole du jeton
  • amount / expected_fee / fee_mode — string — Montant du retrait / frais prévus figés à la commande / mode de frais (in_amount, out_amount)
  • to_address — string — Adresse de destination
  • memo — string — Mémo (TAG/Memo)
  • status / status_label — int / string — Code d’état et libellé ; voir « État des commandes » ci-dessous
  • tx_hash — string — Hash de la transaction sur la chaîne (défini après diffusion)
  • fail_reason — string — Motif de l’échec (défini en cas d’échec)
  • delayed_until / broadcast_at / confirmed_at / paused_at / cancelled_at — string | null — Horodatages des étapes : diffusion prévue / diffusion / confirmation sur la chaîne / pause / annulation ; null si l’étape n’a pas été atteinte
  • callback_url / callback_retry — string / int — URL de rappel du résultat / nombre de nouvelles tentatives effectuées
  • callback_state — string — État du rappel : pending = pas encore appelé ou nouvelle tentative en cours, success = 2xx reçu, giveup = tentatives épuisées, no_url = aucun rappel configuré
  • created_at — string — Date de création

Consulter le solde disponible

GET /api/v1/balance/withdrawable

Renvoie le solde « regroupé, en attente de décaissement » du compte par chaîne × actif. Seule cette part peut servir aux décaissements API.

Structure à deux niveaux : chaîne → symbole du jeton → solde retirable (chaîne) ; seuls les soldes supérieurs à 0 sont renvoyés.

Estimation des frais

Renvoie les frais prélevés à l’avance configurés par l’administrateur pour cette chaîne × symbole (valeur fixe de type OKX).

Champs de réponse

  • chain / symbol / amount — string — Paramètres de requête repris : chain / symbol / amount
  • fee_amount — string — Montant des frais
  • fee_asset — string — Actif de règlement des frais

Exemple cURL complet

Procédure complète de signature et de requête ; copiez-la directement dans votre terminal pour tester.

État de commande · Versement

Machine à états : pending → broadcasted → completed / failed_onchain ; les états paused / cancelled / failed peuvent intervenir.

  • 0 — pending — Solde débité ; en attente de la fin du délai / pas encore diffusé
  • 1 — completed — Transaction sur la chaîne confirmée avec succès (rappel possible)
  • 2 — failed — Échec avant diffusion (solde remboursé)
  • 3 — broadcasted — Diffusée ; en attente de confirmation sur la chaîne
  • 4 — failed_onchain — Échec sur la chaîne (annulation / absence prolongée d’inclusion dans un bloc ; solde remboursé)
  • 5 — paused — Mise en pause manuellement par l’utilisateur ; reprise ou annulation possible
  • 6 — cancelled — Annulée manuellement par l’utilisateur ; solde remboursé
  • 7 — broadcasting — Diffusion en cours (état transitoire bref évitant une double diffusion)

Codes d’erreur · API de décaissement

  • 400 — Paramètres invalides / solde insuffisant / montant hors limites pour la chaîne × symbole / échec de validation de l’adresse
  • 401 — Clé API invalide / écart d’horodatage excessif / nonce déjà utilisé / échec de vérification de la signature
  • 403 — Décaissement API non activé pour le compte / IP absente de la liste autorisée du compte ; ou clé API sans capacité withdraw (code 4032), ou IP source absente de la liste autorisée de cette clé (code 4033)
  • 404 — Commande introuvable
  • 429 — Trop de requêtes (10 par seconde et par compte maximum). La réponse contient Retry-After: 1 ; attendez une seconde et réessayez avec le même request_id
  • 5xx — Erreur de la plateforme ; nouvelle tentative possible (utilisez le même request_id pour garantir l’idempotence)

Consignes de sécurité des versements

  • Conservez votre clé privée en sécurité localement ; une fuite permettrait à d’autres d’effectuer des décaissements en votre nom
  • Vous devez configurer une liste d’IP autorisées avant d’activer les décaissements API (obligatoire) ; une IP non autorisée est refusée même avec une signature valide
  • Nous recommandons aussi d’activer la liste d’adresses de décaissement autorisées et d’enregistrer les destinations connues à l’avance
  • Après activation de la 2FA, le titulaire du compte peut l’utiliser dans la console pour accélérer ou annuler des commandes pendant le délai
  • Pour les commandes importantes, envisagez un délai plus long (plusieurs heures) afin de laisser le temps d’intervenir manuellement après les notifications

Pages connexes: Paiements crypto multichaînes · API SMTP agrégée · Services IA

Chargement…