@aron-petrus/wallet-sdk

Wallet SDK

SDK TypeScript para integrar aplicações de backend à Wallet.

O fluxo de autenticação é automático: ao realizar a primeira chamada protegida, o SDK autentica o api_user, armazena o token em memória e o renova quando necessário. A aplicação não precisa implementar login, challenge ou renovação de sessão.

Configuração do cliente

import { WalletSdk } from "@wallet/sdk";

const wallet = new WalletSdk({
  baseUrl: process.env.WALLET_API_URL!,
  apiUserAuth: {
    privateKeyPem: process.env.WALLET_API_PRIVATE_KEY!,
    publicKey: process.env.WALLET_API_PUBLIC_KEY!,
  },
});

Depois da configuração, use os resources diretamente. A autenticação será feita na primeira chamada.

const vault = await wallet.vaults.create({
  name: "customer-123",
  requestId: crypto.randomUUID(),
});

const address = await wallet.vaultAddresses.create(vault.vaultId, {
  networkGroup: "evm",
  requestId: crypto.randomUUID(),
});

const balances = await wallet.balances.list(vault.vaultId);

console.log({ vault, address, balances });

Resources utilizados na integração

Fluxo recomendado

1. Configurar uma instância de WalletSdk por processo.
2. Criar ou localizar o vault do cliente.
3. Criar um endereço para o grupo de rede necessário.
4. Consultar saldos e depósitos pelo vaultId.
5. Criar transações usando valores em string.
6. Acompanhar o resultado por webhook ou por wallet.transactions.get().
7. Usar o Callback Handler quando a operação exigir aprovação externa antes da assinatura.

Documentação de integração

• Integração essencial
• Callback Handler
• Referência rápida

Cuidados de produção

• Mantenha a chave privada do api_user fora do código-fonte e dos logs.
• Reutilize a instância do cliente para compartilhar o token e sua renovação.
• Use requestId único nas criações para facilitar idempotência e rastreamento.
• Trate valores financeiros como strings.
• Considere uma transação concluída somente após o estado final recebido pela Wallet.
• Valide a assinatura de todo Callback Handler ou webhook antes de processar o conteúdo.