Blog

Comment Utiliser l'API Privy: Wallets Intégrés et Authentification Sociale pour le Web3

Ashley Innocent

Ashley Innocent

23 April 2026

Comment Utiliser l'API Privy: Wallets Intégrés et Authentification Sociale pour le Web3

Apidog pour les entreprises

Déploiement sur site

SSO & RBAC

Conforme SOC 2

Découvrir Apidog Enterprise

L'intégration des utilisateurs à une application Web3 décourage encore la plupart des gens dès la première étape. Les phrases de récupération, les extensions de navigateur et les frais de gaz transforment une inscription en deux clics en une lutte de dix minutes. L'API Privy comble cette lacune en offrant à chaque nouvel utilisateur un portefeuille intégré derrière une connexion familière : e-mail, SMS, Google, Apple, ou un portefeuille existant comme MetaMask. Vous obtenez un utilisateur crypto-natif sans demander à quiconque d'installer une extension de navigateur.

Privy soutient désormais les portefeuilles pour Blackbird, Friend.tech, OpenSea et des milliers d'autres applications, et le produit couvre Ethereum, Solana et toute chaîne EVM. Ce guide vous présente le flux de travail complet du développeur : la création d'une application Privy, l'intégration du SDK React, la vérification des jetons sur le serveur, la signature des transactions avec des portefeuilles intégrés et l'envoi de webhooks. Si vous souhaitez également comparer des options comme la boîte à outils pour développeurs de MetaMask, gardez cette page ouverte et alternez entre les deux.

💡
Avant de lire le code, une note sur un outil. Apidog est la manière dont vous devriez inspecter chaque requête HTTPS que les SDK de Privy effectuent en arrière-plan. Dirigez votre application vers un proxy local, capturez la charge utile réelle et déboguez les échecs d'authentification en quelques secondes au lieu de suivre les journaux.

bouton

En bref

Qu'est-ce que l'API Privy ?

Privy est une plateforme d'authentification et d'infrastructure de portefeuille. Elle offre trois choses à votre application : une interface utilisateur de connexion, un portefeuille intégré provisionné par utilisateur et un ensemble de points de terminaison REST pour les vérifications côté serveur. Le portefeuille intégré réside dans une enclave sécurisée, de sorte que Privy ne voit jamais la clé privée, pas plus que votre backend. Les utilisateurs peuvent exporter leur clé plus tard s'ils souhaitent passer à un portefeuille auto-gardé ; cette option fait partie intégrante de l'argument de vente.

La plateforme facture par portefeuille actif mensuel, ce qui signifie que vous pouvez lancer un prototype gratuitement et faire évoluer les tarifs à mesure que l'adoption augmente. Le niveau gratuit couvre 1 000 utilisateurs actifs mensuels, Pro commence à 149 $ par mois, et Enterprise gère les SLA personnalisés.

Authentification et configuration

Commencez par privy.io et créez une nouvelle application depuis le tableau de bord. Vous obtiendrez deux valeurs importantes :

Définissez les méthodes de connexion autorisées (e-mail, SMS, Google, Apple, Farcaster, portefeuille), choisissez votre chaîne par défaut et ajoutez votre domaine à la liste des origines autorisées. Pour React, installez le SDK :

npm install @privy-io/react-auth

Enveloppez votre application dans 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>
  );
}

L'indicateur createOnLogin provisionne un portefeuille intégré la première fois qu'un utilisateur se connecte sans en avoir un. Vous contrôlez les chaînes prises en charge ; Solana est géré par une configuration solanaClusters séparée.

Points de terminaison principaux et appels SDK

Le SDK React de Privy gère la plupart des flux, de sorte que vous accédez rarement directement aux API REST brutes. Cependant, le SDK serveur et les charges utiles des webhooks utilisent le même format de jeton, donc connaître l'API sous-jacente est utile lorsque les choses tournent mal.

Déclencher la connexion et lire l'utilisateur

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

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

  if (!ready) return <p>Chargement...</p>;
  if (!authenticated) return <button onClick={login}>Se connecter</button>;

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

  return (
    <div>
      <p>Bonjour {user.email?.address ?? user.id}</p>
      <p>Portefeuille : {embedded?.address}</p>
      <button onClick={logout}>Se déconnecter</button>
    </div>
  );
}

useWallets renvoie tous les portefeuilles que l'utilisateur a liés, et le champ walletClientType vous indique celui que Privy a créé. C'est le modèle à suivre pour les portefeuilles intégrés Privy.

Signature d'une transaction

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

Pour Solana, remplacez getEthereumProvider par getSolanaProvider et passez une transaction sérialisée. Si vous souhaitez reproduire les modèles d'accès aux données de fournisseurs comme Alchemy, Privy fonctionne bien avec eux ; Privy gère la clé, Alchemy gère le RPC.

Vérification des jetons sur le serveur

Installez le SDK serveur :

npm install @privy-io/server-auth

Chaque requête authentifiée de votre frontend contient un jeton d'accès Privy (JWT). Vérifiez-le sur le serveur avant de faire confiance à un ID utilisateur :

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('Non autorisé', { status: 401 });
  }
}

Vous pouvez également récupérer l'objet utilisateur complet (`privy.getUser(userId)`) pour vérifier les comptes liés, les adresses de portefeuille et les métadonnées personnalisées.

Exporter un portefeuille intégré

Privy permet aux utilisateurs d'exporter leur clé privée à tout moment. L'expérience utilisateur se résume à un seul hook :

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

const { exportWallet } = useExportWallet();
<button onClick={() => exportWallet()}>Exporter la clé privée</button>;

Privy affiche une fenêtre modale iframe sécurisée ; votre application ne touche jamais au matériel de la clé.

Signatures d'autorisation et moteur de politique

Pour les opérations sensibles (transferts importants, connexions depuis un nouvel appareil), Privy prend en charge les **signatures d'autorisation**. Vous définissez une politique dans le tableau de bord, l'attachez à votre application, et Privy applique l'authentification multifacteur (MFA), les listes blanches ou les approbations signées par le serveur avant qu'une transaction ne soit exécutée. Les détails se trouvent dans le guide des clés d'autorisation Privy. Combiné aux options MFA (TOTP, SMS, clé d'accès), cela réduit la plupart des surfaces d'attaque de prise de contrôle de compte que les portefeuilles classiques laissent ouvertes.

Webhooks

Privy publie des événements JSON sur votre point de terminaison lors des changements de cycle de vie des utilisateurs et des portefeuilles :

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

Vérifiez l'en-tête `svix-signature` avec le secret du webhook depuis le tableau de bord avant d'écrire quoi que ce soit dans votre base de données.

Erreurs courantes et limites de débit

Quelques erreurs reviennent sans cesse :

Utilisez Apidog pour rejouer un webhook en échec localement. Collez la charge utile brute dans une requête, modifiez l'en-tête de signature et sollicitez votre serveur de développement à plusieurs reprises jusqu'à ce que le gestionnaire fonctionne.

Tarification de Privy

Consultez privy.io/pricing pour les chiffres actuels ; les niveaux évoluent à mesure que le produit se développe.

Tester l'API Privy avec Apidog

Le SDK client de Privy masque les appels HTTPS, mais chaque vérification de jeton, recherche d'utilisateur et webhook géré par votre backend est une requête REST standard. C'est là qu'Apidog prend tout son sens. Créez une collection Privy dans Apidog, insérez votre ID d'application et votre secret comme variables d'environnement, et accédez à des points de terminaison comme GET /api/v1/users/{userId} ou POST /api/v1/users/{userId}/wallets sans quitter l'outil.

Vous pouvez également enregistrer les charges utiles des webhooks depuis le tableau de bord, les sauvegarder en tant que requêtes Apidog et les rejouer via un tunnel local. Configurez des tests automatisés qui vérifient qu'un JWT valide renvoie un objet utilisateur et qu'un JWT expiré renvoie une erreur 401 ; exécutez-les à chaque déploiement. Téléchargez Apidog gratuitement et évitez les contorsions cURL. Si vous êtes déjà passé de Postman, le guide de flux de travail côte à côte couvre la migration complète.

bouton

FAQ

En quoi Privy diffère-t-il de Web3Auth ou Magic ?

Les trois proposent des portefeuilles intégrés, mais Privy met davantage l'accent sur l'authentification mixte (e-mail + portefeuille + réseaux sociaux) et un moteur de politique dont les grandes applications ont besoin. Web3Auth se concentre sur le partage de clés MPC ; Magic propose un produit de type 'magic link' plus large. Choisissez Privy lorsque vous souhaitez à la fois une interface utilisateur d'intégration claire et un contrôle précis sur les capacités des portefeuilles.

Privy prend-il en charge Solana ?

Oui. Les portefeuilles intégrés fonctionnent sur les mainnets et devnets Solana, et le SDK React expose getSolanaProvider() pour la signature et l'envoi de transactions. Vous pouvez configurer à la fois EVM et Solana dans la même application.

Les utilisateurs peuvent-ils utiliser leur propre portefeuille ?

Oui. MetaMask, Coinbase Wallet, WalletConnect, Phantom et des dizaines d'autres fonctionnent immédiatement. Privy considère les portefeuilles externes comme des comptes liés, de sorte que le même DID utilisateur possède les clés intégrées et externes.

Que se passe-t-il si Privy tombe en panne ?

Les utilisateurs conservent l'accès aux portefeuilles exportés, car la clé réside dans l'enclave du navigateur de l'utilisateur. Pour les applications de production, activez l'exportabilité du portefeuille et documentez un chemin de repli. Consultez le guide de comparaison des fournisseurs d'identité pour en savoir plus sur les modèles de risque liés aux fournisseurs.

Privy prend-il en charge l'authentification multifacteur (MFA) ?

Oui. TOTP, SMS et les clés d'accès sont tous intégrés, et vous pouvez exiger la MFA pour des actions spécifiques (envoi de jetons, exportation de portefeuilles) via le moteur de politique.

Le code de mon application s'exécute-t-il côté serveur ou côté client ?

Les deux. Le SDK client gère l'interface utilisateur de connexion et la signature ; le SDK serveur vérifie les jetons et récupère les données utilisateur. N'envoyez jamais le secret de votre application au navigateur.

Pratiquez le Design-first d'API dans Apidog

Découvrez une manière plus simple de créer et utiliser des API

S'inscrire gratuitementTélécharger
Comment Utiliser l'API Privy: Wallets Intégrés et Authentification Sociale pour le Web3