phantom-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phantom Connect SDK

Build wallet-connected Solana applications with the Phantom Connect SDK ecosystem.

借助Phantom Connect SDK生态系统构建支持钱包连接的Solana应用。

SDK Selection

SDK选择

Platform	SDK	Package
React web apps	React SDK	`@phantom/react-sdk`
React Native / Expo	React Native SDK	`@phantom/react-native-sdk`
Vanilla JS / Vue / Angular	Browser SDK	`@phantom/browser-sdk`

平台	SDK	包名
React网页应用	React SDK	`@phantom/react-sdk`
React Native / Expo	React Native SDK	`@phantom/react-native-sdk`
原生JS / Vue / Angular	Browser SDK	`@phantom/browser-sdk`

Prerequisites

前置条件

Phantom Portal Account — Register at phantom.com/portal
App ID — Get from Portal → App → Set Up
Allowlisted URLs — Add domains and redirect URLs in Portal

Phantom Portal账户 — 前往phantom.com/portal注册
App ID — 从Portal → 应用 → 设置页面获取
白名单URL — 在Portal中添加域名和重定向URL

Auth Providers

认证提供商

Provider	Description	Requires appId
`"injected"`	Phantom browser extension	No
`"google"`	Google OAuth (embedded wallet)	Yes
`"apple"`	Apple ID (embedded wallet)	Yes

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

Critical Rules

重要规则

Always use
signAndSendTransaction
—

signTransaction

and

signAllTransactions

are NOT supported for embedded wallets

Always use
LAMPORTS_PER_SOL
from
```
@solana/web3.js
```
for amount conversion — never hardcode
```
1000000000
```
Wrap all async SDK calls in try-catch — users can reject prompts at any time
Check
isConnected
before signing — verify wallet connection before any operation
React Native:
react-native-get-random-values
must be the FIRST import — before any other imports
BrowserSDK must be a singleton — create one instance per app, never multiple
Import
AddressType
from
@phantom/browser-sdk
only
Use devnet for testing, mainnet-beta for production — never test against mainnet with real funds
Never expose private keys — Phantom handles all signing internally
Embedded wallet spending limit: $1,000 USD per day per app per user
Social login sessions persist 7 days from last auth event — handle expiration gracefully

始终使用
signAndSendTransaction
— 嵌入式钱包不支持

signTransaction

和

signAllTransactions

始终使用
@solana/web3.js
中的
LAMPORTS_PER_SOL
进行金额转换 — 切勿硬编码
```
1000000000
```
将所有异步SDK调用包裹在try-catch中 — 用户可随时拒绝弹窗请求
签名前检查
isConnected
状态 — 任何操作前先验证钱包连接状态
React Native：
react-native-get-random-values
必须是第一个导入项 — 早于其他所有导入
BrowserSDK必须是单例 — 每个应用仅创建一个实例，切勿创建多个
仅从
@phantom/browser-sdk
导入
AddressType
使用devnet进行测试，mainnet-beta用于生产环境 — 切勿使用主网进行真实资金测试
切勿暴露私钥 — Phantom会在内部处理所有签名操作
嵌入式钱包每日消费限额：每个应用每位用户每日1000美元
社交登录会话有效期：自上次认证事件起7天 — 需优雅处理过期情况

Quick Start

快速开始

React SDK

tsx

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

tsx

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

tsx

// 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": [...] } }

tsx

// 重要：必须是第一个导入项
import "react-native-get-random-values";
import { PhantomProvider, AddressType, darkTheme } from "@phantom/react-native-sdk";

// 需要在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,
});

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

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

Reference Docs

参考文档

For detailed implementation patterns, read these files:

references/react-sdk.md — Complete React SDK reference (hooks, components, theming)
references/react-native-sdk.md — Mobile setup, Expo config, deep links
references/browser-sdk.md — Vanilla JS patterns, events, wallet discovery
references/transactions.md — Solana transaction patterns (SOL, SPL tokens)
references/payments.md — Crypto payment flows (SOL, USDC, backend verification)
references/token-gating.md — Token-gated access (client-side, server-side, NFT)
references/nft-minting.md — NFT mint pages, Metaplex Core, compressed NFTs

如需详细的实现模式，请阅读以下文档：

references/react-sdk.md — 完整的React SDK参考（钩子、组件、主题）
references/react-native-sdk.md — 移动端设置、Expo配置、深度链接
references/browser-sdk.md — 原生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

Common Issues

常见问题

Issue	Solution
"appId required"	Add appId from Phantom Portal when using google/apple providers
Redirect not working	Allowlist redirectUrl in Phantom Portal
React Native crashes	Import `react-native-get-random-values` as FIRST import
Extension not detected	Use `waitForPhantomExtension()` with timeout
`signTransaction` error	Use `signAndSendTransaction` instead — embedded wallets don't support `signTransaction`

问题	解决方案
"appId required"	使用Google/Apple提供商时，添加从Phantom Portal获取的appId
重定向不生效	在Phantom Portal中将redirectUrl加入白名单
React Native应用崩溃	将 `react-native-get-random-values` 作为第一个导入项
扩展未被检测到	使用带超时的 `waitForPhantomExtension()`
`signTransaction` 报错	改用 `signAndSendTransaction` — 嵌入式钱包不支持 `signTransaction`

Resources

资源

Phantom Portal — App registration
Phantom Docs — Full documentation
SDK Examples — Working demos
MCP Server — AI docs access

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