Frais, soldes et réconciliation

Les questions d’argent méritent des réponses exactes. Cette page couvre les trois qui comptent : combien cela va coûter, où est mon argent en ce moment, et comment prouver que mes livres correspondent à ceux de CowriePay.

Comment les frais se calculent

Les dépôts paient un pourcentage du brut, avec un frais minimum par blockchain ; le plus élevé des deux s’applique. Le pourcentage est dégressif : il suit votre volume de dépôts sur 30 jours glissants à travers les paliers (le volume de retraits ne gonfle jamais le palier).
Les retraits paient un frais fixe par blockchain.
Un workspace peut porter un accord négocié ; quand il s’applique, il prime champ par champ sur le palier.
Certains contrats portent un engagement mensuel minimum négocié. Quand les frais facturés d’un mois calendaire restent sous le plancher convenu, un ajustement de rattrapage de la différence est émis (au prorata le premier et le dernier mois) et notifié par le webhook COMMITMENT_ADJUSTMENT_EMITTED. Il n’est prélevé sur votre solde disponible que si votre contrat le prévoit, et le prélèvement est borné à ce solde : il ne peut jamais vous faire passer sous zéro ; la fraction non couverte reste exigible. Consultez le vôtre, et l’avancement du mois en cours, avec GET /v2/commitment (scope fees:read) ; la réponse est à null quand aucun ne s’applique. Un engagement terminé y reste lisible tant que tout ce qui est dû n’est pas réglé, avec current_period à null et outstanding_total_usdt portant le reliquat. L’article 9 des conditions générales d’utilisation en est le texte contractuel.

Vous n’inscrivez jamais ces nombres en dur : vous les demandez en devis.

Demandez un devis avant d’agir

POST /v2/fees/quote (scope fees:read) chiffre un dépôt ou un retrait prospectif avec le moteur exact qui le réglera, et répond toujours 200 pour une entrée valide :

{ "direction": "deposit", "chain": "TRON", "asset": "USDT_TRON", "amount": "100", "mode": "charge" }

La réponse porte gross, fee, net, les applied_rate et applied_min_fee qui les ont produits, et effective_rate (frais sur brut, plus élevé que le taux nominal quand le frais minimum domine un petit montant). Deux modes :

charge (défaut) : amount est le brut ; net est ce qui atterrit après frais.
gross_up : amount est le net cible ; gross est ce qu’il faut envoyer pour le toucher.

Un devis peut être non viable sans échouer : pour un montant trop petit pour survivre aux frais, vous recevez quand même 200, avec viable: false, net: null et une entrée warnings[] qui nomme la raison (montant trop petit, montant sous le minimum de consolidation, frais minimum dominant, accord négocié expirant sous 24 h). Lisez les warnings ; ne les traitez pas comme des erreurs.

Le devis est indicatif, le règlement est engageant. Entre devis et règlement, votre volume sur 30 jours peut franchir un palier ou un accord peut expirer ; les chiffres réglés sont ceux du payload DEPOSIT_SWEPT et du fee_record.

Les trois états du solde

GET /v2/transactions/balances renvoie, par actif, les trois nombres qui décrivent où est votre argent (dans le réseau de votre clé ; mainnet et testnet ne se mélangent jamais) :

Champ	Signification
`available`	Dépensable maintenant : crédité net de frais, retirable
`pending`	Dépôts détectés pas encore consolidés : en sécurité, mais pas encore dépensables
`locked`	Réservé par des retraits en vol : revient en `available` s’ils échouent ou sont annulés

Les mouvements entre eux sont exactement les tableaux de statuts d’ Encaisser des dépôts et de Déclencher des retraits : pending se remplit à DETECTED et se convertit en available (net) à SWEPT ; locked se remplit à la création d’un retrait et se vide à son état terminal.

Réconciliez au centime

Tout ce qu’il faut pour rapprocher vos livres de ceux de CowriePay arrive tout seul :

Par dépôt : le webhook DEPOSIT_SWEPT porte l’objet fee (gross_amount, fee_amount, net_amount, applied_rate, applied_min_fee), et les mêmes chiffres persistent sur le fee_record du dépôt (GET /v2/transactions/deposits), null tant que non consolidé.
Par retrait : WITHDRAWAL_CONFIRMED porte le même objet fee ; les estimations vues à la création deviennent définitives ici.
Réconciliez par enregistrement, pas par total. À intervalle régulier, parcourez GET /v2/transactions (le flux combiné) et vérifiez que chaque net_amount de dépôt consolidé et chaque retrait terminal a son reflet dans vos livres, en portant les enregistrements en vol (dépôts pending, retraits locked) comme leurs propres lignes ouvertes. Un enregistrement que votre système ne sait pas expliquer est le résultat de l’exercice ; l’ habitude de réconciliation des dépôts est la façon de le traquer.

Et ensuite

Déclencher des retraits : d’où vient locked, et où il retourne.
Référence Fees : l’endpoint de devis, champ par champ.