API reference - Phantom developer documentation

The Server SDK is currently experimental and not ready for production use. Reach out to partnerships@phantom.com for access.

This page provides a comprehensive reference for all methods, types, and utilities available in the Phantom Server SDK.

ServerSDK class

Constructor

new ServerSDK(config: ServerSDKConfig)

Creates a new instance of the Server SDK.

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

Network information

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.

​ServerSDK class

​Constructor

​Parameters

​ServerSDKConfig type

​Example

​Methods

​createWallet

​Parameters

​Returns

​Example

​getWallets

​Parameters

​Returns

​Example

​getWalletAddresses

​Parameters

​Returns

​Example

​signTransaction

​Parameters

​Returns

​Example

​signAndSendTransaction

​Parameters

​Returns

​Example

​signMessage

​Parameters

​Returns

​Example

​Types

​CreateWalletResult

​WalletAddress

​Wallet

​GetWalletsResult

​ParsedTransactionResult

​ParsedSignatureResult

​NetworkId enum

​Solana networks

​Ethereum networks

​Other EVM networks

​Future networks

​Utility functions

​Network information

​getNetworkDescription

​getSupportedNetworkIds

​getNetworkIdsByChain

​supportsTransactionSubmission

​Error handling

​Common errors

​Error types

​Rate limits

​Complete example

​CAIP-2 network utilities

​License

​Next steps

​Disclaimers

ServerSDK class

Constructor

Parameters

ServerSDKConfig type

Example

Methods

createWallet

Parameters

Returns

Example

getWallets

Parameters

Returns

Example

getWalletAddresses

Parameters

Returns

Example

signTransaction

Parameters

Returns

Example

signAndSendTransaction

Parameters

Returns

Example

signMessage

Parameters

Returns

Example

Types

CreateWalletResult

WalletAddress

Wallet

GetWalletsResult

ParsedTransactionResult

ParsedSignatureResult

NetworkId enum

Solana networks

Ethereum networks

Other EVM networks

Future networks

Utility functions

Network information

getNetworkDescription

getSupportedNetworkIds

getNetworkIdsByChain

supportsTransactionSubmission

Error handling

Common errors

Error types

Rate limits

Complete example

CAIP-2 network utilities

License

Next steps

Disclaimers