Blog

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

Ashley Innocent

Ashley Innocent

23 April 2026

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

Apidog para empresas

Despliegue local

SSO & RBAC

Conforme con SOC 2

Explorar Apidog Enterprise

La incorporación de usuarios a una aplicación Web3 sigue alejando a la mayoría de las personas en el primer paso. Las frases semilla, las extensiones de navegador y las tarifas de gas convierten un registro de dos toques en una lucha de diez minutos. La API de Privy soluciona esa brecha entregando a cada nuevo usuario una billetera incrustada detrás de un inicio de sesión familiar: correo electrónico, SMS, Google, Apple o una billetera existente como MetaMask. Obtienes un usuario cripto-nativo sin pedirle a nadie que instale una extensión de navegador.

Privy ahora respalda billeteras para Blackbird, Friend.tech, OpenSea y miles de otras aplicaciones, y el producto abarca Ethereum, Solana y cualquier cadena EVM. Esta guía recorre el flujo de trabajo completo del desarrollador: crear una aplicación Privy, conectar el SDK de React, verificar tokens en el servidor, firmar transacciones con billeteras incrustadas y enviar webhooks. Si también deseas comparar opciones como el kit de herramientas para desarrolladores de MetaMask, mantén esta página abierta y salta de un lado a otro.

💡
Antes de leer el código, una nota sobre una herramienta. Apidog es cómo deberías inspeccionar cada solicitud HTTPS que los SDK de Privy realizan internamente. Apunta tu aplicación a un proxy local, captura la carga útil real y depura fallos de autenticación en segundos en lugar de rastrear los registros.
botón

En resumen

¿Qué es la API de Privy?

Privy es una plataforma de infraestructura de autenticación y billetera. Ofrece a tu aplicación tres cosas: una interfaz de usuario de inicio de sesión, una billetera incrustada provisionada por usuario y un conjunto de endpoints REST para verificaciones del lado del servidor. La billetera incrustada reside en un enclave seguro, por lo que Privy nunca ve la clave privada y tu backend tampoco. Los usuarios pueden exportar su clave más tarde si desean pasar a una billetera de autocustodia; esa opcionalidad es una parte importante de la propuesta.

La plataforma cobra por billetera activa mensual, lo que significa que puedes lanzar un prototipo gratis y escalar el precio a medida que crece la tracción. El nivel gratuito cubre 1,000 usuarios activos mensuales, Pro comienza en $149 al mes y Enterprise gestiona SLA personalizados.

Autenticación y configuración

Comienza en privy.io y crea una nueva aplicación desde el panel de control. Obtendrás dos valores que te interesan:

Configura los métodos de inicio de sesión permitidos (correo electrónico, SMS, Google, Apple, Farcaster, billetera), elige tu cadena predeterminada e introduce tu dominio en la lista de orígenes permitidos. Para React, instala el SDK:

npm install @privy-io/react-auth

Envuelve tu aplicación en 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>
  );
}

El flag createOnLogin provisiona una billetera incrustada la primera vez que un usuario inicia sesión sin una. Tú controlas las cadenas soportadas; Solana reside bajo una configuración solanaClusters separada.

Endpoints principales y llamadas al SDK

El SDK de React de Privy maneja la mayoría de los flujos, por lo que rara vez accedes directamente a REST. Aun así, el SDK del servidor y las cargas útiles de los webhooks utilizan el mismo formato de token, por lo que conocer la API subyacente ayuda cuando las cosas no van bien.

Activación del inicio de sesión y lectura del 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 devuelve cada billetera que el usuario ha vinculado, y el campo walletClientType te indica cuál creó Privy. Este es el patrón que sigues 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, cambia getEthereumProvider por getSolanaProvider y pasa una transacción serializada. Si deseas replicar patrones de acceso a datos de proveedores como Alchemy, Privy se integra perfectamente con ellos; Privy gestiona la clave, Alchemy gestiona el RPC.

Verificación de tokens en el servidor

Instala el SDK del servidor:

npm install @privy-io/server-auth

Cada solicitud autenticada desde tu frontend lleva un token de acceso de Privy (JWT). Verifícalo en el servidor antes de confiar en cualquier ID de usuario:

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 is the Privy user DID
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

También puedes obtener el objeto de usuario completo (privy.getUser(userId)) para verificar cuentas vinculadas, direcciones de billetera y metadatos personalizados.

Exportación de una billetera incrustada

Privy permite a los usuarios exportar su clave privada en cualquier momento. La UX es un único hook:

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

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

Privy muestra un modal seguro en un iframe; tu aplicación nunca toca el material de la clave.

Firmas de autorización y el motor de políticas

Para operaciones sensibles (grandes transferencias, inicios de sesión en nuevos dispositivos), Privy admite firmas de autorización. Defines una política en el panel de control, la adjuntas a tu aplicación y Privy aplica MFA, listas blancas o aprobaciones firmadas por el servidor antes de que una transacción se complete. Los detalles se encuentran en la guía de claves de autorización de Privy. Combinado con las opciones de MFA (TOTP, SMS, passkey), esto cierra la mayor parte de la superficie de ataque de apropiación de cuentas que las billeteras simples dejan abiertas.

Webhooks

Privy publica eventos JSON en tu endpoint sobre los cambios en el ciclo de vida del usuario y la 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": "a@b.com" } }
  }'

Verifica el encabezado svix-signature con el secreto del webhook desde el panel de control antes de escribir cualquier cosa en tu base de datos.

Errores comunes y límites de tasa

Algunos errores se repiten con frecuencia:

Usa Apidog para reproducir un webhook fallido localmente. Pega la carga útil sin procesar en una solicitud, edita el encabezado de la firma y envía solicitudes a tu servidor de desarrollo repetidamente hasta que el manejador funcione.

Precios de Privy

Consulta privy.io/pricing para ver los números actuales; los niveles cambian a medida que el producto crece.

Probando la API de Privy con Apidog

El SDK del cliente de Privy oculta las llamadas HTTPS, pero cada verificación de token, búsqueda de usuario y webhook que tu backend maneja es una solicitud REST regular. Ahí es donde Apidog se gana su lugar. Crea una colección de Privy en Apidog, inserta tu ID de aplicación y secreto como variables de entorno, y accede a endpoints como GET /api/v1/users/{userId} o POST /api/v1/users/{userId}/wallets sin salir de la herramienta.

También puedes registrar cargas útiles de webhook desde el panel de control, guardarlas como solicitudes de Apidog y reproducirlas contra un túnel local. Configura pruebas automatizadas que verifiquen que un JWT válido devuelve un objeto de usuario y que uno caducado devuelve 401; ejecútalas en cada despliegue. Descarga Apidog gratis y salta las acrobacias de cURL. Si ya dejaste Postman, la guía de flujo de trabajo lado a lado cubre la migración completa.

botón

Preguntas Frecuentes

¿En qué se diferencia Privy de Web3Auth o Magic?Los tres ofrecen billeteras incrustadas, pero Privy se inclina más hacia la autenticación mixta (correo electrónico + billetera + social) y un motor de políticas que las aplicaciones más grandes necesitan. Web3Auth se centra en la división de claves MPC; Magic ofrece un producto de "enlace mágico" más amplio. Elige Privy cuando quieras una UI de incorporación limpia y un control granular sobre lo que las billeteras pueden hacer.

¿Privy es compatible con Solana?Sí. Las billeteras incrustadas funcionan en la red principal y devnet de Solana, y el SDK de React expone getSolanaProvider() para firmar y enviar transacciones. Puedes configurar tanto EVM como Solana en la misma aplicación.

¿Pueden los usuarios traer su propia billetera?Sí. MetaMask, Coinbase Wallet, WalletConnect, Phantom y docenas de otras funcionan de forma inmediata. Privy trata las billeteras externas como cuentas vinculadas, por lo que el mismo DID de usuario posee tanto las claves incrustadas como las externas.

¿Qué ocurre si Privy deja de funcionar?Los usuarios conservan el acceso a las billeteras exportadas, ya que la clave reside en el enclave del navegador del usuario. Para aplicaciones de producción, activa la exportabilidad de la billetera y documenta una ruta de respaldo. Consulta la guía para comparar proveedores de identidad para obtener más información sobre los patrones de riesgo del proveedor.

¿Privy es compatible con MFA?Sí. TOTP, SMS y passkeys están integrados, y puedes requerir MFA para acciones específicas (envío de tokens, exportación de billeteras) a través del motor de políticas.

¿El código de mi aplicación se ejecuta en el lado del servidor o del cliente?Ambos. El SDK del cliente maneja la UI de inicio de sesión y la firma; el SDK del servidor verifica los tokens y recupera los datos del usuario. Nunca envíes el secreto de tu aplicación al navegador.

Practica el diseño de API en Apidog

Descubre una forma más fácil de construir y usar APIs

Registrarse gratisDescargar