DEV Community

Cover image for Privy APIの使い方：Web3向け埋め込みウォレットとソーシャル認証
Akira
Akira

Posted on • Originally published at apidog.com

Privy APIの使い方：Web3向け埋め込みウォレットとソーシャル認証

Web3アプリのユーザーオンボーディングは、依然として大きな障壁が存在します。シードフレーズやブラウザ拡張、ガス代の問題で、2タップで済むはずのサインアップが10分の格闘に変わりがちです。Privy APIはこの課題を解決し、メール、SMS、Google、Apple、MetaMaskなど多様なログイン手段の裏で埋め込みウォレットを自動生成します。ユーザーにブラウザ拡張のインストールを促すことなく、スムーズにWeb3体験を提供できます。 Apidogを今すぐ試す PrivyはBlackbird、Friend.tech、OpenSeaなど数千のアプリで採用されており、Ethereum、Solana、EVMチェーンに対応しています。本記事では、Privyアプリの作成からReact SDK導入、サーバーでのトークン検証、埋め込みウォレットによる署名、Webhookの設定まで、導入に必要な具体的手順を解説します。MetaMaskの開発者ツールキットなどとの比較も参考にどうぞ。

💡コードを実装する前に、Privy SDKが発行するHTTPSリクエストを監視・検証したい場合はApidogが便利です。ローカルプロキシを経由し、実際のリクエストペイロードをキャプチャすることで、認証失敗の早期デバッグが可能です。 ## 要点 - Privyは埋め込みウォレットと多彩なログイン方法（メール、SMS、ソーシャル、外部ウォレット）を1つのSDKで統合。 - React SDKは`PrivyProvider`、`useLogin`、`useWallets`、`usePrivy`フックを提供し、認証・署名フローをカバー。 - `@privy-io/server-auth`でバックエンドのアクセストークン検証が可能。全リクエストのユーザーID信頼性を担保。 - ウォレットはEthereum/Solana/各種EVMチェーンをサポートし、主要操作にエクスポートや認証署名も対応。 - Webhookでユーザー作成・ログイン・ウォレットイベント時の即時データ同期が可能。 - ポリシーエンジンでアプリコードを書き換えずMFAや許可リスト、トランザクション制御が追加可能。 ## Privy APIとは？ Privyは認証とウォレットのインフラをノーコード&セキュアに提供します。アプリにログインUI、ユーザーごとの埋め込みウォレット、サーバー検証用RESTエンドポイント群を追加できます。埋め込みウォレットはセキュアエンクレーブ内に保管され、Privyや自サーバーで秘密鍵を保持しません。ユーザーは必要に応じて秘密鍵をエクスポートし自己管理も可能。 料金は月間アクティブウォレット数に基づき、無料1,000MAW・Pro（$149/月）・Enterpriseと段階的。プロトタイプは無料で開始可能です。 ## 認証とセットアップ 1. [privy.io](https://www.privy.io/)でダッシュボードにアクセスし新規アプリを作成。 2. 下記2つの値を控えます。 - **App ID** (`clxxxxx...`)：クライアントSDK用 - **App secret**：サーバーSDK用 3. 許可するログイン手段（メール、SMS、Google、Apple、Farcaster、ウォレット）とデフォルトチェーンを設定し、自ドメインを許可オリジンに登録。 4. Reactの場合、SDKをインストール： ```bash npm install @privy-io/react-auth ``` 5. アプリを`PrivyProvider`でラップ： ```jsx import { PrivyProvider } from '@privy-io/react-auth'; export default function App({ Component, pageProps }) { return ( ); } ``` - `createOnLogin`でウォレット未保有ユーザーの自動ウォレット発行を制御。 - 対応チェーンは`supportedChains`で自由に設定。Solanaの場合は`solanaClusters`で追加。 ## 主要なエンドポイントとSDK呼び出し 通常はReact SDKでほとんどの認証・署名フローをカバーできますが、サーバーSDKやWebhookは共通のトークン形式を利用しているため、APIの構造も把握しておきましょう。 ### ログインのトリガーとユーザー取得 ```jsx import { usePrivy, useWallets } from '@privy-io/react-auth'; function LoginButton() { const { ready, authenticated, login, logout, user } = usePrivy(); const { wallets } = useWallets(); if (!ready) return

Loading...

; if (!authenticated) return Sign in; const embedded = wallets.find((w) => w.walletClientType === 'privy'); return (

Hi {user.email?.address ?? user.id}

  <p>Wallet: {embedded?.address}</p>
  <button onClick={logout}>Log out</button>
</div>

);
}



`useWallets`で紐付け済みウォレットをすべて取得、`walletClientType`でPrivyウォレットを区別できます。このパターンは<a href="http://apidog.com/blog/best-crypto-wallet-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation">Privyの埋め込みウォレット</a>でも利用されています。

### トランザクション署名



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

SolanaならgetEthereumProvider→getSolanaProviderに変更し、シリアライズ済みトランザクションを渡します。Alchemy等と組み合わせたデータアクセスも可能です。

サーバーでのトークン検証

  1. サーバーSDKをインストール： 
npm install @privy-io/server-auth
  1. フロントエンドからのJWTトークンをサーバーで検証： 
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 は Privy user DID
    return Response.json({ userId: claims.userId });
  } catch (err) {
    return new Response('Unauthorized', { status: 401 });
  }
}

ユーザーIDを検証した上で、privy.getUser(userId)で詳細情報も取得可能。

埋め込みウォレットのエクスポート

ユーザーによる秘密鍵エクスポートは以下のフックで完結：

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

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

セキュアなiframeモーダルで鍵が表示され、アプリ側で生データに触れることはありません。

認証署名とポリシーエンジン

高リスク操作（大額送金・新規デバイスログイン等）には、Privyの認証署名とポリシーエンジンが活躍します。ダッシュボードでMFAや許可リスト、サーバー署名認可のルールを設定し、コードを変更せずにセキュリティ強化が可能です。詳細はPrivyの認証鍵ガイドを参照。

Webhook

ユーザーやウォレットのライフサイクルイベント時、自動でWebhookが発火します。

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

データベース同期前に、Webhookシークレットでsvix-signatureを必ず検証してください。

よくあるエラーとレート制限

開発時に遭遇しやすいエラーと対処法：

  • invalid_token: JWTが期限切れ。APIリクエスト直前にusePrivyのgetAccessToken()で更新。トークン有効期限は1時間。
  • 403 origin_not_allowed: デプロイURLがPrivyダッシュボードで許可されていない。https://yourapp.comやプレビュードメインを追加。
  • wallet_not_ready: readyがtrueになる前にuseWalletsを使用。すべてのウォレット操作はreadyでガード。
  • レート制限: 無料ティアは1秒100リクエスト/アプリ。超えそうな場合はgetUserのバッチ処理やキャッシュ推奨。

Webhookの失敗リプレイはApidogで。生のペイロードを貼り付け、ヘッダーを編集して何度もテストできます。

Privyの料金

  • Free: 月1,000アクティブウォレット、コアログイン、EVM+Solana埋め込みウォレット。
  • Pro: $149/月、より高いMAW、Webhooks全機能、ステージングアプリ。
  • Enterprise: カスタムSLA、専用サポート、エンジニアリング支援、カスタムポリシールール。

最新の料金はprivy.io/pricingで確認してください。

Apidogを使ったPrivy APIのテスト

PrivyのクライアントSDKはHTTPSリクエストを内部で処理しますが、サーバーサイドのトークン検証やWebhookはRESTです。ApidogでPrivy APIコレクションを作成し、App ID/Secretを環境変数に設定、GET /api/v1/users/{userId}やPOST /api/v1/users/{userId}/walletsなどを直接テストできます。

Webhookのサンプルペイロードも保存・リプレイして、ローカルサーバー検証が可能。JWTの有効/期限切れテストも自動化でき、デプロイごとに検証を回すことが推奨されます。Apidogを無料でダウンロードすれば、cURLやPostman不要で複雑なAPIテストが実現。もしPostmanから移行済みなら、ワークフローガイドも活用してください。

よくある質問

PrivyはWeb3AuthやMagicとどう違う？

3サービスとも埋め込みウォレットを提供しますが、Privyは複合認証（メール＋ウォレット＋ソーシャル）やエンタープライズ向けポリシーエンジンに強み。Web3AuthはMPC鍵分割中心、Magicはマジックリンク製品が豊富です。柔軟なUXと細かいウォレット制御を両立したいならPrivy推奨。

PrivyはSolanaをサポート？

はい。埋め込みウォレットはSolanaメインネット・devネット両対応。React SDKのgetSolanaProvider()で署名・送信可。同一アプリでEVMとSolana両対応も可能。

ユーザーは自分のウォレットを持ち込める？

はい。MetaMask、Coinbase Wallet、WalletConnect、Phantom等に即対応。外部ウォレットはリンク済みアカウントとして扱われ、同一DIDで埋め込み・外部鍵を管理。

Privyがダウンした場合は？

鍵はユーザーのブラウザエンクレーブ内に存在し、エクスポート機能でアクセス可能。運用時はエクスポートを有効化し、フォールバック手順も併記推奨。ベンダーリスクの比較はIDプロバイダー比較ガイド参照。

PrivyはMFA対応？

TOTP、SMS、パスキー全て組み込み。ポリシーエンジン経由で操作単位（送金・エクスポート等）にMFAを必須化できます。

アプリのコードはサーバー/クライアントどちらで動く？

両方。クライアントSDKでログインUIと署名、サーバーSDKでトークン検証＆ユーザーデータ取得。App Secretをブラウザに公開しないよう注意してください。

Top comments (0)