Blog

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

Ashley Innocent

Ashley Innocent

23 abril 2026

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

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

A integração de usuários a um aplicativo Web3 ainda afasta a maioria das pessoas no primeiro passo. Frases sementes, extensões de navegador e taxas de gás transformam um cadastro de dois toques em uma luta de dez minutos. A API do Privy resolve essa lacuna, fornecendo a cada novo usuário uma carteira incorporada atrás de um login familiar: e-mail, SMS, Google, Apple ou uma carteira existente como MetaMask. Você obtém um usuário nativo de cripto sem pedir a ninguém para instalar uma extensão de navegador.

O Privy agora oferece suporte a carteiras para Blackbird, Friend.tech, OpenSea e milhares de outros aplicativos, e o produto abrange Ethereum, Solana e qualquer cadeia EVM. Este guia detalha o fluxo de trabalho completo do desenvolvedor: criando um aplicativo Privy, configurando o SDK React, verificando tokens no servidor, assinando transações com carteiras incorporadas e enviando webhooks. Se você também quiser comparar opções como o kit de ferramentas para desenvolvedores do MetaMask, mantenha esta página aberta e alterne entre elas.

💡
Antes de ler o código, uma observação sobre a ferramenta. O Apidog é como você deve inspecionar cada requisição HTTPS que os SDKs do Privy fazem nos bastidores. Aponte seu aplicativo para um proxy local, capture a carga útil real e depure falhas de autenticação em segundos, em vez de analisar logs.
botão

TL;DR

O que é a API do Privy?

O Privy é uma plataforma de infraestrutura de autenticação e carteira. Ele oferece ao seu aplicativo três coisas: uma UI de login, uma carteira incorporada provisionada por usuário e um conjunto de endpoints REST para verificações do lado do servidor. A carteira incorporada reside em um enclave seguro, então o Privy nunca vê a chave privada e seu backend também não. Os usuários podem exportar sua chave mais tarde se quiserem migrar para uma carteira de auto-custódia; essa opcionalidade é uma grande parte da proposta.

A plataforma cobra por carteira ativa mensal, o que significa que você pode lançar um protótipo gratuitamente e escalar o preço à medida que a adesão cresce. A camada gratuita cobre 1.000 usuários ativos mensais, o Pro começa em US$ 149 por mês e o Enterprise lida com SLAs personalizados.

Autenticação e configuração

Comece em privy.io e crie um novo aplicativo no painel. Você obterá dois valores importantes:

Defina os métodos de login permitidos (e-mail, SMS, Google, Apple, Farcaster, carteira), escolha sua cadeia padrão e adicione seu domínio à lista de origens permitidas. Para React, instale o SDK:

npm install @privy-io/react-auth

Empacote seu aplicativo em 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 provisiona uma carteira incorporada na primeira vez que um usuário faz login sem uma. Você controla as cadeias suportadas; Solana reside sob uma configuração `solanaClusters` separada.

Endpoints principais e chamadas do SDK

O SDK React do Privy lida com a maioria dos fluxos, então você raramente acessa o REST bruto. Ainda assim, o SDK do servidor e os payloads de webhook usam o mesmo formato de token, então conhecer a API subjacente ajuda quando as coisas dão errado.

Acionando o login e lendo o 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>
  );
}

useWallets retorna todas as carteiras que o usuário vinculou, e o campo walletClientType informa qual delas o Privy criou. Este é o padrão que você segue para carteiras incorporadas do Privy.

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, troque getEthereumProvider por getSolanaProvider e passe uma transação serializada. Se você quiser espelhar padrões de acesso a dados de provedores como Alchemy, o Privy funciona bem junto a eles; o Privy gerencia a chave, o Alchemy gerencia o RPC.

Verificando tokens no servidor

Instale o SDK do servidor:

npm install @privy-io/server-auth

Cada requisição autenticada do seu frontend carrega um token de acesso Privy (JWT). Verifique-o no servidor antes de confiar em qualquer ID de usuário:

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 });
  }
}

Você também pode buscar o objeto de usuário completo (`privy.getUser(userId)`) para verificar contas vinculadas, endereços de carteira e metadados personalizados.

Exportando uma carteira incorporada

O Privy permite que os usuários exportem sua chave privada a qualquer momento. A UX é um único hook:

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

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

O Privy exibe um modal de iframe seguro; seu aplicativo nunca toca no material da chave.

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

Para operações sensíveis (grandes transferências, logins de novos dispositivos), o Privy suporta assinaturas de autorização. Você define uma política no painel, a anexa ao seu aplicativo, e o Privy impõe MFA, listas de permissão ou aprovações assinadas pelo servidor antes que uma transação seja concluída. Os detalhes estão no guia de chaves de autorização do Privy. Combinado com as opções de MFA (TOTP, SMS, passkey), isso fecha a maioria das vulnerabilidades de tomada de conta que as carteiras comuns deixam abertas.

Webhooks

O Privy publica eventos JSON para o seu endpoint nas mudanças de ciclo de vida do usuário e da carteira:

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": "a@b.com" } }
  }'

Verifique o cabeçalho `svix-signature` com o segredo do webhook do painel antes de gravar qualquer coisa em seu banco de dados.

Erros comuns e limites de taxa

Alguns erros aparecem repetidamente:

Use Apidog para reproduzir um webhook com falha localmente. Cole o payload bruto em uma requisição, edite o cabeçalho da assinatura e acione seu servidor de desenvolvimento repetidamente até que o manipulador seja bem-sucedido.

Preços do Privy

Verifique privy.io/pricing para os números atuais; os níveis mudam conforme o produto cresce.

Testando a API do Privy com Apidog

O SDK cliente do Privy oculta as chamadas HTTPS, mas cada verificação de token, busca de usuário e webhook que seu backend manipula é uma requisição REST regular. É aí que o Apidog se destaca. Crie uma coleção Privy no Apidog, adicione seu ID e segredo do aplicativo como variáveis de ambiente e acesse endpoints como `GET /api/v1/users/{userId}` ou `POST /api/v1/users/{userId}/wallets` sem sair da ferramenta.

Você também pode registrar payloads de webhook do painel, salvá-los como requisições do Apidog e reproduzi-los contra um túnel local. Configure testes automatizados que verificam se um JWT válido retorna um objeto de usuário e um expirado retorna 401; execute-os em cada deploy. Baixe o Apidog gratuitamente e evite as acrobacias do cURL. Se você já migrou do Postman, o guia de fluxo de trabalho lado a lado cobre a migração completa.

botão

Perguntas Frequentes

Qual a diferença entre Privy, Web3Auth e Magic?Todos os três oferecem carteiras incorporadas, mas o Privy se inclina mais para autenticação mista (e-mail + carteira + social) e um motor de políticas que aplicativos maiores necessitam. O Web3Auth foca na divisão de chaves MPC; o Magic oferece um produto de magic-link mais amplo. Escolha o Privy quando você deseja uma UI de integração limpa e controle granular sobre o que as carteiras podem fazer.

O Privy suporta Solana?Sim. Carteiras incorporadas funcionam na mainnet e devnet de Solana, e o SDK React expõe getSolanaProvider() para assinar e enviar transações. Você pode configurar tanto EVM quanto Solana no mesmo aplicativo.

Os usuários podem trazer sua própria carteira?Sim. MetaMask, Coinbase Wallet, WalletConnect, Phantom e dezenas de outros funcionam imediatamente. O Privy trata carteiras externas como contas vinculadas, então o mesmo DID de usuário possui as chaves incorporadas e externas.

O que acontece se o Privy sair do ar?Os usuários mantêm acesso às carteiras exportadas, já que a chave reside no enclave do navegador do usuário. Para aplicativos de produção, ative a exportabilidade da carteira e documente um caminho de fallback. Consulte o guia para comparar provedores de identidade para mais informações sobre padrões de risco de fornecedores.

O Privy suporta MFA?Sim. TOTP, SMS e passkeys estão todos integrados, e você pode exigir MFA para ações específicas (enviar tokens, exportar carteiras) através do motor de políticas.

O código do meu aplicativo está rodando no lado do servidor ou no lado do cliente?Ambos. O SDK do cliente lida com a UI de login e a assinatura; o SDK do servidor verifica tokens e busca dados do usuário. Nunca envie o segredo do seu aplicativo para o navegador.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar