关于 privy-integration
供开发者将 Privy 身份验证和钱包基础设施集成到加密应用的文档技能，涵盖 React、Node.js、EVM、Solana，以及 Agent 支付和钱包。
主要功能
- 01React 和 Node.js SDK 集成指南
- 02电子邮件、短信、社交、通行密钥和钱包认证
- 03嵌入式钱包与智能钱包配置
- 04EVM 和 Solana 钱包工作流
- 05x402 与 MPP 支付集成
- 06基于策略的 Agent 钱包指南
适用场景
- 01为 React 应用添加 Privy 认证
- 02在 Node.js 服务中验证令牌
- 03集成 x402 或 MPP 支付
- 04配置受策略约束的 Agent 钱包
MCP 相关
该技能包含 Agent 身份验证中的 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 链上进行交易。还支持 Agent 支付协议（x402、MPP）和自主 Agent 钱包。
主要软件包：
@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 提供官方 Agent 技能 - 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 构建 Agent 钱包或 Agent 身份验证？ -> 查看下方的 Agent 钱包，然后参阅 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');
Agentic Wallets（快速入门）
由服务端控制的钱包，可通过基于策略的约束支持自主 Agent。
// 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}}
});
两种控制模式：Agent 控制（完全自主，由开发者拥有）和用户拥有并配置 Agent 签名者（用户保留撤销权限）。策略示例和设置方法请参阅 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、Webhooks - references/wallets.md - 嵌入式钱包（EVM + Solana）、智能钱包（ERC-4337）、Gas 赞助、外部连接器、策略和控制、资金充值、钱包导出
- references/solana.md - Solana 专属设置、连接器、@solana/kit 和 @solana/web3.js 集成、交易签名、通过费用支付方进行 Gas 赞助
- references/agent-payments.md - x402 协议（React + Node.js）、使用 mppx SDK 的 MPP（客户端 + 服务端）、Tempo 区块链（PathUSD、TIP-20）、会话、协调器、x402 与 MPP 对比
- references/agent-auth.md - Agentic Wallets（策略、授权密钥、OpenClaw）、Agent Auth Protocol（每个 Agent 的身份和能力）、MCP 授权、Better Auth 桥接