# Integration Patterns — Phantom + Helius End-to-end patterns for building frontend Solana applications combining Phantom Connect SDK with Helius infrastructure. ## Pattern 1: Swap UI **Architecture**: Aggregator API provides serialized transaction → Phantom signs → Helius Sender submits → poll confirmation. This pattern is aggregator-agnostic — works with Jupiter, DFlow, or any API that returns a serialized transaction. ```tsx import { useSolana, useAccounts } from '@phantom/react-sdk'; import { useState } from 'react'; function SwapButton({ serializedTransaction }: { serializedTransaction: string }) { const { solana } = useSolana(); const { isConnected, addresses } = useAccounts(); const [status, setStatus] = useState<'idle' | 'signing' | 'submitting' | 'confirming' | 'done' | 'error'>('idle'); async function handleSwap() { if (!isConnected || !solana) return; try { // 1. Decode the transaction from the swap API setStatus('signing'); const txBytes = Uint8Array.from(atob(serializedTransaction), (c) => c.charCodeAt(0)); // 2. Phantom signs (accepts raw transaction bytes, does NOT send) const signedTx = await solana.signTransaction(txBytes); // 3. Submit to Helius Sender (browser-safe, no API key) setStatus('submitting'); const base64Tx = btoa(String.fromCharCode(...new Uint8Array(signedTx))); const response = await fetch('https://sender.helius-rpc.com/fast', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'sendTransaction', params: [base64Tx, { encoding: 'base64', skipPreflight: true, maxRetries: 0 }], }), }); const result = await response.json(); if (result.error) throw new Error(result.error.message); // 4. Poll for confirmation setStatus('confirming'); const signature = result.result; await pollConfirmation(signature); setStatus('done'); } catch (error: any) { if (error.message?.includes('User rejected')) { setStatus('idle'); // User cancelled } else { setStatus('error'); } } } return ( ); } async function pollConfirmation(signature: string): Promise { for (let i = 0; i < 30; i++) { const response = await fetch('/api/rpc', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'getSignatureStatuses', params: [[signature]], }), }); const { result } = await response.json(); const status = result?.value?.[0]; if (status?.confirmationStatus === 'confirmed' || status?.confirmationStatus === 'finalized') { if (status.err) throw new Error('Transaction failed'); return; } await new Promise((r) => setTimeout(r, 500)); } throw new Error('Confirmation timeout'); } ``` **Key points**: - The swap API (Jupiter, DFlow, etc.) returns a serialized transaction — you don't build it yourself - Phantom signs the pre-built transaction via `solana.signTransaction` - Submit via Helius Sender HTTPS endpoint (browser-safe, no API key) - Poll confirmation through your backend proxy (needs API key) ## Pattern 2: Portfolio Viewer **Architecture**: Phantom provides wallet address → backend proxy calls Helius DAS and Wallet API → display balances with USD values. ```tsx import { useAccounts, useModal } from '@phantom/react-sdk'; import { useState, useEffect } from 'react'; interface TokenBalance { mint: string; name: string; symbol: string; amount: number; usdValue: number | null; imageUrl: string | null; } function PortfolioViewer() { const { isConnected, addresses } = useAccounts(); const { open } = useModal(); const [tokens, setTokens] = useState([]); const [solBalance, setSolBalance] = useState(null); const [loading, setLoading] = useState(false); const walletAddress = addresses?.find(a => a.addressType === 'solana')?.address; useEffect(() => { if (!walletAddress) { setTokens([]); setSolBalance(null); return; } setLoading(true); // Fetch portfolio via backend proxy (Helius Wallet API — 100 credits) fetch(`/api/helius/v1/wallet/${walletAddress}/balances?showNative=true`) .then((r) => r.json()) .then((data) => { // Native SOL if (data.nativeBalance) { setSolBalance(data.nativeBalance.lamports / 1e9); } // Tokens sorted by USD value (descending) const tokenList: TokenBalance[] = (data.tokens || []).map((t: any) => ({ mint: t.mint, name: t.name || 'Unknown', symbol: t.symbol || t.mint.slice(0, 6), amount: t.amount, usdValue: t.usdValue, imageUrl: t.imageUrl, })); setTokens(tokenList); }) .finally(() => setLoading(false)); }, [walletAddress]); if (!isConnected) { return (

Connect your wallet to view your portfolio

); } if (loading) return

Loading portfolio...

; return (

Portfolio

{solBalance !== null && (

SOL: {solBalance.toFixed(4)}

)} {tokens.map((token) => (

{token.symbol} {token.amount.toFixed(4)} {token.usdValue && ${token.usdValue.toFixed(2)}}

))}

); } ``` **Key points**: - Phantom provides the wallet address via `useAccounts` — no signing needed for read-only operations - All Helius API calls go through the backend proxy (`/api/helius/...`) to keep the API key server-side - `getWalletBalances` returns tokens sorted by USD value — ideal for portfolio display - For detailed token metadata or NFTs, supplement with DAS `getAssetsByOwner` via the proxy ## Pattern 3: Real-Time Dashboard **Architecture**: Phantom connection → server-side Helius WebSocket → relay to client via SSE. ```tsx // Client component import { useAccounts } from '@phantom/react-sdk'; import { useState, useEffect } from 'react'; interface AccountUpdate { lamports: number; slot: number; } function RealTimeDashboard() { const { addresses } = useAccounts(); const [updates, setUpdates] = useState([]); const [balance, setBalance] = useState(null); const walletAddress = addresses?.find(a => a.addressType === 'solana')?.address; useEffect(() => { if (!walletAddress) return; // SSE stream from our backend (which connects to Helius WS) const eventSource = new EventSource( `/api/stream?address=${walletAddress}` ); eventSource.onmessage = (event) => { const data = JSON.parse(event.data); const value = data?.result?.value; if (value) { const balanceSOL = value.lamports / 1e9; setBalance(balanceSOL); setUpdates((prev) => [ { lamports: value.lamports, slot: data.result.context?.slot }, ...prev.slice(0, 49), // Keep last 50 updates ]); } }; return () => eventSource.close(); }, [walletAddress]); return (

Live Balance

{balance !== null &&

{balance.toFixed(4)} SOL

}

Recent Updates

{updates.map((u, i) => (

Slot {u.slot}: {(u.lamports / 1e9).toFixed(4)} SOL

))}

); } ``` **Server-side SSE endpoint**: See `references/frontend-security.md` for the full WebSocket relay pattern. The key idea is: 1. Server opens `wss://mainnet.helius-rpc.com/?api-key=KEY` (key stays server-side) 2. Server subscribes to `accountSubscribe` for the user's wallet address 3. Server relays notifications to the client via SSE 4. Client consumes the SSE stream with `EventSource` ## Pattern 4: Token Transfer **Architecture**: Build `VersionedTransaction` with CU limit + CU price + transfer instruction + Jito tip → Phantom signs → Sender submits → parse confirmation. ```tsx import { useSolana, useAccounts } from '@phantom/react-sdk'; import { pipe, createTransactionMessage, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstruction, compileTransaction, address, lamports, } from '@solana/kit'; import { getTransferSolInstruction } from '@solana-program/system'; import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget'; const TIP_ACCOUNTS = [ '4ACfpUFoaSD9bfPdeu6DBt89gB6ENTeHBXCAi87NhDEE', 'D2L6yPZ2FmmmTKPgzaMKdhu6EWZcTpLy1Vhx8uvZe7NZ', '9bnz4RShgq1hAnLnZbP8kbgBg1kEmcJBYQq3gQbmnSta', '5VY91ws6B2hMmBFRsXkoAAdsPHBJwRfBht4DXox3xkwn', '2nyhqdwKcJZR2vcqCyrYsaPVdAnFoJjiksCXJ7hfEYgD', '2q5pghRs6arqVjRvT5gfgWfWcHWmw1ZuCzphgd5KfWGJ', 'wyvPkWjVZz1M8fHQnMMCDTQDbkManefNNhweYk5WkcF', '3KCKozbAaF75qEU33jtzozcJ29yJuaLJTy2jFdzUY8bT', '4vieeGHPYPG2MmyPRcYjdiDmmhN3ww7hsFNap8pVN3Ey', '4TQLFNWK8AovT1gFvda5jfw2oJeRMKEmw7aH6MGBJ3or', ]; function TransferForm() { const { solana } = useSolana(); const { addresses } = useAccounts(); async function handleTransfer(recipient: string, amountSOL: number) { if (!solana) return; const walletAddress = addresses?.find(a => a.addressType === 'solana')?.address; if (!walletAddress) return; const payer = address(walletAddress); // 1. Get priority fee from backend proxy const feeRes = await fetch('/api/rpc', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'getPriorityFeeEstimate', params: [{ accountKeys: [walletAddress], options: { priorityLevel: 'High' } }], }), }); const { result: feeResult } = await feeRes.json(); const priorityFee = Math.ceil((feeResult?.priorityFeeEstimate || 200_000) * 1.2); // 2. Get blockhash via proxy const bhRes = await fetch('/api/rpc', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'getLatestBlockhash', params: [{ commitment: 'confirmed' }], }), }); const { result: bhResult } = await bhRes.json(); const blockhash = bhResult.value; // 3. Build transaction const tipAccount = TIP_ACCOUNTS[Math.floor(Math.random() * TIP_ACCOUNTS.length)]; const txMessage = pipe( createTransactionMessage({ version: 0 }), (m) => setTransactionMessageFeePayer(payer, m), (m) => setTransactionMessageLifetimeUsingBlockhash(blockhash, m), (m) => appendTransactionMessageInstruction(getSetComputeUnitLimitInstruction({ units: 50_000 }), m), (m) => appendTransactionMessageInstruction(getSetComputeUnitPriceInstruction({ microLamports: priorityFee }), m), (m) => appendTransactionMessageInstruction(getTransferSolInstruction({ source: payer, destination: address(recipient), amount: lamports(BigInt(Math.floor(amountSOL * 1_000_000_000))), }), m), (m) => appendTransactionMessageInstruction(getTransferSolInstruction({ source: payer, destination: address(tipAccount), amount: lamports(200_000n), // 0.0002 SOL Jito tip }), m), ); const transaction = compileTransaction(txMessage); // 4. Sign with Phantom const signedTx = await solana.signTransaction(transaction); // 5. Submit to Sender const base64Tx = btoa(String.fromCharCode(...new Uint8Array(signedTx))); const response = await fetch('https://sender.helius-rpc.com/fast', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'sendTransaction', params: [base64Tx, { encoding: 'base64', skipPreflight: true, maxRetries: 0 }], }), }); const result = await response.json(); if (result.error) throw new Error(result.error.message); const signature = result.result; // 6. Parse transaction for confirmation display const parseRes = await fetch('/api/helius/v0/transactions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ transactions: [signature] }), }); const [parsed] = await parseRes.json(); return { signature, description: parsed?.description }; } // render form... } ``` **Instruction ordering** (required for Sender): 1. `setComputeUnitLimit` (first) 2. `setComputeUnitPrice` (second) 3. Your instructions (middle) 4. Jito tip transfer (last) ## Pattern 5: NFT Gallery **Architecture**: Phantom provides wallet address → backend proxy calls Helius DAS `getAssetsByOwner` → display NFT images. ```tsx import { useAccounts, useModal } from '@phantom/react-sdk'; import { useState, useEffect } from 'react'; interface NFT { id: string; name: string; image: string | null; collection: string | null; } function NFTGallery() { const { addresses, isConnected } = useAccounts(); const { open } = useModal(); const [nfts, setNfts] = useState([]); const [loading, setLoading] = useState(false); const walletAddress = addresses?.find(a => a.addressType === 'solana')?.address; useEffect(() => { if (!walletAddress) return; setLoading(true); // DAS getAssetsByOwner via backend proxy (10 credits/page) fetch('/api/rpc', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ jsonrpc: '2.0', id: '1', method: 'getAssetsByOwner', params: { ownerAddress: walletAddress, page: 1, limit: 100, displayOptions: { showCollectionMetadata: true }, }, }), }) .then((r) => r.json()) .then((data) => { const items = data.result?.items || []; // Filter to NFTs only (exclude fungible tokens) const nftItems: NFT[] = items .filter((item: any) => item.interface === 'V1_NFT' || item.interface === 'ProgrammableNFT' || item.compression?.compressed) .map((item: any) => ({ id: item.id, name: item.content?.metadata?.name || 'Unknown NFT', image: item.content?.links?.image || item.content?.files?.[0]?.uri || null, collection: item.grouping?.find((g: any) => g.group_key === 'collection')?.group_value || null, })); setNfts(nftItems); }) .finally(() => setLoading(false)); }, [walletAddress]); if (!isConnected) { return (

Connect your wallet to view your NFTs

); } if (loading) return

Loading NFTs...

; return (

{nfts.map((nft) => (

{nft.image &&

}

{nft.name}

))}

); } ``` **Key points**: - Use `content.links.image` for the NFT image URL (hosted on Arweave/IPFS, cached by DAS) - Filter by `interface` to separate NFTs from fungible tokens - Compressed NFTs (`compression.compressed === true`) work identically — DAS abstracts the difference - For collection browsing, use `getAssetsByGroup` with `groupKey: "collection"` instead ## Architecture Summary | Pattern | Phantom Role | Helius Products | API Key Needed in Browser? | |---|---|---|---| | Swap UI | Signs pre-built tx | Sender (submit) | No | | Portfolio Viewer | Provides address | Wallet API, DAS (via proxy) | No — proxy | | Real-Time Dashboard | Provides address | WebSockets (server relay) | No — server | | Token Transfer | Signs built tx | Sender (submit), Priority Fee (via proxy) | No | | NFT Gallery | Provides address | DAS (via proxy) | No — proxy | In every pattern, the Helius API key stays server-side. Only the Sender HTTPS endpoint is called directly from the browser.

helius-phantom

Install this skill

Comments