phantom-connect

Phantom Connect SDK

使用 Phantom Connect SDK 生态系统构建连接钱包的 Solana 应用。

SDK 选择

平台	SDK	包
React Web 应用	React SDK	@phantom/react-sdk
React Native / Expo	React Native SDK	@phantom/react-native-sdk
Vanilla JS / Vue / Angular	Browser SDK	@phantom/browser-sdk

前提条件

1. Phantom Portal 账户 — 在 phantom.com/portal 注册
2. App ID — 在 Portal → App → Set Up 中获取
3. 允许列表中的 URL — 在 Portal 中添加域名和重定向 URL

身份验证提供方

提供方	说明	是否需要 appId
"injected"	Phantom 浏览器扩展	否
"google"	Google OAuth（嵌入式钱包）	是
"apple"	Apple ID（嵌入式钱包）	是

重要规则

1. 始终使用 signAndSendTransaction — 嵌入式钱包不支持 signTransaction 和 signAllTransactions
2. 始终使用 @solana/web3.js 中的 LAMPORTS_PER_SOL 进行金额转换 — 切勿将 1000000000 硬编码
3. 将所有异步 SDK 调用放在 try-catch 中 — 用户随时可以拒绝提示
4. 签名之前检查 isConnected — 在执行任何操作之前确认钱包已连接
5. React Native：react-native-get-random-values 必须是第一个导入项 — 放在所有其他导入项之前
6. BrowserSDK 必须是单例 — 每个应用创建一个实例，切勿创建多个实例
7. 仅从 @phantom/browser-sdk 导入 AddressType
8. 测试时使用 devnet，生产环境使用 mainnet-beta — 切勿使用真实资金在 mainnet 上测试
9. 切勿泄露私钥 — 所有签名均由 Phantom 在内部处理
10. 嵌入式钱包消费限额：每个应用、每位用户每天 1,000 美元
11. 社交登录会话从上次身份验证事件起保留 7 天 — 请妥善处理会话过期

快速开始

React SDK

import { PhantomProvider, useModal, usePhantom, darkTheme } from "@phantom/react-sdk";
import { AddressType } from "@phantom/browser-sdk";

function App() {
  return (
    <PhantomProvider
      config={{
        providers: ["google", "apple", "injected"],
        appId: "your-app-id",
        addressTypes: [AddressType.solana],
        authOptions: { redirectUrl: "https://yourapp.com/callback" },
      }}
      theme={darkTheme}
    >
      <YourApp />
    </PhantomProvider>
  );
}

React Native SDK

// CRITICAL: Must be first import
import "react-native-get-random-values";
import { PhantomProvider, AddressType, darkTheme } from "@phantom/react-native-sdk";

// Requires app.json: { "expo": { "scheme": "myapp", "plugins": [...] } }

Browser SDK

import { BrowserSDK, AddressType } from "@phantom/browser-sdk";

const sdk = new BrowserSDK({
  providers: ["google", "apple", "injected"],
  appId: "your-app-id",
  addressTypes: [AddressType.solana],
  autoConnect: true,
});

参考文档

如需了解详细实现模式，请阅读以下文件：

• references/react-sdk.md — 完整的 React SDK 参考（钩子、组件、主题）
• references/react-native-sdk.md — 移动端设置、Expo 配置、深度链接
• references/browser-sdk.md — Vanilla JS 模式、事件、钱包发现
• references/transactions.md — Solana 交易模式（SOL、SPL 代币）
• references/payments.md — 加密货币支付流程（SOL、USDC、后端验证）
• references/token-gating.md — 代币门控访问（客户端、服务端、NFT）
• references/nft-minting.md — NFT 铸造页面、Metaplex Core、压缩 NFT

常见问题

问题	解决方案
"appId required"	使用 google/apple 提供方时，请添加来自 Phantom Portal 的 appId
重定向不起作用	在 Phantom Portal 中将 redirectUrl 添加到允许列表
React Native 崩溃	将 react-native-get-random-values 作为第一个导入项
未检测到扩展	使用 waitForPhantomExtension() 并设置超时时间
signTransaction 错误	改用 signAndSendTransaction — 嵌入式钱包不支持 signTransaction

资源

• Phantom Portal — 应用注册
• Phantom Docs — 完整文档
• SDK Examples — 可运行的演示
• MCP Server — AI 文档访问