@usdctofiat/offramp aggiunge un off-ramp USDC in una sola chiamata di funzione.
L'SDK è la via rapida per vendere USDC dalla tua app. Una sola chiamata valida l'input, approva gli USDC, registra il venditore, crea il deposito su Base e delega il pricing. È pensato per la mainnet di Base ed è permissionless per la creazione dei depositi.
Installa e crea un deposito
- 1Installa il pacchetto: bun add @usdctofiat/offramp (funzionano anche npm e pnpm).
- 2Passa un viem WalletClient: il wallet dell'utente, un server wallet o un bot wallet.
- 3Chiama offramp(walletClient, { amount, platform, currency, identifier }).
- 4Leggi depositId e txHash restituiti, oppure crea l'impalcatura di un progetto con npx create-offramp-app@latest.
La superficie dell'SDK
| Export | Cosa fa |
|---|---|
| offramp(walletClient, params) | Flusso di vendita USDC in una chiamata che restituisce { depositId, txHash, resumed, otcLink? } |
| deposits(address) | Elenca i depositi di un indirizzo senza indicizzare lo stato del protocollo |
| close(walletClient, depositId) | Preleva gli USDC non riempiti da un deposito esistente |
| enableOtc / disableOtc / getOtcLink | Gestisci la restrizione privata a un solo acquirente su un deposito |
| useOfframp() / usePeerExtensionRegistration() | Hook React da @usdctofiat/offramp/react |
| PLATFORMS, CURRENCIES | Mappe const tipizzate con identificatori, validazione ed elenchi di valute |
Riprendibile by design
Creare un deposito comporta diversi passaggi onchain. Se una chiamata precedente ha lasciato un deposito a metà, richiamare offramp() riprende da dove si era interrotto invece di creare un duplicato. Il flag resumed del risultato è true quando viene adottato un deposito esistente non ancora delegato anziché crearne uno nuovo.
Questo rende l'SDK sicuro da ritentare da un server o da un bot: un entry point idempotency-friendly che si riconcilia con lo stato onchain invece di presumere una situazione pulita.
Gestione degli errori
| Aspetto | Come l'SDK lo segnala |
|---|---|
| Errori tipizzati | OfframpError porta un code da OFFRAMP_ERROR_CODES |
| Configurazione PayPal o Wise | EXTENSION_REGISTRATION_REQUIRED quando l'handle non è ancora registrato |
| Validazione | PLATFORMS e CURRENCIES espongono la validazione di identificatore e valuta |
| Nessuna custodia delle chiavi | L'SDK firma con il tuo WalletClient e non memorizza mai le chiavi private |
Dove andare dopo
Keep exploring
Common questions
@usdctofiat/offramp è gratuito?
Sì. L'SDK è gratuito da installare e integrare, e la creazione dei depositi non richiede alcuna API key perché firma il tuo wallet. Analytics di Peerlytics, crediti API e gestione dei webhook firmati sono disponibili separatamente tramite Peerlytics.
L'SDK custodisce le chiavi o muove fiat?
No a entrambe le cose. Firma con il viem WalletClient che fornisci e non detiene mai le chiavi private. Il fiat si muove direttamente tra acquirente e venditore sull'app di pagamento scelta; l'SDK gestisce solo gli USDC onchain e il ciclo di vita del deposito.
Come testo un'integrazione?
Non esiste una sandbox pubblica; l'SDK è pensato per la mainnet di Base, quindi un deposito di test è reale e visibile sull'orderbook aperto. Usa il minimo di 1 USDC e o limitalo come deposito OTC (passa otcTaker così solo il tuo wallet può riempirlo) oppure chiamalo con close() rapidamente. Conferma onchain e tramite deposits().