Documentation Index
Fetch the complete documentation index at: https://docs.phantom.com/llms.txt
Use this file to discover all available pages before exploring further.
The Server SDK is currently experimental and not ready for production use. Reach out to partnerships@phantom.com for access. ServerSDK class
Constructor
new ServerSDK(config: ServerSDKConfig)
Parameters
config (ServerSDKConfig): Configuration object.
ServerSDKConfig type
interface ServerSDKConfig {
organizationId: string; // Your organization ID
apiPrivateKey: string; // Base58-encoded private key
appId: string; // Your app ID
}
Example
const sdk = new ServerSDK({
organizationId: 'org_abc123',
apiPrivateKey: '5Kb8kLf9zgW...',
appId: 'your-app-id'
});
Methods
createWallet
Creates a new wallet with addresses for multiple blockchains.
createWallet(walletName?: string): Promise<CreateWalletResult>
Parameters
walletName (string, optional): Custom name for the wallet.
Returns
Promise<CreateWalletResult>: Object containing:
walletId (string): Unique identifier for the wallet.addresses (WalletAddress[]): Array of blockchain addresses.
Example
const wallet = await sdk.createWallet('Customer Wallet');
console.log('Wallet ID:', wallet.walletId);
console.log('Addresses:', wallet.addresses);
getWallets
Lists all wallets in your organization with pagination support.
getWallets(limit?: number, offset?: number): Promise<GetWalletsResult>
Parameters
limit (number, optional): Number of results per page (default: 20, max: 100).offset (number, optional): Pagination offset (default: 0).
Returns
Promise<GetWalletsResult>: Object containing:
wallets (Wallet[]): Array of wallet objects.totalCount (number): Total number of wallets.limit (number): Results per page.offset (number): Current offset.
Example
// Get first 50 wallets
const page1 = await sdk.getWallets(50, 0);
// Get next 50 wallets
const page2 = await sdk.getWallets(50, 50);
console.log(`Total wallets: ${page1.totalCount}`);
getWalletAddresses
Retrieves addresses for a specific wallet.
getWalletAddresses(
walletId: string,
derivationPaths?: string[]
): Promise<WalletAddress[]>
Parameters
walletId (string): The wallet ID.derivationPaths (string[], optional): Custom derivation paths.
Returns
Promise<WalletAddress[]>: Array of wallet addresses.
Example
// Get all addresses
const addresses = await sdk.getWalletAddresses(walletId);
// Get specific addresses by derivation path
const customAddresses = await sdk.getWalletAddresses(
walletId,
["m/44'/501'/0'/0'", "m/44'/60'/0'/0/0"]
);
signTransaction
Signs a transaction without submitting it to the network. Use this when you want to broadcast the transaction yourself.
signTransaction({
walletId: string,
transaction: any,
networkId: NetworkId,
derivationIndex?: number,
account?: string
}): Promise<ParsedTransactionResult>
Parameters
walletId (string): The wallet ID to sign with.transaction (any): The transaction to sign. Accepts @solana/web3.js transaction objects, EVM transaction objects (viem or ethers.js), hex strings, or raw bytes.networkId (NetworkId): The target network.derivationIndex (number, optional): Account derivation index (defaults to 0).account (string, optional): Specific account address for simulation.
Returns
Promise<ParsedTransactionResult>: Object containing:
rawTransaction (string): The signed transaction payload.
Example
const signed = await sdk.signTransaction({
walletId,
transaction,
networkId: NetworkId.SOLANA_MAINNET,
});
console.log("Signed payload:", signed.rawTransaction);
signAndSendTransaction
Signs a transaction and submits it to the network.
signAndSendTransaction({
walletId: string,
transaction: any,
networkId: NetworkId,
derivationIndex?: number,
account?: string
}): Promise<ParsedTransactionResult>
Parameters
walletId (string): The wallet ID to sign with.transaction (any): The transaction to sign. Accepts @solana/web3.js transaction objects, EVM transaction objects (viem or ethers.js), hex strings, or raw bytes.networkId (NetworkId): The target network.derivationIndex (number, optional): Account derivation index (defaults to 0).account (string, optional): Specific account address for simulation.
Returns
Promise<ParsedTransactionResult>: Object containing:
rawTransaction (string): The signed transaction payload.hash (string): The transaction hash (when submitted to the network).
Example
const result = await sdk.signAndSendTransaction({
walletId,
transaction,
networkId: NetworkId.SOLANA_MAINNET,
});
console.log("Transaction hash:", result.hash);
signMessage
Signs an arbitrary message.
signMessage({
walletId: string,
message: string,
networkId: NetworkId
}): Promise<string>
Parameters
walletId (string): The wallet ID to sign with.message (string): The message to sign.networkId (NetworkId): The network context for signing.
Returns
Promise<string>: Base64-encoded signature.
Example
const signature = await sdk.signMessage({
walletId,
message: 'Authenticate with our service',
networkId: NetworkId.ETHEREUM_MAINNET
});
Types
CreateWalletResult
interface CreateWalletResult {
walletId: string;
addresses: WalletAddress[];
}
WalletAddress
interface WalletAddress {
addressType: string; // 'Solana', 'Ethereum', and so on
address: string; // The blockchain address
}
Wallet
interface Wallet {
walletId: string;
walletName?: string;
createdAt: string;
updatedAt: string;
}
GetWalletsResult
interface GetWalletsResult {
wallets: Wallet[];
totalCount: number;
limit: number;
offset: number;
}
ParsedTransactionResult
interface ParsedTransactionResult {
rawTransaction: string; // Signed transaction payload
hash?: string; // Transaction hash (present when submitted via signAndSendTransaction)
}
ParsedSignatureResult
interface ParsedSignatureResult {
signature: string; // The message signature
}
NetworkId enum
The NetworkId enum specifies which blockchain network to use:
Solana networks
NetworkId.SOLANA_MAINNET // 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
NetworkId.SOLANA_DEVNET // 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1'
NetworkId.SOLANA_TESTNET // 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z'
Ethereum networks
NetworkId.ETHEREUM_MAINNET // 'eip155:1'
NetworkId.ETHEREUM_GOERLI // 'eip155:5'
NetworkId.ETHEREUM_SEPOLIA // 'eip155:11155111'
Other EVM networks
NetworkId.POLYGON_MAINNET // 'eip155:137'
NetworkId.POLYGON_MUMBAI // 'eip155:80001'
NetworkId.OPTIMISM_MAINNET // 'eip155:10'
NetworkId.ARBITRUM_ONE // 'eip155:42161'
NetworkId.BASE_MAINNET // 'eip155:8453'
Future networks
NetworkId.BITCOIN_MAINNET // 'bip122:000000000019d6689c085ae165831e93'
NetworkId.SUI_MAINNET // 'sui:35834a8a'
Utility functions
import {
getNetworkDescription,
getSupportedNetworkIds,
getNetworkIdsByChain,
supportsTransactionSubmission
} from '@phantom/server-sdk';
getNetworkDescription
Get a human-readable description of a network.
getNetworkDescription(networkId: NetworkId): string
const description = getNetworkDescription(NetworkId.ETHEREUM_MAINNET);
// Returns: "Ethereum Mainnet"
getSupportedNetworkIds
Get all supported network IDs.
getSupportedNetworkIds(): NetworkId[]
const networks = getSupportedNetworkIds();
// Returns array of all NetworkId values
getNetworkIdsByChain
Get all networks for a specific blockchain.
getNetworkIdsByChain(chain: 'solana' | 'ethereum' | 'polygon' | ...): NetworkId[]
const solanaNetworks = getNetworkIdsByChain('solana');
// Returns: [SOLANA_MAINNET, SOLANA_DEVNET, SOLANA_TESTNET]
supportsTransactionSubmission
Check if a network supports automatic transaction submission.
supportsTransactionSubmission(networkId: NetworkId): boolean
if (supportsTransactionSubmission(NetworkId.SOLANA_MAINNET)) {
// Network supports automatic submission
}
Error handling
The SDK throws errors for various failure scenarios. Always wrap SDK calls in try-catch blocks:
Common errors
try {
const wallet = await sdk.createWallet();
} catch (error) {
if (error.message.includes('organizationId')) {
// Configuration error
} else if (error.message.includes('unauthorized')) {
// Authentication error
} else if (error.message.includes('network')) {
// Network error
} else {
// Unknown error
}
}
Error types
- Configuration errors: Missing or invalid configuration.
- Authentication errors: Invalid credentials or unauthorized access.
- Validation errors: Invalid parameters or data.
- Network errors: Connection or timeout issues.
- Wallet errors: Wallet not found or access denied.
Rate limits
The Phantom API implements rate limiting to ensure fair usage:
- Wallet Creation: Limited per organization.
- Transaction Signing: Limited per wallet.
- API calls: General rate limit per organization.
Handle rate limit errors gracefully:
async function createWalletWithRetry(name: string) {
try {
return await sdk.createWallet(name);
} catch (error) {
if (error.message.includes('rate limit')) {
// Wait and retry
await new Promise(resolve => setTimeout(resolve, 60000));
return await sdk.createWallet(name);
}
throw error;
}
}
Complete example
Here’s a complete example using multiple SDK features:
import { ServerSDK, NetworkId } from '@phantom/server-sdk';
import { Connection, Transaction, SystemProgram, PublicKey } from '@solana/web3.js';
class WalletManager {
private sdk: ServerSDK;
private connection: Connection;
constructor() {
this.sdk = new ServerSDK({
organizationId: process.env.PHANTOM_ORG_ID!,
apiPrivateKey: process.env.PHANTOM_PRIVATE_KEY!,
appId: process.env.PHANTOM_APP_ID!
});
this.connection = new Connection('https://api.mainnet-beta.solana.com');
}
async createUserWallet(userId: string) {
// Create wallet
const wallet = await this.sdk.createWallet(`user_${userId}`);
// Get Solana address
const solanaAddress = wallet.addresses.find(
addr => addr.addressType === 'Solana'
)?.address;
return {
walletId: wallet.walletId,
solanaAddress,
allAddresses: wallet.addresses
};
}
async sendPayment(
walletId: string,
fromAddress: string,
toAddress: string,
amountSol: number
) {
// Create transaction
const transaction = new Transaction().add(
SystemProgram.transfer({
fromPubkey: new PublicKey(fromAddress),
toPubkey: new PublicKey(toAddress),
lamports: amountSol * 1e9
})
);
// Prepare transaction
const { blockhash } = await this.connection.getLatestBlockhash();
transaction.recentBlockhash = blockhash;
transaction.feePayer = new PublicKey(fromAddress);
// Sign and send
const signed = await this.sdk.signAndSendTransaction({
walletId,
transaction: transaction.serialize({
requireAllSignatures: false,
verifySignatures: false
}),
networkId: NetworkId.SOLANA_MAINNET
});
return signed;
}
async authenticateUser(walletId: string, challenge: string) {
// Sign authentication challenge
const signature = await this.sdk.signMessage(
walletId,
challenge,
NetworkId.SOLANA_MAINNET
);
return signature;
}
async listAllWallets() {
const allWallets = [];
let offset = 0;
while (true) {
const result = await this.sdk.getWallets(100, offset);
allWallets.push(...result.wallets);
if (offset + result.wallets.length >= result.totalCount) {
break;
}
offset += 100;
}
return allWallets;
}
}
CAIP-2 network utilities
The SDK includes utilities for working with CAIP-2 network identifiers:
import {
deriveSubmissionConfig,
supportsTransactionSubmission,
getNetworkDescription,
getSupportedNetworkIds,
getNetworkIdsByChain
} from '@phantom/server-sdk';
// Check if a network supports transaction submission
if (supportsTransactionSubmission(NetworkId.SOLANA_MAINNET)) {
// Network supports automatic transaction submission
}
// Get human-readable network description
const description = getNetworkDescription(NetworkId.ETHEREUM_MAINNET);
// Returns: "Ethereum Mainnet"
// List all supported networks
const allNetworks = getSupportedNetworkIds();
// Get all networks for a specific chain
const solanaNetworks = getNetworkIdsByChain('solana');
// Returns: [SOLANA_MAINNET, SOLANA_DEVNET, SOLANA_TESTNET]
License
This SDK is distributed under the MIT License. See the LICENSE file for details.
Next steps
Disclaimers
The Server SDK 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 Server SDK 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.
