privy-integration について
Privy の認証とウォレット基盤を暗号資産アプリに組み込む開発者向けのドキュメントスキルです。React・Node.js SDK、EVM・Solana のウォレット、エージェント決済とウォレットを扱います。
主な機能
- 01React・Node.js SDK の統合ガイド
- 02メール・SMS・ソーシャル・パスキー・ウォレット認証
- 03組み込みウォレットとスマートウォレットの設定
- 04EVM・Solana のウォレットワークフロー
- 05x402・MPP 決済の統合
- 06ポリシー対応エージェントウォレットのガイド
活用シーン
- 01React アプリへの Privy 認証の追加
- 02Node.js サービスでのトークン検証
- 03x402 または MPP 決済の統合
- 04ポリシー制約付きエージェントウォレットの設定
MCP 対応
エージェント認証の一部として MCP 認可のガイドを含みます。MCP サーバーやクライアントの提供については説明されていません。
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/privy-integrationを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
CHANGELOG.mdLICENSE.txtskill-card.mdreferences/agent-auth.mdagent-payments.mdreact-sdk.mdserver-sdk.mdsolana.mdwallets.md詳細
Privy 連携
Privy は、暗号資産を基盤とするアプリ向けに認証とウォレットのインフラを提供します。セルフカストディ型ウォレットを組み込み、メール／SMS／ソーシャルログイン／パスキー／ウォレットによるユーザー認証に対応し、EVM および Solana チェーンで取引できます。また、エージェント決済プロトコル（x402、MPP）と自律型エージェントウォレットにも対応しています。
主なパッケージ：
@privy-io/react-auth- React SDK（認証 + ウォレット + x402）@privy-io/react-auth/solana- Solana ウォレット用フック@privy-io/react-auth/smart-wallets- スマートウォレット（ERC-4337）@privy-io/wagmi- wagmi v2 コネクター@privy-io/node- サーバーサイド SDK（非推奨の@privy-io/server-authに代わるもの）mppx- MPP クライアント／サーバー SDK（Tempo で決済）
ドキュメント：Privy は公式のエージェントスキルを提供しています。npx skills add https://docs.privy.io を実行するか、https://docs.privy.io/skill.md を取得してください。機械可読なドキュメントインデックスは https://docs.privy.io/llms-full.txt（および sitemap.xml）です。現在、llms.txt はスキルインストーラーへのリンクのみを記載しています。Privy はドキュメントを頻繁に再構成するため、URL を推測しないでください。404 エラーになります。
ワークフローの選択ガイド
React アプリで Privy 認証を設定する場合 -> 以下のクイックスタートに進み、その後 references/react-sdk.md を参照してください
Privy アプリに wagmi／viem を追加する場合 -> 以下の Wagmi 連携に進み、その後 references/react-sdk.md を参照してください
サーバーサイド（Node.js）で作業する場合 -> 以下のサーバーサイドのセクションに進み、その後 references/server-sdk.md を参照してください
x402 または MPP 決済を追加する場合 -> 以下の x402／MPP のセクションに進み、その後 references/agent-payments.md を参照してください
エージェントウォレットまたはエージェント認証を構築する場合 -> 以下のエージェントウォレットに進み、その後 references/agent-auth.md を参照してください
Solana 固有の連携を行う場合 -> references/solana.md を参照してください
ウォレットを管理する場合（スマートウォレット、ポリシー、資金の追加） -> references/wallets.md を参照してください
ウォレット操作を行う場合（DeFi 運用、スワップ、クロスチェーン送金／ブリッジ） -> references/wallets.md のウォレット操作を参照してください
クイックスタート（React + Next.js）
1. インストール
npm i @privy-io/react-auth
2. PrivyProvider でアプリをラップする
'use client';
import {PrivyProvider} from '@privy-io/react-auth';
export default function Providers({children}: {children: React.ReactNode}) {
return (
<PrivyProvider
appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID!}
config={{
embeddedWallets: {
ethereum: {createOnLogin: 'users-without-wallets'}
}
}}
>
{children}
</PrivyProvider>
);
}
3. フックを使う前に準備状況を確認する
import {usePrivy} from '@privy-io/react-auth';
function App() {
const {ready, authenticated, user} = usePrivy();
if (!ready) return <div>Loading...</div>;
// Safe to use Privy hooks now
}
4. ログイン（メール OTP の例）
import {useLoginWithEmail} from '@privy-io/react-auth';
function LoginForm() {
const {sendCode, loginWithCode} = useLoginWithEmail();
// sendCode({email}) then loginWithCode({code})
}
5. トランザクションを送信する（EVM）
import {useSendTransaction} from '@privy-io/react-auth';
function SendButton() {
const {sendTransaction} = useSendTransaction();
return (
<button onClick={() => sendTransaction({to: '0x...', value: 100000})}>
Send
</button>
);
}
PrivyProvider の設定
config={{
// Auth methods enabled for login
loginMethods: ['email', 'sms', 'wallet', 'google', 'apple', 'twitter',
'github', 'discord', 'farcaster', 'telegram', 'passkey'],
// Embedded wallet creation
embeddedWallets: {
ethereum: {createOnLogin: 'users-without-wallets'}, // or 'all-users' | 'off'
solana: {createOnLogin: 'users-without-wallets'}
},
// UI appearance
appearance: {
showWalletLoginFirst: false,
walletChainType: 'ethereum-and-solana', // or 'ethereum-only' | 'solana-only'
theme: 'light', // or 'dark'
accentColor: '#6A6FF5',
logo: 'https://your-logo.png'
},
// External wallet connectors (Solana)
externalWallets: {
solana: {connectors: toSolanaWalletConnectors()}
},
// Solana RPC config (required for embedded wallet UIs)
solana: {
rpcs: {
'solana:mainnet': {
rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
rpcSubscriptions: createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com')
}
}
}
}}
Wagmi 連携
@privy-io/wagmi から createConfig と WagmiProvider をインポートしてください（wagmi からではありません）。
npm i @privy-io/react-auth @privy-io/wagmi wagmi @tanstack/react-query
import {PrivyProvider} from '@privy-io/react-auth';
import {WagmiProvider, createConfig} from '@privy-io/wagmi';
import {QueryClient, QueryClientProvider} from '@tanstack/react-query';
import {mainnet, base} from 'viem/chains';
import {http} from 'wagmi';
const queryClient = new QueryClient();
const wagmiConfig = createConfig({
chains: [mainnet, base],
transports: {[mainnet.id]: http(), [base.id]: http()}
});
// Nesting order: PrivyProvider > QueryClientProvider > WagmiProvider
export default function Providers({children}: {children: React.ReactNode}) {
return (
<PrivyProvider appId="your-app-id" config={privyConfig}>
<QueryClientProvider client={queryClient}>
<WagmiProvider config={wagmiConfig}>{children}</WagmiProvider>
</QueryClientProvider>
</PrivyProvider>
);
}
読み取り／書き込み操作には wagmi フック（useAccount、useSendTransaction など）を使用してください。ウォレットの接続／作成には Privy フックを使用してください。
サーバーサイドでのトークン検証
npm i @privy-io/node
import {PrivyClient} from '@privy-io/node';
const privy = new PrivyClient({
appId: process.env.PRIVY_APP_ID!,
appSecret: process.env.PRIVY_APP_SECRET!
});
// Verify access token from Authorization header
// (top-level privy.verifyAuthToken is deprecated - use utils().auth())
const {userId} = await privy.utils().auth().verifyAccessToken(accessToken);
ホワイトラベル認証
すべての認証フローは、カスタム UI で完全にホワイトラベル化できます。主なフック：
| フック | 認証方法 |
|---|---|
useLoginWithEmail | メール OTP（sendCode、loginWithCode） |
useLoginWithSms | SMS OTP |
useLoginWithOAuth | ソーシャルログイン（initOAuth({provider: 'google'})） |
useLoginWithPasskey | パスキー |
useSignupWithPasskey | パスキー登録 |
useLoginWithTelegram | Telegram |
useLogin | コールバックを使った汎用ログイン |
注意点：ホワイトラベルフロー（useLoginWithEmail など）はアプリのドメインから Privy を直接呼び出すため、そのドメインが Dashboard の Allowed Origins/Domains に登録されていないと、エラーを表示せずに失敗します。一方、ホスト型モーダル（usePrivy().login()）は引き続き動作するため、問題が見えにくくなります。ローカル開発で使うポート（例：localhost:5173）もすべて追加してください。useLoginWithEmail の onError が返すのは {message} ではなく詳細なオブジェクトです。実際の拒否理由を確認するには、オブジェクト全体をログに出してください。
x402 決済（クイックスタート）
v3.7.0 以降、@privy-io/react-auth に組み込まれています。USDC を使用した HTTP 402 決済フローを自動的に処理します。
import {useX402Fetch, useWallets} from '@privy-io/react-auth';
function PaidContent() {
const {wallets} = useWallets();
const {wrapFetchWithPayment} = useX402Fetch();
const fetchContent = async () => {
const fetchWithPayment = wrapFetchWithPayment({
walletAddress: wallets[0]?.address,
fetch,
maxValue: BigInt(1000000) // Max 1 USDC
});
const res = await fetchWithPayment('https://api.example.com/premium');
return res.json();
};
}
サーバーサイド（Node.js）：
import {createX402Client} from '@privy-io/node/x402';
import {wrapFetchWithPayment} from '@x402/fetch';
const x402client = createX402Client(privy, {walletId: wallet.id, address: wallet.address});
const fetchWithPayment = wrapFetchWithPayment(fetch, x402client);
const response = await fetchWithPayment('https://api.example.com/premium');
MPP 決済（クイックスタート）
MPP（Machine Payments Protocol）は、ステーブルコイン（PathUSD、USDC など）を使用して Tempo で決済します。高頻度の決済に対応するセッションもサポートしています。
import {Mppx, tempo} from 'mppx/client';
// Create Privy-backed viem account (see references/agent-payments.md for full pattern)
const account = createPrivyAccount(wallet.id, wallet.address);
const mppx = Mppx.create({polyfill: false, methods: [tempo({account})]});
const response = await mppx.fetch('https://api.example.com/weather');
エージェント型ウォレット（クイックスタート）
自律型エージェント向けの、ポリシーベースの制約を備えたサーバー制御ウォレットです。
// Create agent wallet
const wallet = await privy.wallets().create({chain_type: 'ethereum'});
// Execute transactions - validated against attached policies
const {hash} = await privy.wallets().ethereum().sendTransaction(wallet.id, {
caip2: 'eip155:8453',
params: {transaction: {to: '0x...', value: '0x1', chain_id: 8453}}
});
2 つの制御モデルがあります。エージェント制御型（完全自律型、開発者所有）と、エージェント署名者を設定したユーザー所有型（ユーザーが取り消し権限を保持）です。ポリシーの例とセットアップについては、references/agent-auth.md をご覧ください。
リファレンスドキュメント
詳しい統合ガイドについては、該当するリファレンスファイルをご覧ください。
- references/react-sdk.md - すべての React フック、PrivyProvider の設定、wagmi/viem のセットアップ、外観設定、ホワイトレーベルのパターン、ウォレット UI コンポーネント
- references/server-sdk.md - Node.js SDK（
@privy-io/node）、トークンの種類と検証、ユーザー管理 API、REST API、ウェブフック - references/wallets.md - 埋め込みウォレット（EVM + Solana）、スマートウォレット（ERC-4337）、ガススポンサーシップ、外部コネクター、ポリシーと制御、資金の入金、ウォレットのエクスポート
- references/solana.md - Solana 固有のセットアップ、コネクター、@solana/kit と @solana/web3.js の統合、トランザクション署名、フィーペイヤーによるガススポンサーシップ
- references/agent-payments.md - x402 プロトコル（React + Node.js）、mppx SDK を使用した MPP（クライアント + サーバー）、Tempo ブロックチェーン（PathUSD、TIP-20）、セッション、ファシリテーター、x402 と MPP の比較
- references/agent-auth.md - エージェント型ウォレット（ポリシー、認可キー、OpenClaw）、Agent Auth Protocol（エージェントごとの ID、機能）、MCP 認可、Better Auth ブリッジ