Emre Demir

Posted on Apr 23 • Originally published at apidog.com

Privy API Nutzung: Embedded Wallets & Social Auth für Web3

Das Onboarding von Benutzern in Web3-Apps bleibt eine Hürde: Seed-Phrasen, Browser-Erweiterungen und Gasgebühren machen aus einer einfachen Anmeldung einen komplexen Prozess. Die Privy API vereinfacht das, indem sie neuen Nutzern eine eingebettete Wallet hinter vertrauten Login-Methoden (E-Mail, SMS, Google, Apple, MetaMask usw.) bereitstellt. So erhalten Sie einen krypto-nativen Benutzer, ohne ihn zur Installation einer Browser-Erweiterung zu zwingen.

Teste Apidog noch heute

Privy unterstützt Wallets für Blackbird, Friend.tech, OpenSea und viele weitere Apps und deckt Ethereum, Solana sowie alle EVM-Ketten ab. In diesem Leitfaden lernst du: Privy-App einrichten, React SDK anbinden, Token-Überprüfung auf dem Server, Transaktionen mit eingebetteten Wallets signieren und Webhooks nutzen. Wenn du das MetaMask Entwickler-Toolkit vergleichen möchtest, behalte diese Seite offen.

💡Mit Apidog kannst du jede HTTPS-Anfrage, die das Privy SDK im Hintergrund sendet, analysieren. Route deine App durch einen lokalen Proxy, zeichne Payloads auf und debugge Authentifizierungsfehler in Sekunden – ohne Logfiles zu durchsuchen.

TL;DR

Privy kombiniert eingebettete Wallets, E-Mail-, SMS-, Social- und externe Wallet-Logins in einem SDK.
Das React SDK bietet Hooks wie PrivyProvider, useLogin, useWallets und usePrivy für Authentifizierung und Signatur.
Mit @privy-io/server-auth prüfst du Zugriffstokens im Backend und kannst Benutzer eindeutig identifizieren.
Wallets unterstützen Ethereum, Solana und andere EVM-Ketten. Export und Autorisierungssignaturen sind möglich.
Webhooks benachrichtigen bei Benutzer- und Wallet-Events, damit deine DB synchron bleibt.
Über die Policy Engine kannst du MFA, Zulassungslisten und Transaktionsregeln ohne App-Code-Verzweigungen implementieren.

Was ist die Privy API?

Privy bietet Authentifizierungs- und Wallet-Infrastruktur für Apps: eine Login-UI, pro Benutzer eine eingebettete Wallet und REST-APIs für serverseitige Prüfungen. Die Wallet liegt in einer sicheren Enklave – weder Privy noch dein Backend sehen den Private Key. Nutzer können den Schlüssel jederzeit exportieren, um auf Self-Custody-Wallets zu wechseln.

Die Abrechnung erfolgt pro monatlich aktiver Wallet (MAW). Das Free-Tier deckt 1.000 MAWs ab, Pro startet bei 149 $/Monat, Enterprise mit individuellen SLAs.

Authentifizierung und Einrichtung

Erstelle unter privy.io eine neue App.
Notiere dir:
- App-ID (clxxxxx...) für das Client SDK
- App-Geheimnis für das Server SDK
Konfiguriere Login-Methoden (E-Mail, SMS, Google, Apple, Farcaster, Wallet), Standard-Chain und erlaubte Domains.

React SDK installieren:

npm install @privy-io/react-auth

App mit PrivyProvider umschließen:

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

Mit createOnLogin erhalten Nutzer ohne Wallet beim ersten Login automatisch eine eingebettete Wallet. Solana-Cluster werden separat via solanaClusters konfiguriert.

Kern-Endpunkte und SDK-Aufrufe

Das React SDK übernimmt den Großteil – REST-APIs brauchst du meist nur fürs Backend oder Troubleshooting.

Login auslösen & Benutzerdaten lesen

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

Mit useWallets bekommst du alle Wallets des Nutzers. Das Feld walletClientType zeigt, welche Wallet von Privy stammt. Siehe auch eingebettete Privy Wallets.

Transaktion signieren

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

Für Solana: getSolanaProvider() statt getEthereumProvider() und eine serialisierte Transaktion übergeben. Privy arbeitet problemlos mit RPC-Anbietern wie Alchemy zusammen.

Tokens auf dem Server verifizieren

Server SDK installieren:

npm install @privy-io/server-auth

JWT vom Frontend auf dem Server prüfen:

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

Für weitere Daten: privy.getUser(userId) liefert verknüpfte Accounts, Wallets und Metadaten.

Eingebettete Wallet exportieren

Benutzern den Private Key bereitstellen:

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

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

Privy zeigt dazu ein sicheres Modal; Schlüsselmaterial bleibt geschützt.

Autorisierungssignaturen & Policy Engine

Für kritische Aktionen (z.B. hohe Überweisungen, neue Geräte) kannst du Autorisierungssignaturen erzwingen: Definiere im Dashboard eine Policy, verknüpfe sie mit deiner App. Privy setzt dann MFA, Zulassungslisten oder serverseitige Freigaben durch, bevor Transaktionen möglich sind. Details im Privy-Autorisierungsschlüssel-Leitfaden.

Webhooks

Privy informiert deinen Endpunkt über User-/Wallet-Events:

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

Prüfe den svix-signature-Header mit dem Webhook-Secret, bevor du Änderungen an deiner DB vornimmst.

Häufige Fehler und Ratenbegrenzungen

Typische Stolperfallen:

invalid_token: JWT abgelaufen – rufe getAccessToken() vor jeder Anfrage auf.
403 origin_not_allowed: Deployment-URL fehlt im Privy-Dashboard – Domain whitelisten.
wallet_not_ready: useWallets vor ready verwendet – Zugriffe immer mit ready schützen.
Ratenbegrenzung: 100 Requests/Sekunde/App im Free-Tier – ggf. getUser-Aufrufe bündeln oder cachen.

Mit Apidog kannst du fehlgeschlagene Webhooks lokal nachspielen: Payload einfügen, Signatur anpassen und Requests bis zum funktionierenden Handler wiederholen.

Privy Preise

Kostenlos: Bis 1.000 monatlich aktive Wallets, Kern-Logins, eingebettete Wallets auf EVM + Solana.
Pro: 149 $/Monat, mehr MAWs, komplette Webhook-Suite, Staging-App.
Enterprise: Individuelle SLA, dedizierter Support, Policy-Engine-Regeln nach Maß.

Aktuelle Preise unter privy.io/pricing.

Die Privy API mit Apidog testen

Das Privy Client SDK kapselt die HTTPS-Calls, aber Token-Prüfung, User-Abfragen und Webhooks laufen über REST. Hier hilft Apidog:

Lege eine Privy-Sammlung in Apidog an.
Trage App-ID und Secret als Umgebungsvariablen ein.
Teste Endpunkte wie GET /api/v1/users/{userId} oder POST /api/v1/users/{userId}/wallets direkt im Tool.
Webhook-Nutzlasten vom Dashboard speichern und lokal gegen deinen Dev-Server abspielen.
Automatisierte Tests: Prüfe, ob ein gültiges JWT ein User-Objekt liefert und ein abgelaufenes JWT einen 401-Fehler bringt – bei jedem Deployment.

Lade Apidog kostenlos herunter und erspare dir cURL-Skripte. Wenn du schon von Postman wechselst, hilft der Side-by-Side-Workflow-Leitfaden.

FAQ

Worin unterscheidet sich Privy von Web3Auth oder Magic?

Alle drei bieten eingebettete Wallets. Privy legt den Fokus stärker auf gemischte Authentifizierung (E-Mail + Wallet + Social) und eine Policy Engine für größere Apps. Web3Auth setzt auf MPC-Schlüsselsplitting, Magic auf Magic-Link-Produkte. Wähle Privy, wenn du ein cleanes Onboarding und granulare Kontrolle über Wallet-Operationen willst.

Unterstützt Privy Solana?

Ja, eingebettete Wallets funktionieren auf Solana Mainnet/Devnet. Über das React SDK erhältst du mit getSolanaProvider() Zugriff auf Signatur- und Transaktionsfunktionen. EVM und Solana sind parallel nutzbar.

Können Benutzer ihre eigene Wallet mitbringen?

Ja. MetaMask, Coinbase Wallet, WalletConnect, Phantom etc. funktionieren direkt. Externe Wallets werden als verknüpfte Accounts geführt, die User-DID bleibt identisch.

Was passiert, wenn Privy ausfällt?

User behalten Zugriff auf exportierte Wallets, da der Key in der Browser-Enklave gespeichert ist. Für produktive Apps: Wallet-Exportierbarkeit aktivieren und Fallbacks dokumentieren. Mehr zu Risiko-Mustern im Vergleich von Identitätsanbietern.

Unterstützt Privy MFA?

Ja. TOTP, SMS und Passkeys sind integriert. MFA kann über die Policy Engine gezielt für Aktionen wie Token-Transfers oder Wallet-Export verlangt werden.

Läuft mein App-Code client- oder serverseitig?

Beides: Das Client SDK übernimmt UI und Signaturen, das Server SDK verifiziert Tokens und holt Benutzerdaten. Das App-Secret niemals an den Browser weitergeben.

DEV Community