sendaifun/phantom-connect

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