@usdctofiat/offramp ajoute un off-ramp USDC en un seul appel de fonction.
Le SDK est la voie rapide pour vendre des USDC depuis votre propre app. Un seul appel valide l'entrée, approuve les USDC, enregistre le vendeur, crée le dépôt sur Base et délègue la tarification. Il cible le mainnet Base et la création de dépôt est sans permission.
Installer et créer un dépôt
- 1Installez le paquet : bun add @usdctofiat/offramp (npm et pnpm fonctionnent aussi).
- 2Passez un WalletClient viem : le wallet de l'utilisateur, un wallet serveur ou un wallet de bot.
- 3Appelez offramp(walletClient, { amount, platform, currency, identifier }).
- 4Lisez le depositId et le txHash retournés, ou échafaudez un projet avec npx create-offramp-app@latest.
La surface du SDK
| Export | Ce qu'il fait |
|---|---|
| offramp(walletClient, params) | Flux de vente d'USDC en un appel, retournant { depositId, txHash, resumed, otcLink? } |
| deposits(address) | Liste les dépôts d'une adresse sans indexer l'état du protocole |
| close(walletClient, depositId) | Retire les USDC non remplis d'un dépôt existant |
| enableOtc / disableOtc / getOtcLink | Gère la restriction privée à un seul acheteur sur un dépôt |
| useOfframp() / usePeerExtensionRegistration() | Hooks React depuis @usdctofiat/offramp/react |
| PLATFORMS, CURRENCIES | Maps de constantes typées avec identifiants, validation et listes de devises |
Reprenable par conception
La création d'un dépôt s'étend sur plusieurs étapes onchain. Si un appel précédent a laissé un dépôt en cours, rappeler offramp() reprend là où il s'était arrêté plutôt que de créer un doublon. Le flag resumed du résultat vaut true lorsqu'un dépôt non délégué existant a été adopté au lieu d'être créé.
Cela rend le SDK sûr à réessayer depuis un serveur ou un bot : un point d'entrée compatible avec l'idempotence qui se réconcilie avec l'état onchain au lieu de supposer une page blanche.
Gestion des erreurs
| Préoccupation | Comment le SDK la signale |
|---|---|
| Erreurs typées | OfframpError porte un code issu de OFFRAMP_ERROR_CODES |
| Configuration PayPal ou Wise | EXTENSION_REGISTRATION_REQUIRED lorsque le handle n'est pas encore enregistré |
| Validation | PLATFORMS et CURRENCIES exposent la validation des identifiants et des devises |
| Aucune garde de clés | Le SDK signe avec votre WalletClient et ne stocke jamais de clés privées |
Où aller ensuite
Templates de démarrage
Starters Next.js, Vite et bot Telegram, plus des scripts exécutables et des récepteurs HMAC.
Webhooks
Abonnez-vous aux événements du cycle de vie des dépôts et de l'OTC avec des callbacks signés en HMAC.
OTC privé en code
Restreignez un dépôt à un seul wallet acheteur approuvé et partagez un lien.
Keep exploring
Common questions
@usdctofiat/offramp est-il gratuit ?
Oui. Le SDK est gratuit à installer et à intégrer, et la création de dépôts ne nécessite aucune clé API car votre wallet signe. Les analyses Peerlytics, les crédits d'API et la gestion de webhooks signés sont disponibles séparément via Peerlytics.
Le SDK détient-il des clés ou déplace-t-il du fiat ?
Non aux deux. Il signe avec le WalletClient viem que vous fournissez et ne détient jamais de clés privées. Le fiat circule directement entre l'acheteur et le vendeur sur l'app de paiement choisie ; le SDK ne gère que les USDC onchain et le cycle de vie du dépôt.
Comment tester une intégration ?
Il n'y a pas de sandbox public ; le SDK cible le mainnet Base, donc un dépôt de test est réel et visible sur l'orderbook ouvert. Utilisez le minimum de 1 USDC et soit restreignez-le comme dépôt OTC (passez otcTaker pour que seul votre wallet puisse le remplir), soit fermez-le rapidement avec close(). Vérifiez onchain et via deposits().