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

L'intégration des utilisateurs dans une application Web3 reste un obstacle majeur : phrases de récupération, extensions de navigateur et frais de gaz rendent l'inscription complexe. L'API Privy simplifie ce processus en fournissant à chaque utilisateur un portefeuille intégré, accessible via une connexion e-mail, SMS, Google, Apple ou un portefeuille existant comme MetaMask. Ainsi, vous créez un utilisateur crypto-natif sans extension à installer.

Essayez Apidog dès aujourd'hui

Privy prend en charge les portefeuilles pour Blackbird, Friend.tech, OpenSea et de nombreuses autres applications sur Ethereum, Solana et toutes les chaînes EVM. Ce guide couvre les étapes pratiques : création d'une application Privy, intégration du SDK React, vérification des jetons côté serveur, signature de transactions, gestion des webhooks. Pour comparer avec la boîte à outils MetaMask, gardez cette page à portée de main.

💡 Avant de lire le code : Apidog est l'outil recommandé pour inspecter chaque requête HTTPS des SDK Privy. Passez par un proxy local, capturez les payloads réels et déboguez l'authentification en quelques secondes.

En bref

• Privy regroupe portefeuilles intégrés, connexion e-mail/SMS/social, et portefeuilles externes sous un seul SDK.
• Le SDK React expose les hooks PrivyProvider, useLogin, useWallets et usePrivy pour la gestion complète du login et de la signature.
• @privy-io/server-auth permet de vérifier les jetons d'accès sur votre backend.
• Les portefeuilles supportent Ethereum, Solana, autres chaînes EVM, avec exportabilité et signatures d'autorisation.
• Les webhooks notifient la création/utilisation des comptes et portefeuilles pour synchroniser votre base de données.
• Le moteur de politique Privy ajoute MFA, listes blanches et règles de transaction sans modifier votre code applicatif.

Qu'est-ce que l'API Privy ?

Privy fournit à votre application une UI de connexion, un portefeuille intégré par utilisateur, ainsi que des endpoints REST pour la vérification côté serveur. Le portefeuille intégré reste dans une enclave sécurisée : ni Privy, ni votre backend n'accèdent à la clé privée. L'utilisateur peut exporter sa clé pour migrer vers un portefeuille auto-gardé.

La tarification dépend du nombre de portefeuilles actifs par mois. Le plan gratuit couvre 1 000 utilisateurs actifs, Pro commence à 149 $/mois, Enterprise propose des SLA personnalisés.

Authentification et configuration

1. Rendez-vous sur privy.io et créez une application depuis le dashboard.
2. Récupérez :
   • ID d'application (clxxxxx...) pour le SDK client
   • Secret d'application pour le SDK serveur
3. Définissez les méthodes de connexion (e-mail, SMS, Google, Apple, Farcaster, portefeuille), la chaîne par défaut, et ajoutez votre domaine en origine autorisée.

Installation côté React :

npm install @privy-io/react-auth

Enveloppez votre application avec 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'option createOnLogin provisionne automatiquement un portefeuille intégré à la première connexion d'un utilisateur sans wallet. Pour Solana, configurez solanaClusters séparément.

Points de terminaison principaux et appels SDK

Le SDK React gère la plupart des flux courants. Les appels directs à l'API REST sont nécessaires surtout côté serveur ou pour le traitement des webhooks.

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

Le hook useWallets liste tous les portefeuilles liés. Le champ walletClientType indique le portefeuille intégré Privy. Ce pattern s'applique aussi aux 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 transmettez une transaction sérialisée. Privy gère la clé, vous pouvez connecter des fournisseurs comme Alchemy pour le RPC.

Vérification des jetons sur le serveur

Installez le SDK serveur :

npm install @privy-io/server-auth

Vérifiez le JWT reçu en backend :

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 correspond au DID utilisateur Privy
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Non autorisé', { status: 401 });
  }
}

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

Exporter un portefeuille intégré

L'utilisateur peut exporter sa clé privée à tout moment :

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

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

Privy affiche alors une modale iframe sécurisée ; votre code n'accède jamais directement à la clé.

Signatures d'autorisation et moteur de politique

Pour les opérations sensibles (transferts importants, nouveaux appareils), activez les signatures d'autorisation. Définissez votre politique dans le dashboard Privy, attachez-la à l'app, et Privy gère MFA, listes blanches, ou approbations serveur avant d'exécuter la transaction. Voir le guide des clés d'autorisation Privy pour les détails.

Webhooks

Privy envoie des événements JSON sur votre endpoint aux changements du cycle utilisateur/portefeuille :

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

Vérifiez la signature (svix-signature) avec le secret webhook avant d'écrire dans votre base de données.

Erreurs courantes et limites de débit

• invalid_token : JWT expiré côté frontend. Rafraîchissez avec getAccessToken() juste avant la requête (valide 1h).
• 403 origin_not_allowed : Domaine non listé dans Privy. Ajoutez vos URLs (production/prévisualisation) dans le dashboard.
• wallet_not_ready : Usage de useWallets avant que ready ne soit à true. Attendez toujours l'état prêt.
• Limites de débit : 100 requêtes/s/app sur le plan gratuit. Groupez/cachez les appels si besoin.

Pour rejouer un webhook localement, utilisez Apidog : collez la payload brute, ajustez la signature, et testez jusqu'à valider votre handler.

Tarification de Privy

• Gratuit : Jusqu'à 1 000 wallets actifs, logins de base, intégration EVM+Solana.
• Pro : 149 $/mois, quotas supérieurs, webhooks avancés, app de staging.
• Entreprise : SLA, support dédié, règles de politique personnalisées.

Consultez privy.io/pricing pour les tarifs à jour.

Tester l'API Privy avec Apidog

Le SDK client masque les requêtes HTTPS, mais chaque vérification de jeton, recherche d’utilisateur ou webhook backend correspond à une requête REST standard. Apidog permet :

• De créer une collection Privy, renseigner ID et secret comme variables d’environnement.
• D’appeler des endpoints comme GET /api/v1/users/{userId} ou POST /api/v1/users/{userId}/wallets directement.
• D’enregistrer les payloads webhooks et de les rejouer via tunnel local.
• De configurer des tests automatisés pour valider la gestion des JWT (valide/expiré).
• De télécharger Apidog gratuitement.
• Pour migrer depuis Postman, suivez le guide de workflow côte à côte.

FAQ

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

Les trois proposent des portefeuilles intégrés. Privy se distingue par son focus sur l'authentification hybride (e-mail, wallet, social) et un moteur de politique avancé. Web3Auth privilégie le partage MPC, Magic propose un login "magic link" plus générique. Choisissez Privy pour une intégration UX claire et un contrôle fin des wallets.

Privy prend-il en charge Solana ?

Oui. Les portefeuilles intégrés fonctionnent sur mainnet/devnet Solana. Le SDK React expose getSolanaProvider() pour signer/envoyer des transactions. EVM et Solana sont configurables sur la même app.

Les utilisateurs peuvent-ils utiliser leur propre portefeuille ?

Oui. MetaMask, Coinbase Wallet, WalletConnect, Phantom et bien d'autres sont supportés immédiatement. Privy traite les wallets externes comme comptes liés sous le même DID utilisateur.

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

Les utilisateurs gardent l'accès aux wallets exportés, la clé restant dans le navigateur. Pour le production, activez l'exportabilité et documentez un plan de repli. Voir le guide de comparaison Identité pour les modèles de risque.

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

Oui. TOTP, SMS, clés d'accès sont intégrés. Vous pouvez exiger MFA pour des actions précises (envois, export) via le moteur de politique.

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

Les deux. Le SDK client gère login et signature ; le SDK serveur vérifie les jetons et récupère les données utilisateur. Ne divulguez jamais le secret d'application côté client.