Conventions d'API

Les règles qui valent sur tous les endpoints, énoncées une fois. Tout ce qui suit est appliqué par le serveur ; rien n’est un conseil de style.

Les montants sont des chaînes décimales lisibles

Chaque champ monétaire est une chaîne décimale en unités entières de l’actif : "50" signifie 50 USDT, "0.5" un demi ETH. Jamais d’unités blockchain brutes (ni sun, ni wei).

• En entrée, les zéros de fin sont optionnels : "100", "100.0" et "100.000000" sont la même valeur.
• En sortie, l’API complète à la précision de l’actif : vous relisez "100.000000".
• Faites les calculs en décimal, jamais en flottant. Chaque actif a une précision fixe, et l’une d’elles est un piège : l’USDT sur BSC a 18 décimales (c’est le Binance-Peg BSC-USD), contrairement à l’USDT sur TRON et Ethereum (6). Un 6 inscrit en dur fausse les montants BSC de 12 ordres de grandeur. La table par actif est sur la vue d’ensemble de la référence.

Idempotence : des retentatives qui ne peuvent jamais doubler

Les POST créateurs (créer un wallet, créer un customer, demander un retrait) acceptent un en-tête Idempotency-Key (1-255 caractères, A-Z a-z 0-9 _ - ; un UUIDv4 est le choix simple). La première requête s’exécute ; une retentative avec la même clé et le même corps renvoie la réponse d’origine, marquée Idempotent-Replay: true, sans se réexécuter.

Vous envoyez	Vous recevez
Même clé, même corps	La réponse d’origine, Idempotent-Replay: true
Même clé, corps différent	422 IDEMPOTENCY_MISMATCH
Même clé pendant que la première est en vol	409 IDEMPOTENCY_CONFLICT : patientez, réessayez la même clé
Une clé mal formée	400 IDEMPOTENCY_KEY_INVALID

Les clés sont mémorisées 24 heures. Seules les issues définitives sont rejouées (succès et erreurs client déterministes) ; un 401, 429 ou 5xx libère la clé pour que la retentative s’exécute. Générez la clé une fois par intention et persistez-la avant l’envoi ; l’exemple complet est dans Déclencher des retraits.

Pagination

Les endpoints de liste prennent page (à partir de 1, défaut 1) et limit (1-100, défaut 20) et répondent une seule enveloppe :

{ "data": [], "total": 137, "page": 1, "limit": 20 }

Itérez jusqu’à page * limit >= total. Les listes sont ordonnées du plus récent au plus ancien.

Limites de débit

Les requêtes sont limitées par clé API ; le défaut déployé est de 100 requêtes par fenêtre glissante de 60 secondes (considérez ce nombre comme la valeur du jour, pas comme un contrat). Au-delà, 429 RATE_LIMITED : reculez et réessayez, et lissez vos rafales plutôt que de marteler le bord de la fenêtre.

Taille des requêtes

Les corps de requête sont plafonnés à 50 ko ; au-delà, 413 PAYLOAD_TOO_LARGE. Aucun appel légitime n’approche ce plafond ; l’atteindre signifie généralement qu’une donnée (un blob de métadonnées, par exemple) n’a pas sa place dans la requête.

Les erreurs portent un code ; les warnings ne sont pas des erreurs

Chaque corps d’erreur suit la même enveloppe, et le code est le contrat :

{ "error": "Insufficient balance. Available: 10.000000, Requested: 50.000000", "code": "INSUFFICIENT_BALANCE" }

Branchez-vous sur code, journalisez error, et attendez-vous aux codes génériques (VALIDATION_ERROR, NOT_FOUND, UNPROCESSABLE…) bien plus souvent qu’aux codes nommés ; le catalogue complet avec la conduite de retentative est dans Codes d’erreur.

À part, une réponse en succès peut porter un tableau warnings[] (le devis de frais le fait : un devis peut être bien formé sans être viable). Un warning ne change jamais le code de statut ; lisez-le, ne le traitez pas comme un échec. Les codes de warning s’ajoutent au fil du temps ; ignorez ceux que vous ne connaissez pas.

Évolution additive

Les réponses en succès gagnent des champs avec le temps ; les champs inconnus et les valeurs d’enum inconnues doivent être ignorés, pas rejetés. Ce qui est promis à long terme, et ce qui ne l’est pas, est énoncé strictement dans Compatibilité ascendante.