@phantom/wallet-sdk

> ⚠️ DEPRECATED
>
> This package (@phantom/wallet-sdk) is deprecated and will no longer receive updates. Please migrate to the new Phantom SDK packages:
>
> - @phantom/react-sdk - For React applications
> - @phantom/browser-sdk - For vanilla JavaScript/TypeScript applications
> - @phantom/server-sdk - For server-side applications

The Phantom Embedded Wallet SDK allows you to integrate Phantom's wallet functionality directly into your web application. It provides a simple interface for interacting with the wallet, including showing/hiding the wallet UI, performing swaps and purchases, and accessing chain-specific RPC interfaces for Solana, Ethereum, Sui, and Bitcoin.

Installation

``bash


Using npm

npm install @phantom/wallet-sdk

Using yarn

yarn add @phantom/wallet-sdk

Using pnpm

pnpm add @phantom/wallet-sdk
`

Basic Usage

`typescript
import { createPhantom, Position } from "@phantom/wallet-sdk";

// Create a wallet instance
const phantom = await createPhantom({
position: Position.bottomRight,
hideLauncherBeforeOnboarded: false,
namespace: "my-app",
});

// Show the wallet
phantom.show();

// Access blockchain-specific interfaces
// Solana
const solanaPublicKey = await phantom.solana.connect();
console.log("Connected Solana account:", solanaPublicKey.toString());

// Ethereum
const ethereumAccounts = await phantom.ethereum.request({
method: "eth_requestAccounts",
});
console.log("Connected Ethereum account:", ethereumAccounts[0]);

// Use wallet functions
phantom.buy({ buy: "solana:101/nativeToken:501" }); // Buy SOL
phantom.swap({
buy: "solana:101/address:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
sell: "solana:101/nativeToken:501",
}); // Swap SOL to USDC
`

Usage Modes

The SDK supports two primary integration modes:

$3

In this mode, the Phantom wallet appears as a floating widget on your page in one of the predefined positions (bottom-right, bottom-left, top-right, top-left). This is the simplest integration method.

`typescript
import { createPhantom, Position } from "@phantom/wallet-sdk";

// Initialize the Phantom wallet as a popup
const phantom = await createPhantom({
position: Position.bottomRight, // Choose from bottomRight, bottomLeft, topRight, topLeft
hideLauncherBeforeOnboarded: false,
namespace: "my-app",
});

// Show the wallet UI
phantom.show();
`

$3

In this mode, the Phantom wallet renders inside a specific HTML element that you provide. This gives you complete control over the wallet's positioning and layout within your application.

`typescript
import { createPhantom } from "@phantom/wallet-sdk";

// Make sure the container element exists in your DOM
//

// Initialize the Phantom wallet inside your container
const phantom = await createPhantom({
element: "wallet-container", // ID of the container element
namespace: "my-app",
});

// The wallet will automatically show in the container
// You can still use show/hide methods
phantom.show();
`

Window Integration Behavior

$3

When you initialize the SDK without specifying a namespace:

`typescript
const phantom = await createPhantom();
`

The SDK behaves as follows:

1. If the Phantom browser extension is already installed, the SDK will not initialize a new embedded wallet to avoid conflicts. Your dApp will continue to use the extension.

2. If no extension is detected, the SDK will:
- Attach the wallet instance to window.phantom
- Expose blockchain RPC providers to their standard window objects:
- window.solana for Solana
- window.ethereum for Ethereum
- And other blockchain providers

This means that existing dApps built for the Phantom extension can work with the embedded wallet without code changes - the same window objects they already use will be populated by the SDK.

$3

When you specify a custom namespace:

`typescript
const phantom = await createPhantom({ namespace: "myCustomWallet" });
`

The SDK will:

1. Initialize even if the Phantom extension is installed (allowing both to coexist)
2. Attach the wallet instance to window.myCustomWallet instead of window.phantom
3. Not automatically expose providers to standard window objects to avoid conflicts with the extension

In this case, you must use the returned object for all interactions:

`typescript
// Connect to Solana using your namespaced instance
const address = await phantom.solana.connect();
`

$3

For existing dApps that detect and use standard provider patterns:

1. Extension Installed: The dApp will use the extension as normal
2. No Extension, Default Namespace: The dApp will use the embedded wallet through the standard window objects
3. Custom Namespace: You'll need to modify your dApp code to use the custom instance

$3

When you set skipInjection to true:

`typescript
// Create a wallet instance with skipInjection enabled
const phantom = await createPhantom({
skipInjection: true,
});

// All providers are available through the phantom instance only
const solanaAddress = await phantom.solana.connect();
`

The SDK will:

1. Not inject any providers into the window object, even if no extension is detected
2. Return all providers through the Phantom instance only
3. Work with the new event structure that passes providers directly in the event detail

This is useful when you want to avoid any global namespace pollution and prefer to access all functionality through the returned Phantom instance.

Configuration Options

The createPhantom function accepts the following configuration options:

`typescript
export type CreatePhantomConfig = Partial<{
zIndex: number; // Set the z-index of the wallet UI
hideLauncherBeforeOnboarded: boolean; // Hide the launcher for new users
colorScheme: string; // Light or dark mode
paddingBottom: number; // Padding from bottom of screen
paddingRight: number; // Padding from right of screen
paddingTop: number; // Padding from top of screen
paddingLeft: number; // Padding from left of screen
position: Position; // Position on screen (bottomRight, bottomLeft, topRight, topLeft)
sdkURL: string; // Custom SDK URL
element: string; // ID of element to render wallet in (for custom positioning)
namespace: string; // Namespace for the wallet instance
skipInjection: boolean; // Skip injecting providers into the window object
}>;
`

Note: When using Element Mode, the position setting is ignored since the wallet will render inside your specified container element.

Phantom Interface

The createPhantom function returns a Phantom interface with the following methods and properties:

`typescript
export interface Phantom {
// UI Controls
show: () => void; // Show the wallet UI
hide: () => void; // Hide the wallet UI

// Wallet Actions
buy: (options: { amount?: number; buy: string }) => void; // Buy tokens
swap: (options: { buy: string; sell?: string; amount?: string }) => void; // Swap tokens
navigate: ({ route, params }: { route: string; params?: any }) => void; // Navigate within wallet

// Blockchain RPC Interfaces
solana?: any; // Solana RPC interface
ethereum?: any; // Ethereum RPC interface
sui?: any; // Sui RPC interface
bitcoin?: any; // Bitcoin RPC interface

// App Interface
app: PhantomApp; // Phantom app interface
}
`

Blockchain RPC Interfaces

The SDK provides access to Phantom's blockchain-specific RPC interfaces:

- phantom.solana - Solana RPC interface
- phantom.ethereum - Ethereum, Base, Polygon and Monad Testnet RPC interface
- phantom.sui - Sui RPC interface
- phantom.bitcoin - Bitcoin RPC interface

$3

`typescript
// Connect to wallet
const address = await phantom.solana.connect();

// Sign a message
const message = new TextEncoder().encode("Hello, Solana!");
const signature = await phantom.solana.signMessage(message);

// Send a transaction
const transaction = new Transaction();
// ... add instructions ...
const signature = await phantom.solana.signAndSendTransaction(transaction);
`

For detailed examples, see Solana documentation.

$3

`typescript
// Connect to wallet
const accounts = await phantom.ethereum.request({
method: "eth_requestAccounts",
});

// Sign a message
const from = accounts[0];
const message = "Hello, Ethereum!";
const signature = await phantom.ethereum.request({
method: "personal_sign",
params: [message, from],
});

// Send a transaction
const txHash = await phantom.ethereum.request({
method: "eth_sendTransaction",
params: [
{
from,
to: "0x...",
value: "0x...",
// other tx params
},
],
});
`

For detailed examples, see Ethereum documentation.

$3

`typescript
// Connect to wallet
const accounts = await phantom.sui.connect();

// Sign a transaction
// ... create transaction ...
const signedTx = await phantom.sui.signTransaction(tx);
`

For detailed examples, see Sui documentation.

$3

`typescript
// Connect to wallet
const accounts = await phantom.bitcoin.connect();

// Sign a PSBT
// ... create PSBT ...
const signedPsbt = await phantom.bitcoin.signPsbt(psbt);
`

For detailed examples, see Bitcoin documentation.

Wallet Actions

$3

`typescript
// Buy SOL with default amount
phantom.buy({ buy: "solana:101/nativeToken:501" });

// Buy SOL with specific amount
phantom.buy({ buy: "solana:101/nativeToken:501", amount: 10 });
`

$3

`typescript
// Swap SOL to USDC
phantom.swap({
sell: "solana:101/nativeToken:501",
buy: "solana:101/address:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
});

// Swap SOL to USDC with specific amount
phantom.swap({
sell: "solana:101/nativeToken:501",
buy: "solana:101/address:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
amount: "1000000000",
});
`

Development

`bash


Install dependencies

yarn install

Start the demo app

yarn start:demo

Build all packages

yarn build
`

Frequently Asked Questions

How does the embedded wallet work with the Phantom extension?

If the Phantom extension is detected, we will not inject the embedded wallet. Phantom users can continue using their extension like normal.

If you want to use the embedded wallet and the Phantom extension, you need to instantiate the wallet with a custom namespace.




What does createPhantom() do?

The Phantom embedded wallet lives inside an iframe. The createPhantom function loads and attaches the iframe to your website.




How do I interact with the embedded wallet?

Once createPhantom has been called, window.phantom.solana and a compliant wallet-standard provider will also be available in the global scope of your website. This means that most of your existing code for interacting with Solana wallets should work out of the box.

Once a user has onboarded to the embedded wallet, they should be able to click your "connect wallet" button, which gives your website access to their Solana address. After that, signing messages and transactions should just work as normal.

If you use a namespace, you will need to invoke the functions through the window[namespace] object, or directly through the returned Phantom instance.

If you use skipInjection: true, all providers will only be available through the returned Phantom instance.




I can't see the embedded wallet on my website. What's wrong?

The most common cause is that you are using a browser with the Phantom extension installed. If the Phantom extension is detected, we will not inject the embedded wallet, unless you use a custom namespace.

You can temporarily disable the Phantom extension by going to chrome://extensions and toggling Phantom off.

How much does this cost?

It's free!

Disclaimers

The embedded wallet is a beta version, and Phantom will not be liable for any losses or damages suffered by you or your end users.

Any suggestions, enhancement requests, recommendations, or other feedback provided by you regarding the embedded wallet will be the exclusive property of Phantom. By using this beta version and providing feedback, you agree to assign any rights in that feedback to Phantom.

Give Feedback

Phantom Embedded is in active development and will be prioritizing features requested by early adopters. If you are
interested in working with us, please email us at developers@phantom.app or message @brianfriel` on Telegram.