phantom-connect

name	phantom-connect
description	Build wallet-connected applications with the Phantom Connect SDK for Solana. Use when integrating Phantom wallets into React, React Native, or vanilla JS/TS apps — including wallet connection, social login (Google/Apple), transaction signing, message signing, token-gated access, crypto payments, and NFT minting. Covers @phantom/react-sdk, @phantom/react-native-sdk, and @phantom/browser-sdk.
license	MIT
metadata	{"author":"phantom","version":"1.0","homepage":"https://github.com/phantom/phantom-connect-cursor-plugin"}

Phantom Connect SDK

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

SDK Selection

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

Prerequisites

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

Auth Providers

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

Critical Rules

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

Quick Start

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

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

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

Resources

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