La sandbox et le faucet

La Sandbox est la vraie blockchain

Il existe exactement un environnement de test, et ce sont les vrais testnets publics : TRON Nile, BSC testnet et Ethereum Hoodi. Il n’y a pas de simulateur. Chaque test Sandbox exerce le vrai parcours on-chain : dérivation d’adresse, une vraie transaction dans un vrai bloc, de vraies confirmations, des webhooks au rythme de la blockchain elle-même.

C’est un choix assumé. Un simulateur répond instantanément et masque précisément la classe de comportements qui surprend les intégrateurs en production (les délais de confirmation, la distinction DETECTED puis CONFIRMED, une transaction qui met une minute à se poser). La Sandbox vous fait rencontrer ces comportements dès le premier jour, avec des actifs sans valeur.

Concrètement :

• Même hôte, même code, même recette de signature qu’en production. Le préfixe cpk_test_ de votre clé est la seule chose qui dit Sandbox.
• Les stablecoins que vous recevez sont des tokens de test émis par CowriePay sur ces réseaux ; les monnaies natives (ETH, BNB, TRX) sont les monnaies de test des réseaux eux-mêmes.
• Les délais sont réels : un dépôt TRON se confirme en secondes ou minutes, un dépôt Ethereum au rythme de Hoodi.

Le faucet : alimenter un wallet en un appel

Le faucet préfinance l’une de vos propres adresses de wallet sandbox avec des actifs de test, pour que vous n’ayez jamais à chercher de faucets publics. C’est POST /v2/sandbox/faucet, avec le scope wallets:write, et il n’accepte qu’une clé cpk_test_ (une clé de production reçoit 403 FAUCET_ONLY_SANDBOX).

Requête :

{
  "chain": "TRON",
  "address": "TYourSandboxWalletAddress1234567890",
  "assets": [{ "symbol": "USDT_TRON" }]
}

Réponse (202) :

{
  "drip_id": "d4e5f6a7-0000-0000-0000-000000000004",
  "status": "PENDING",
  "chain": "TRON",
  "address": "TYourSandboxWalletAddress1234567890",
  "items": [
    { "asset": "USDT_TRON", "amount": "1000", "status": "PENDING" }
  ]
}

La distribution est mise en file, envoyée on-chain, puis arrive comme un dépôt parfaitement normal : votre webhook reçoit DEPOSIT_DETECTED, puis DEPOSIT_CONFIRMED, exactement comme avec un vrai client. C’est tout l’intérêt : le faucet est un raccourci de financement, pas un chemin de code séparé.

Omettez amount pour recevoir le montant par défaut de l’actif (généreux pour les tokens). Le tableau de bord propose la même chose via une invite de préfinancement juste après la création d’un wallet sandbox.

Tokens généreux, natif rationné

Les tokens de test (USDT, USDC, EURC) sont émis par CowriePay : ils sont de fait illimités et les montants par défaut sont généreux.

La monnaie native (ETH, BNB) est différente : elle est collectée sur les faucets publics des testnets, ce qui en fait la ressource réellement rare. Le natif est donc en opt-in (demandez-le explicitement dans assets), porte un budget glissant par actif et par workspace, et n’est débloqué qu’une fois que votre workspace a au moins un dépôt de token sandbox confirmé.

Avant de demander du natif, demandez-vous si vous en avez besoin : dans le modèle de garde de CowriePay, vous n’avez jamais besoin de monnaie native pour déplacer des tokens. CowriePay paie le gas des consolidations et des retraits. La seule raison de demander du natif est de tester un dépôt d’actif natif lui-même.

Quand le faucet refuse

Chaque limite a son propre code d’erreur, pour que vous sachiez toujours quel mur vous avez touché ; la liste complète avec la conduite à tenir est dans le catalogue des codes d’erreur. Les deux à connaître d’avance :

• FAUCET_NATIVE_REQUIRES_DEPOSIT : distribuez d’abord un token et laissez-le se confirmer ; le natif se débloque ensuite.
• FAUCET_DISPENSER_EXHAUSTED : celui-ci est de notre côté, pas du vôtre. Le distributeur partagé n’a plus de monnaie native ; notre équipe est alertée quand il se déclenche. Réessayez plus tard, ou demandez uniquement des tokens.

Ce que la Sandbox ne fait pas encore

Il n’existe pas encore de moyen de déclencher de façon déterministe un scénario d’échec (un dépôt signalé, un sous-paiement, une livraison de webhook en échec). C’est un manque connu et planifié, énoncé ici pour que vous ne cherchiez pas une fonctionnalité qui n’existe pas. D’ici là, la gestion des échecs se travaille en revue de code, avec le catalogue des codes d’erreur comme contrat.

Et ensuite

• Démarrage rapide : le faucet en contexte, du compte vide au client crédité.
• Concepts on-chain : ce que DETECTED, CONFIRMING et CONFIRMED veulent vraiment dire.
• Passage en production : ce qui change, et ce qui ne change volontairement pas, quand vous échangez la clé.