Cómo Usar la API de Privy: Billeteras Integradas y Autenticación Social para Web3

La incorporación de usuarios a una aplicación Web3 suele ser una barrera: frases semilla, extensiones de navegador y tarifas de gas complican lo que debería ser un registro sencillo. La API de Privy elimina esa fricción proveyendo a cada usuario una billetera incrustada tras un login tradicional (correo, SMS, Google, Apple o billetera existente como MetaMask). Así, puedes ofrecer una experiencia cripto-nativa desde el primer acceso sin requerir extensiones adicionales.

Prueba Apidog hoy

Privy ya respalda billeteras en aplicaciones como Blackbird, Friend.tech, OpenSea y miles más. Soporta Ethereum, Solana y cualquier cadena EVM. En esta guía verás cómo crear una app Privy, integrar el SDK de React, verificar tokens en tu backend, firmar transacciones con billeteras incrustadas y gestionar webhooks. Si quieres comparar con el kit de herramientas de MetaMask, mantén esta página abierta para referencias rápidas.

💡 Tip técnico: Usa Apidog para inspeccionar cualquier solicitud HTTPS generada por los SDK de Privy. Redirige tu app a un proxy local, captura la carga útil exacta y depura autenticaciones en segundos.

En resumen

• Privy unifica inicio de sesión (correo, SMS, redes sociales, billeteras externas) y billeteras incrustadas en un solo SDK.
• El SDK de React expone PrivyProvider, useLogin, useWallets y usePrivy para manejar autenticación y firma.
• @privy-io/server-auth permite verificar tokens en el backend y confiar en el ID de usuario en cada request.
• Compatible con Ethereum, Solana y otras EVM, exportabilidad opcional y soporte de firmas de autorización.
• Webhooks disponibles en eventos de usuario y billetera para mantener tu base de datos sincronizada.
• El motor de políticas de Privy permite MFA, listas blancas y reglas de transacción sin modificar tu código principal.

¿Qué es la API de Privy?

Privy es una plataforma de autenticación y billetera que te da:

1. Una UI de login lista para usar.
2. Una billetera incrustada y aislada por usuario.
3. Endpoints REST para verificación y operaciones del lado del servidor.

La billetera incrustada vive en un enclave seguro: Privy nunca accede a la clave privada. Los usuarios pueden exportar su clave cuando lo deseen, lo que facilita migraciones a billeteras autocustodiadas.

El modelo de precios es por billetera activa mensual: puedes lanzar un prototipo gratis (1,000 usuarios activos), pasar a Pro por $149/mes, o Enterprise para necesidades avanzadas.

Autenticación y configuración

1. Regístrate en privy.io y crea una nueva app.
2. Obtén tu App ID (clxxxxx...) y App Secret (para el backend).
3. Configura métodos de login habilitados (correo, SMS, Google, Apple, Farcaster, billetera), elige la cadena principal y agrega tus dominios a la whitelist.

Instala el SDK de React:

npm install @privy-io/react-auth

Envuélvelo en tu app:

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

El flag createOnLogin crea una billetera incrustada para usuarios nuevos. Puedes controlar las chains soportadas. Para Solana, usa la config solanaClusters.

Endpoints principales y uso del SDK

El SDK de React cubre la mayoría de los flujos, pero es útil entender los endpoints REST, especialmente para el backend y webhooks.

Login y lectura de usuario

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

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

  if (!ready) return <p>Loading...</p>;
  if (!authenticated) return <button onClick={login}>Sign in</button>;

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

  return (
    <div>
      <p>Hi {user.email?.address ?? user.id}</p>
      <p>Wallet: {embedded?.address}</p>
      <button onClick={logout}>Log out</button>
    </div>
  );
}

useWallets retorna todas las billeteras vinculadas. El campo walletClientType indica si fue creada por Privy. Este patrón aplica para las billeteras incrustadas de Privy.

Firma de una transacción

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, usa getSolanaProvider() y pasa la tx serializada. Privy es compatible con proveedores como Alchemy.

Verificación de tokens en el backend

Instala el SDK del servidor:

npm install @privy-io/server-auth

Verifica el JWT en cada request 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 es el DID del usuario Privy
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

También puedes obtener el usuario completo vía privy.getUser(userId) para validar cuentas y metadatos.

Exportación de billetera incrustada

Exporta la clave privada del usuario cuando lo requiera:

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Export private key</button>;

Privy gestiona el proceso en un modal seguro. Tu app nunca accede a la clave directamente.

Firmas de autorización y motor de políticas

Para acciones sensibles (transferencias grandes, nuevos dispositivos), usa firmas de autorización. Define políticas en el panel, así habilitas MFA, listas blancas o aprobaciones del servidor antes de permitir ciertas operaciones. Consulta la guía de claves de autorización de Privy.

Webhooks

Privy envía eventos JSON a tu endpoint para cambios de usuario y billetera:

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]" } }
  }'

Verifica svix-signature usando el secreto de webhook antes de actualizar tu BD.

Errores comunes y límites de tasa

Atención a estos errores frecuentes:

• invalid_token: El JWT ha expirado. Llama getAccessToken() desde usePrivy justo antes de la solicitud.
• 403 origin_not_allowed: Tu dominio no está en la whitelist. Añádelo en el panel de Privy.
• wallet_not_ready: useWallets accedido antes de que ready sea true. Siempre chequea la bandera ready.
• Límites de tasa: 100 req/s por app en el plan gratis. Si lo alcanzas, agrupa llamadas a getUser o usa caché.

Usa Apidog para simular webhooks y reproducir cargas localmente, editando headers de firma y validando tu handler.

Precios de Privy

• Gratis: Hasta 1,000 billeteras activas/mes, login principal, EVM y Solana.
• Pro: $149/mes, mayor límite MAW, webhooks completos, app de ensayo.
• Enterprise: SLA personalizado, soporte dedicado, reglas avanzadas.

Consulta privy.io/pricing para precios actualizados.

Probando la API de Privy con Apidog

El SDK de Privy oculta las llamadas HTTPS, pero para verificar tokens, obtener usuarios o probar webhooks, Apidog es ideal.

• Crea una colección de Privy en Apidog.
• Define ID de app y secreto como variables.
• Prueba endpoints como GET /api/v1/users/{userId} o POST /api/v1/users/{userId}/wallets directamente.
• Guarda cargas útiles de webhooks y prueba contra un túnel local.
• Automatiza tests para JWT válidos y expirados.
• Descarga Apidog gratis y evita cURL. Si migras desde Postman, sigue la guía de Apidog.

botón

Preguntas Frecuentes

¿En qué se diferencia Privy de Web3Auth o Magic?

Todos ofrecen billeteras incrustadas, pero Privy prioriza la autenticación combinada (correo + billetera + social) y un motor de políticas granular. Web3Auth se especializa en MPC, Magic en flujos de "enlace mágico". Privy es recomendable para onboarding limpio y control granular.

¿Privy es compatible con Solana?

Sí. Billeteras incrustadas en mainnet y devnet. El SDK expone getSolanaProvider() para firmar/enviar transacciones. Puedes usar EVM y Solana en la misma app.

¿Pueden los usuarios traer su propia billetera?

Sí. MetaMask, Coinbase Wallet, WalletConnect, Phantom, y más. Se tratan como cuentas vinculadas bajo el mismo DID de usuario.

¿Qué pasa si Privy deja de funcionar?

Los usuarios pueden exportar sus claves en todo momento, ya que están en el enclave del navegador. Para producción, habilita exportabilidad y documenta un plan B. Consulta la comparativa de proveedores de identidad.

¿Privy soporta MFA?

Sí: TOTP, SMS y passkeys. Puedes requerir MFA para ciertas acciones vía el motor de políticas.

¿Mi código corre en cliente o servidor?

Ambos. El SDK cliente maneja login y firma; el del servidor verifica tokens y obtiene datos. Nunca envíes tu App Secret al frontend.