The Server SDK is currently experimental and not ready for production use.

API Reference

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"]
);

signAndSendTransaction

Signs a transaction and optionally submits it to the network.

signAndSendTransaction({
  walletId: string,
  transaction: Transaction,
  networkId: NetworkId
}): Promise<SignedTransaction>

Parameters

walletId (string) - The wallet ID to sign with
transaction (string) - The web3js transaction
networkId (NetworkId) - The target network

Returns

Promise<SignedTransaction> - Object containing:

rawTransaction (string) - Base64-encoded signed transaction

Example

const signed = await sdk.signAndSendTransaction({ 
  walletId,
  transaction,
  networkId: NetworkId.SOLANA_MAINNET
});

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', etc.
  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;
}

SignedTransaction

interface SignedTransaction {
  rawTransaction: string;  // Base64-encoded transaction
}

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,
      message: challenge,
      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.

Building with Phantom

Solana

Ethereum, Monad, Base & Polygon

Sui

Bitcoin

​API Reference

​ServerSDK Class

​Constructor

​Parameters

​ServerSDKConfig Type

​Example

​Methods

​createWallet

​Parameters

​Returns

​Example

​getWallets

​Parameters

​Returns

​Example

​getWalletAddresses

​Parameters

​Returns

​Example

​signAndSendTransaction

​Parameters

​Returns

​Example

​signMessage

​Parameters

​Returns

​Example

​Types

​CreateWalletResult

​WalletAddress

​Wallet

​GetWalletsResult

​SignedTransaction

​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

API Reference

ServerSDK Class

Constructor

Parameters

ServerSDKConfig Type

Example

Methods

createWallet

Parameters

Returns

Example

getWallets

Parameters

Returns

Example

getWalletAddresses

Parameters

Returns

Example

signAndSendTransaction

Parameters

Returns

Example

signMessage

Parameters

Returns

Example

Types

CreateWalletResult

WalletAddress

Wallet

GetWalletsResult

SignedTransaction

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