Blog

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

Ashley Innocent

Ashley Innocent

23 April 2026

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

Apidog für Unternehmen

On-Premises Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

Das Onboarding von Benutzern in eine Web3-App schreckt die meisten Menschen immer noch beim ersten Schritt ab. Seed-Phrasen, Browser-Erweiterungen und Gasgebühren verwandeln eine Zwei-Klick-Anmeldung in einen zehnminütigen Kampf. Die Privy API schließt diese Lücke, indem sie jedem neuen Benutzer eine eingebettete Wallet hinter einem vertrauten Login bereitstellt: E-Mail, SMS, Google, Apple oder eine bestehende Wallet wie MetaMask. Sie erhalten einen krypto-nativen Benutzer, ohne jemanden zur Installation einer Browser-Erweiterung aufzufordern.

Privy unterstützt jetzt Wallets für Blackbird, Friend.tech, OpenSea und Tausende anderer Apps, und das Produkt umfasst Ethereum, Solana sowie jede EVM-Kette. Dieser Leitfaden führt Sie durch den gesamten Entwickler-Workflow: Erstellung einer Privy-App, Anbindung des React SDK, Überprüfung von Tokens auf dem Server, Signieren von Transaktionen mit eingebetteten Wallets und Bereitstellung von Webhooks. Wenn Sie auch Optionen wie das Entwickler-Toolkit von MetaMask vergleichen möchten, lassen Sie diese Seite geöffnet und springen Sie hin und her.

💡
Bevor Sie den Code lesen, ein Hinweis zum Tool. Mit Apidog sollten Sie jede HTTPS-Anfrage überprüfen, die die Privy SDKs im Hintergrund tätigen. Richten Sie Ihre App auf einen lokalen Proxy, erfassen Sie die tatsächliche Nutzlast und debuggen Sie Authentifizierungsfehler in Sekunden, anstatt Protokolle zu verfolgen.
button

TL;DR

Was ist die Privy API?

Privy ist eine Plattform für Authentifizierung und Wallet-Infrastruktur. Sie bietet Ihrer App drei Dinge: eine Login-Benutzeroberfläche, eine pro Benutzer bereitgestellte eingebettete Wallet und eine Reihe von REST-Endpunkten für serverseitige Überprüfungen. Die eingebettete Wallet befindet sich in einer sicheren Enklave, sodass Privy den privaten Schlüssel nie sieht und Ihr Backend ebenfalls nicht. Benutzer können ihren Schlüssel später exportieren, wenn sie zu einer Self-Custody-Wallet wechseln möchten; diese Optionalität ist ein wichtiger Bestandteil des Angebots.

Die Plattform berechnet pro monatlich aktiver Wallet, was bedeutet, dass Sie kostenlos einen Prototyp veröffentlichen und die Preise mit wachsender Akzeptanz skalieren können. Der kostenlose Tarif deckt 1.000 monatlich aktive Benutzer ab, Pro beginnt bei 149 $ pro Monat, und Enterprise bietet maßgeschneiderte SLAs.

Authentifizierung und Einrichtung

Beginnen Sie unter privy.io und erstellen Sie eine neue App über das Dashboard. Sie erhalten zwei wichtige Werte:

Legen Sie die erlaubten Login-Methoden fest (E-Mail, SMS, Google, Apple, Farcaster, Wallet), wählen Sie Ihre Standard-Kette und fügen Sie Ihre Domain zur Liste der erlaubten Ursprünge hinzu. Für React installieren Sie das SDK:

npm install @privy-io/react-auth

Umschließen Sie Ihre App mit 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>
  );
}

Das createOnLogin-Flag stellt eine eingebettete Wallet bereit, wenn sich ein Benutzer zum ersten Mal ohne eine solche anmeldet. Sie steuern die unterstützten Ketten; Solana wird unter einer separaten solanaClusters-Konfiguration verwaltet.

Kern-Endpunkte und SDK-Aufrufe

Das React SDK von Privy handhabt die meisten Abläufe, sodass Sie selten rohe REST-Anfragen tätigen müssen. Dennoch verwenden das Server SDK und die Webhook-Nutzlasten das gleiche Token-Format, daher hilft es, die zugrunde liegende API zu kennen, wenn etwas schiefgeht.

Login auslösen und 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>
  );
}

useWallets gibt jede Wallet zurück, die der Benutzer verknüpft hat, und das Feld walletClientType sagt Ihnen, welche davon Privy erstellt hat. Dies ist das Muster, dem Sie für eingebettete Privy Wallets folgen.

Eine 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 tauschen Sie getEthereumProvider gegen getSolanaProvider aus und übergeben eine serialisierte Transaktion. Wenn Sie Datenzugriffsmuster von Anbietern wie Alchemy widerspiegeln möchten, arbeitet Privy gut mit ihnen zusammen; Privy verwaltet den Schlüssel, Alchemy den RPC.

Tokens auf dem Server verifizieren

Installieren Sie das Server SDK:

npm install @privy-io/server-auth

Jede authentifizierte Anfrage von Ihrem Frontend enthält ein Privy-Zugriffstoken (JWT). Verifizieren Sie es auf dem Server, bevor Sie einer Benutzer-ID vertrauen:

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

Sie können auch das vollständige Benutzerobjekt (privy.getUser(userId)) abrufen, um verknüpfte Konten, Wallet-Adressen und benutzerdefinierte Metadaten zu überprüfen.

Eine eingebettete Wallet exportieren

Privy ermöglicht Benutzern jederzeit den Export ihres privaten Schlüssels. Die UX ist ein einzelner Hook:

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

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

Privy zeigt ein sicheres iFrame-Modal an; Ihre App berührt niemals das Schlüsselmaterial.

Autorisierungssignaturen und die Policy Engine

Für sensible Operationen (große Überweisungen, Logins von neuen Geräten) unterstützt Privy Autorisierungssignaturen. Sie definieren eine Richtlinie im Dashboard, verknüpfen sie mit Ihrer App, und Privy erzwingt MFA, Zulassungslisten oder vom Server signierte Genehmigungen, bevor eine Transaktion ausgeführt wird. Details finden Sie im Privy-Autorisierungsschlüssel-Leitfaden. In Kombination mit MFA-Optionen (TOTP, SMS, Passkey) schließt dies die meisten Angriffsflächen für Kontoübernahmen, die einfache Wallets offenlassen würden.

Webhooks

Privy sendet JSON-Ereignisse an Ihren Endpunkt bei Änderungen im Benutzer- und Wallet-Lebenszyklus:

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

Verifizieren Sie den svix-signature-Header mit dem Webhook-Geheimnis aus dem Dashboard, bevor Sie etwas in Ihre Datenbank schreiben.

Häufige Fehler und Ratenbegrenzungen

Einige Fehler treten immer wieder auf:

Verwenden Sie Apidog, um einen fehlgeschlagenen Webhook lokal erneut abzuspielen. Fügen Sie die rohe Nutzlast in eine Anfrage ein, bearbeiten Sie den Signatur-Header und senden Sie wiederholt Anfragen an Ihren Entwicklungsserver, bis der Handler funktioniert.

Privy Preise

Aktuelle Zahlen finden Sie unter privy.io/pricing; die Tarife ändern sich mit dem Wachstum des Produkts.

Die Privy API mit Apidog testen

Das Client SDK von Privy verbirgt die HTTPS-Aufrufe, aber jede Token-Verifizierung, Benutzerabfrage und jeder Webhook, den Ihr Backend verarbeitet, ist eine reguläre REST-Anfrage. Hier kommt Apidog ins Spiel. Erstellen Sie eine Privy-Sammlung in Apidog, fügen Sie Ihre App-ID und Ihr Geheimnis als Umgebungsvariablen ein und rufen Sie Endpunkte wie GET /api/v1/users/{userId} oder POST /api/v1/users/{userId}/wallets direkt im Tool auf.

Sie können auch Webhook-Nutzlasten vom Dashboard aufzeichnen, sie als Apidog-Anfragen speichern und diese gegen einen lokalen Tunnel wieder abspielen. Richten Sie automatisierte Tests ein, die überprüfen, ob ein gültiges JWT ein Benutzerobjekt zurückgibt und ein abgelaufenes JWT einen 401-Fehler zurückgibt; führen Sie diese bei jeder Bereitstellung aus. Laden Sie Apidog kostenlos herunter und ersparen Sie sich die cURL-Gymnastik. Wenn Sie bereits von Postman umgestiegen sind, deckt der Side-by-Side-Workflow-Leitfaden die vollständige Migration ab.

button

FAQ

Worin unterscheidet sich Privy von Web3Auth oder Magic?Alle drei bieten eingebettete Wallets an, aber Privy setzt stärker auf gemischte Authentifizierung (E-Mail + Wallet + Social) und eine Policy Engine, die größere Apps benötigen. Web3Auth konzentriert sich auf MPC-Schlüsselsplitting; Magic bietet ein breiteres Magic-Link-Produkt an. Wählen Sie Privy, wenn Sie sowohl eine saubere Onboarding-Benutzeroberfläche als auch eine feingranulare Kontrolle darüber wünschen, was Wallets tun können.

Unterstützt Privy Solana?Ja. Eingebettete Wallets funktionieren auf Solana Mainnet und Devnet, und das React SDK stellt getSolanaProvider() zum Signieren und Senden von Transaktionen bereit. Sie können sowohl EVM als auch Solana in derselben App konfigurieren.

Können Benutzer ihre eigene Wallet mitbringen?Ja. MetaMask, Coinbase Wallet, WalletConnect, Phantom und Dutzende andere funktionieren sofort. Privy behandelt externe Wallets als verknüpfte Konten, sodass dieselbe Benutzer-DID sowohl die eingebetteten als auch die externen Schlüssel besitzt.

Was passiert, wenn Privy ausfällt?Benutzer behalten den Zugriff auf exportierte Wallets, da der Schlüssel in der Browser-Enklave des Benutzers gespeichert ist. Für Produktions-Apps aktivieren Sie die Wallet-Exportierbarkeit und dokumentieren Sie einen Fallback-Pfad. Weitere Informationen zu Anbieter-Risikomustern finden Sie im Leitfaden zum Vergleich von Identitätsanbietern.

Unterstützt Privy MFA?Ja. TOTP, SMS und Passkeys sind alle integriert, und Sie können MFA für bestimmte Aktionen (Senden von Tokens, Exportieren von Wallets) über die Policy Engine vorschreiben.

Läuft der Code meiner App serverseitig oder clientseitig?Beides. Das Client SDK übernimmt die Login-Benutzeroberfläche und das Signieren; das Server SDK verifiziert Tokens und ruft Benutzerdaten ab. Geben Sie Ihr App-Geheimnis niemals an den Browser weiter.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenHerunterladen