@usdctofiat/offramp adiciona um off-ramp de USDC em uma única chamada de função.
O SDK é o caminho rápido para vender USDC a partir do seu próprio app. Uma chamada valida a entrada, aprova o USDC, registra o vendedor, cria o depósito na Base e delega a precificação. Ele tem como alvo a mainnet da Base e é permissionless para a criação de depósitos.
Instale e crie um depósito
- 1Instale o pacote: bun add @usdctofiat/offramp (npm e pnpm também funcionam).
- 2Passe um viem WalletClient: a carteira do usuário, uma carteira de servidor ou uma carteira de bot.
- 3Chame offramp(walletClient, { amount, platform, currency, identifier }).
- 4Leia o depositId e o txHash retornados, ou crie a estrutura de um projeto com npx create-offramp-app@latest.
A superfície do SDK
| Export | O que faz |
|---|---|
| offramp(walletClient, params) | Fluxo de venda de USDC em uma chamada que retorna { depositId, txHash, resumed, otcLink? } |
| deposits(address) | Lista os depósitos de um endereço sem indexar o estado do protocolo |
| close(walletClient, depositId) | Saca o USDC não preenchido de um depósito existente |
| enableOtc / disableOtc / getOtcLink | Gerencia a restrição privada de comprador único em um depósito |
| useOfframp() / usePeerExtensionRegistration() | Hooks React de @usdctofiat/offramp/react |
| PLATFORMS, CURRENCIES | Mapas const tipados com identificadores, validação e listas de moedas |
Retomável por design
Criar um depósito envolve várias etapas onchain. Se uma chamada anterior deixou um depósito no meio do fluxo, chamar offramp() novamente retoma de onde parou, em vez de criar um duplicado. O campo resumed do resultado é true quando um depósito não delegado já existente foi adotado em vez de criado.
Isso torna o SDK seguro para retentativas a partir de um servidor ou bot: um ponto de entrada idempotency-friendly que reconcilia com o estado onchain em vez de presumir um ponto de partida limpo.
Tratamento de erros
| Aspecto | Como o SDK sinaliza |
|---|---|
| Erros tipados | OfframpError carrega um code de OFFRAMP_ERROR_CODES |
| Configuração de PayPal ou Wise | EXTENSION_REGISTRATION_REQUIRED quando o handle ainda não está registrado |
| Validação | PLATFORMS e CURRENCIES expõem validação de identificador e de moeda |
| Sem custódia de chaves | O SDK assina com seu WalletClient e nunca armazena chaves privadas |
Para onde ir em seguida
Templates starter
Starters para Next.js, Vite e bot do Telegram, além de scripts executáveis e receptores HMAC.
Webhooks
Assine eventos do ciclo de vida de depósitos e OTC com callbacks assinados via HMAC.
OTC privado em código
Restrinja um depósito a uma carteira de comprador aprovada e compartilhe um link.
Keep exploring
Common questions
O @usdctofiat/offramp é gratuito?
Sim. O SDK é gratuito para instalar e integrar, e criar depósitos não exige API key porque sua carteira assina. As análises do Peerlytics, os créditos de API e o gerenciamento de webhooks assinados estão disponíveis à parte, através do Peerlytics.
O SDK custodia chaves ou movimenta fiat?
Não, para ambos. Ele assina com o viem WalletClient que você fornece e nunca guarda chaves privadas. O fiat se move diretamente entre comprador e vendedor no app de pagamento escolhido; o SDK só cuida do USDC onchain e do ciclo de vida do depósito.
Como faço para testar uma integração?
Não há sandbox público; o SDK tem como alvo a mainnet da Base, então um depósito de teste é real e descobrível no orderbook aberto. Use o mínimo de 1 USDC e restrinja-o como depósito OTC (passe otcTaker para que só sua carteira possa preenchê-lo) ou faça close() rapidamente. Confirme onchain e via deposits().