Como Usar a API Privy: Carteiras Embutidas e Autenticação Social para Web3

A integração de novos usuários em aplicativos Web3 ainda é um grande obstáculo. Frases-semente, extensões de navegador e taxas de gás complicam o onboarding, tornando algo que deveria ser simples em um processo demorado. A API do Privy resolve esse problema ao fornecer uma carteira incorporada a cada novo usuário, por trás de um login tradicional: e-mail, SMS, Google, Apple ou uma carteira existente como MetaMask. Assim, você converte usuários comuns em usuários Web3 nativos sem exigir extensões ou instalações extras.

Experimente o Apidog hoje

O Privy oferece suporte a carteiras nos principais aplicativos do setor (Blackbird, Friend.tech, OpenSea e milhares de outros) e é compatível com Ethereum, Solana e qualquer cadeia EVM. Este guia mostra, passo a passo, como integrar o Privy ao seu app: criação do app, configuração do SDK React, verificação de tokens no backend, assinatura de transações e uso de webhooks. Se quiser comparar com o kit de ferramentas do MetaMask, mantenha este post aberto e alterne entre eles.

💡Antes de mergulhar no código, vale conhecer a ferramenta Apidog. Use o Apidog para inspecionar cada requisição HTTPS feita pelos SDKs do Privy. Basta apontar seu app para um proxy local, capturar payloads reais e depurar autenticação em segundos, sem depender só de logs.

TL;DR

• O Privy unifica carteiras incorporadas com login por e-mail, SMS, sociais e carteiras externas em um único SDK.
• O SDK React fornece os hooks PrivyProvider, useLogin, useWallets e usePrivy para todo o fluxo de autenticação e assinatura.
• O pacote @privy-io/server-auth permite verificar tokens de acesso no backend e confiar no ID do usuário.
• As carteiras suportam Ethereum, Solana e outras EVMs, com exportação opcional e regras de autorização para operações sensíveis.
• Webhooks informam sobre criação, login e eventos de carteira, mantendo o banco de dados sincronizado sem polling.
• O motor de políticas do Privy permite MFA, listas de permissão e regras de transação, sem bifurcar seu código.

O que é a API do Privy?

O Privy é uma plataforma de autenticação e carteira para apps Web3. Você ganha uma interface de login, uma carteira incorporada por usuário e endpoints REST para verificações no backend. A carteira é criada em um enclave seguro: nem o Privy nem seu backend têm acesso à chave privada. Se o usuário quiser, pode exportar sua chave e migrar para uma carteira auto-custodiada depois.

A cobrança é por carteira ativa mensal: protótipos podem ser lançados gratuitamente, com o plano free cobrindo até 1.000 usuários ativos. O Pro começa em US$ 149/mês, enquanto o Enterprise oferece SLAs e recursos customizados.

Autenticação e Configuração

1. Crie um app em privy.io.
2. Anote o ID do app (clxxxxx...) para o SDK do cliente e o segredo do app para o backend.
3. Defina métodos de login (e-mail, SMS, Google, Apple, Farcaster, carteira), escolha a rede padrão e adicione seu domínio nas origens permitidas.

Instale o SDK React:

npm install @privy-io/react-auth

Envolva seu app com PrivyProvider:

import { PrivyProvider } from '@privy-io/react-auth';

export default function App({ Component, pageProps }) {
  return (
    <PrivyProvider
      appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
      config={{
        loginMethods: ['email', 'wallet', 'google'],
        embeddedWallets: { createOnLogin: 'users-without-wallets' },
        defaultChain: { id: 8453 }, // Base
        supportedChains: [{ id: 1 }, { id: 8453 }, { id: 137 }],
      }}
    >
      <Component {...pageProps} />
    </PrivyProvider>
  );
}

A flag createOnLogin faz o provisionamento automático da carteira na primeira entrada de um usuário sem carteira. Configure as chains suportadas conforme seu caso (Solana requer solanaClusters).

Endpoints principais e uso do SDK

O SDK React cobre a maioria dos fluxos. Conheça a API REST para depuração ou integrações server-side.

Login e leitura do usuário

import { usePrivy, useWallets } from '@privy-io/react-auth';

function LoginButton() {
  const { ready, authenticated, login, logout, user } = usePrivy();
  const { wallets } = useWallets();

  if (!ready) return <p>Carregando...</p>;
  if (!authenticated) return <button onClick={login}>Entrar</button>;

  const embedded = wallets.find((w) => w.walletClientType === 'privy');

  return (
    <div>
      <p>Olá {user.email?.address ?? user.id}</p>
      <p>Carteira: {embedded?.address}</p>
      <button onClick={logout}>Sair</button>
    </div>
  );
}

O hook useWallets retorna todas as carteiras vinculadas ao usuário. O campo walletClientType mostra qual delas foi criada pelo Privy. Siga esse padrão ao integrar carteiras incorporadas.

Assinando uma transação

const { wallets } = useWallets();
const wallet = wallets.find((w) => w.walletClientType === 'privy');

async function sendTx() {
  const provider = await wallet.getEthereumProvider();
  const hash = await provider.request({
    method: 'eth_sendTransaction',
    params: [{
      to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2',
      value: '0x38d7ea4c68000', // 0.001 ETH
    }],
  });
  console.log('tx hash', hash);
}

Para Solana, use getSolanaProvider e envie a transação serializada. O Privy pode ser combinado com provedores como Alchemy: o Privy gerencia as chaves, o Alchemy o RPC.

Verificando tokens no backend

Instale o SDK do servidor:

npm install @privy-io/server-auth

No backend, valide o JWT de cada requisição autenticada:

import { PrivyClient } from '@privy-io/server-auth';

const privy = new PrivyClient(
  process.env.PRIVY_APP_ID,
  process.env.PRIVY_APP_SECRET
);

export async function GET(req) {
  const auth = req.headers.get('authorization')?.replace('Bearer ', '');
  try {
    const claims = await privy.verifyAuthToken(auth);
    // claims.userId é o DID do usuário Privy
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Não Autorizado', { status: 401 });
  }
}

Use também privy.getUser(userId) para buscar dados completos do usuário, como contas vinculadas e metadados.

Exportando a carteira incorporada

O usuário pode exportar a chave privada via hook:

import { useExportWallet } from '@privy-io/react-auth';

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Exportar chave privada</button>;

O modal de exportação é seguro e seu app não acessa a chave diretamente.

Assinaturas de autorização e motor de políticas

Para operações sensíveis (grandes transferências, novos dispositivos), defina políticas no painel do Privy. O Privy pode exigir MFA, listas de permissão ou aprovações assinadas pelo backend. Veja o guia de chaves de autorização para detalhes. Combine isso com MFA (TOTP, SMS, passkey) para reforçar a segurança.

Webhooks

Receba eventos JSON sobre ciclo de vida do usuário e carteiras:

curl -X POST https://yourapp.com/webhooks/privy \
  -H "Content-Type: application/json" \
  -H "svix-id: msg_..." \
  -H "svix-signature: v1,..." \
  -d '{
    "type": "user.created",
    "user": { "id": "did:privy:...", "email": { "address": "[e-mail]" } }
  }'

Sempre valide o cabeçalho svix-signature com o segredo do painel antes de gravar qualquer dado.

Erros comuns e limites de taxa

Principais erros e como tratá-los:

• invalid_token: JWT expirado. Chame getAccessToken() de usePrivy antes de fazer a requisição (tokens duram 1h).
• 403 origin_not_allowed: domínio não autorizado. Adicione todos os domínios de produção e preview no painel do Privy.
• wallet_not_ready: tente acessar carteiras apenas quando ready for verdadeiro.
• Limite de taxa: 100 requisições/segundo/app na camada gratuita. Se atingir o limite, agrupe chamadas getUser ou use cache.

Use o Apidog para testar webhooks localmente: cole o payload, edite a assinatura e reenvie para seu backend até o handler funcionar.

Preços do Privy

• Gratuito: até 1.000 carteiras ativas/mês, login básico, carteiras EVM+Solana.
• Pro: US$ 149/mês, limites maiores, webhooks completos, ambiente de staging.
• Enterprise: SLA customizado, suporte dedicado, regras avançadas.

Confira privy.io/pricing para valores atualizados.

Testando a API do Privy com Apidog

Apesar do SDK cliente esconder detalhes HTTPS, toda verificação de token, busca de usuário e webhook é uma requisição REST. O Apidog facilita muito esse processo:

• Crie uma coleção Privy no Apidog.
• Configure ID e segredo como variáveis de ambiente.
• Teste endpoints como GET /api/v1/users/{userId} e POST /api/v1/users/{userId}/wallets sem sair da interface.

Salve payloads de webhook do painel e os envie para seu endpoint localmente. Automate testes: valide que JWTs válidos retornam usuário, expirados retornam 401. Baixe o Apidog gratuitamente. Se migrou do Postman, veja o guia de migração.

Perguntas Frequentes

Qual a diferença entre Privy, Web3Auth e Magic?

Todos oferecem carteiras incorporadas. O Privy foca em autenticação híbrida (e-mail + carteira + social) e em um motor de políticas avançado. Web3Auth é voltado para MPC; Magic aposta em magic-link. Escolha o Privy para onboarding rápido e controle granular.

O Privy suporta Solana?

Sim. Carteiras incorporadas funcionam na mainnet e devnet Solana, via getSolanaProvider(). Você pode integrar Solana e EVM no mesmo app.

Usuários podem usar suas próprias carteiras?

Sim. MetaMask, Coinbase Wallet, WalletConnect, Phantom e outros funcionam nativamente. O Privy trata todas como contas vinculadas.

O que acontece se o Privy sair do ar?

Usuários mantêm acesso às carteiras exportadas, já que a chave está no enclave do navegador. Para produção, ative a exportabilidade e documente um plano de contingência. Veja o guia de comparação de provedores para padrões de risco.

O Privy suporta MFA?

Sim. TOTP, SMS e passkeys integrados. MFA pode ser exigido para ações específicas via políticas.

O código roda client ou server-side?

Ambos. O SDK do cliente lida com UI e assinatura; o do servidor verifica tokens e busca dados. Nunca envie o segredo do app para o navegador.