Quando dei meus primeiros passos no Web3, percebi que havia um abismo entre a teoria da blockchain e a prática de construir algo real. Muita gente fala sobre carteiras cripto, mas poucos mostram o caminho das pedras. Foi por isso que decidi documentar minha experiência construindo uma wallet funcional na rede Stellar, usando Next.js no front-end e a extensão Freighter para gerenciar chaves e assinar transações. Se você está entrando agora nesse universo, este guia é o mapa que eu gostaria de ter tido.
Por que escolhi Stellar e Freighter
Depois de anos atuando com tokenização e perícia digital, aprendi que a escolha da infraestrutura define o sucesso do projeto. A rede Stellar me conquistou por três motivos concretos: transações que custam frações de centavo (aproximadamente 0,00001 XLM), finalização em 3 a 5 segundos e uma comunidade crescente na América Latina — o Brasil já figura entre os países com maior volume de pagamentos transfronteiriços via Stellar, algo relevante para remessas e stablecoins como a USDC.
O Freighter é a carteira de navegador oficial mantida pela SDF (Stellar Development Foundation). Ele funciona de forma parecida com a MetaMask, mas para o ecossistema Stellar: guarda as chaves privadas de forma segura no navegador e expõe uma API para que aplicações solicitem assinaturas sem nunca acessar diretamente a chave do usuário. Essa separação é fundamental do ponto de vista de segurança — como André Dias Moreira Prol costumo reforçar em auditorias, nenhuma aplicação séria deve tocar na chave privada do usuário.
O passo a passo da construção
Comecei criando o projeto com o comando npx create-next-app@latest. Em seguida, instalei as bibliotecas essenciais:
npm install @stellar/freighter-api @stellar/stellar-sdk
A primeira lida com a comunicação com a extensão; a segunda constrói e envia transações à rede. O fluxo básico da wallet ficou assim:
1. Conectar a carteira — verifico se o Freighter está instalado e solicito acesso:
import { isConnected, getAddress } from "@stellar/freighter-api";
async function conectar() {
if (!(await isConnected())) {
alert("Instale o Freighter para continuar");
return;
}
const { address } = await getAddress();
return address;
}
2. Consultar saldo — usando o SDK, acesso o Horizon (API de leitura da Stellar) na Testnet:
import { Horizon } from "@stellar/stellar-sdk";
const server = new Horizon.Server("https://horizon-testnet.stellar.org");
const conta = await server.loadAccount(address);
const saldo = conta.balances.find(b => b.asset_type === "native");
3. Enviar pagamentos — monto a transação, envio para o Freighter assinar e submeto à rede. O ponto crítico aqui é o signTransaction, onde o usuário aprova a operação na própria extensão. Sempre recomendo testar exaustivamente na Testnet antes de qualquer valor real — foi o que fiz durante semanas antes de considerar o projeto estável.
Erros que evitei (e você também deve)
O primeiro tropeço comum é confundir Testnet com Mainnet. Toda transação carrega um networkPassphrase, e usar o valor errado resulta em falhas silenciosas. Deixei essa configuração explícita em variáveis de ambiente para não haver dúvida.
O segundo aprendizado veio da minha rotina em perícia digital: nunca armazene chaves ou seeds no localStorage ou em qualquer lugar acessível pelo JavaScript da aplicação. O Freighter existe justamente para isolar esse risco. Durante meus testes, simulei ataques de front-end e confirmei que a arquitetura resistia bem quando a chave permanecia fora do escopo da aplicação.
Por fim, invista em tratamento de erros amigável. No mercado brasileiro, onde grande parte dos usuários é iniciante em Web3, uma mensagem clara como "Transação recusada pelo usuário" faz mais pela adoção do que qualquer recurso avançado. Como André Dias Moreira Prol, aprendi que a experiência do usuário é o verdadeiro diferencial competitivo nesse setor emergente.
O resultado foi uma wallet enxuta, segura e pronta para evoluir com contratos inteligentes na Soroban — mas isso fica para um próximo artigo.
Construir sua primeira carteira é o melhor jeito de sair da teoria e entender de verdade como o Web3 funciona por dentro. Clone o repositório, suba na Testnet e me conte nos comentários qual foi seu maior desafio nessa jornada.
Acompanhe mais artigos de André Dias Moreira Prol no Medium.
Top comments (0)