> ## 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.

# API reference

> Complete API reference for Phantom Server SDK methods, types, and utilities

<Danger>
  The Server SDK is currently experimental and not ready for production use. Reach out to [partnerships@phantom.com](mailto:partnerships@phantom.com) for access.
</Danger>

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

## ServerSDK class

### Constructor

```typescript theme={null}
new ServerSDK(config: ServerSDKConfig)
```

Creates a new instance of the Server SDK.

#### Parameters

`config` (ServerSDKConfig): Configuration object.

#### ServerSDKConfig type

```typescript theme={null}
interface ServerSDKConfig {
  organizationId: string;      // Your organization ID
  apiPrivateKey: string;       // Base58-encoded private key
  appId: string;               // Your app ID
}
```

#### Example

```typescript theme={null}
const sdk = new ServerSDK({
  organizationId: 'org_abc123',
  apiPrivateKey: '5Kb8kLf9zgW...',
  appId: 'your-app-id'
});
```

### Methods

## createWallet

Creates a new wallet with addresses for multiple blockchains.

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
// 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.

```typescript theme={null}
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

```typescript theme={null}
// 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.

```typescript theme={null}
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

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
const result = await sdk.signAndSendTransaction({ 
  walletId,
  transaction,
  networkId: NetworkId.SOLANA_MAINNET,
});

console.log("Transaction hash:", result.hash);
```

## signMessage

Signs an arbitrary message.

```typescript theme={null}
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

```typescript theme={null}
const signature = await sdk.signMessage({
  walletId,
  message: 'Authenticate with our service',
  networkId: NetworkId.ETHEREUM_MAINNET
});
```

## Types

### CreateWalletResult

```typescript theme={null}
interface CreateWalletResult {
  walletId: string;
  addresses: WalletAddress[];
}
```

### WalletAddress

```typescript theme={null}
interface WalletAddress {
  addressType: string;  // 'Solana', 'Ethereum', and so on
  address: string;      // The blockchain address
}
```

### Wallet

```typescript theme={null}
interface Wallet {
  walletId: string;
  walletName?: string;
  createdAt: string;
  updatedAt: string;
}
```

### GetWalletsResult

```typescript theme={null}
interface GetWalletsResult {
  wallets: Wallet[];
  totalCount: number;
  limit: number;
  offset: number;
}
```

### ParsedTransactionResult

```typescript theme={null}
interface ParsedTransactionResult {
  rawTransaction: string;  // Signed transaction payload
  hash?: string;           // Transaction hash (present when submitted via signAndSendTransaction)
}
```

### ParsedSignatureResult

```typescript theme={null}
interface ParsedSignatureResult {
  signature: string;       // The message signature
}
```

## NetworkId enum

The `NetworkId` enum specifies which blockchain network to use:

### Solana networks

```typescript theme={null}
NetworkId.SOLANA_MAINNET    // 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'
NetworkId.SOLANA_DEVNET     // 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1'
NetworkId.SOLANA_TESTNET    // 'solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z'
```

### Ethereum networks

```typescript theme={null}
NetworkId.ETHEREUM_MAINNET  // 'eip155:1'
NetworkId.ETHEREUM_GOERLI   // 'eip155:5'
NetworkId.ETHEREUM_SEPOLIA  // 'eip155:11155111'
```

### Other EVM networks

```typescript theme={null}
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

```typescript theme={null}
NetworkId.BITCOIN_MAINNET   // 'bip122:000000000019d6689c085ae165831e93'
NetworkId.SUI_MAINNET       // 'sui:35834a8a'
```

## Utility functions

### Network information

```typescript theme={null}
import { 
  getNetworkDescription,
  getSupportedNetworkIds,
  getNetworkIdsByChain,
  supportsTransactionSubmission
} from '@phantom/server-sdk';
```

#### getNetworkDescription

Get a human-readable description of a network.

```typescript theme={null}
getNetworkDescription(networkId: NetworkId): string
```

```typescript theme={null}
const description = getNetworkDescription(NetworkId.ETHEREUM_MAINNET);
// Returns: "Ethereum Mainnet"
```

#### getSupportedNetworkIds

Get all supported network IDs.

```typescript theme={null}
getSupportedNetworkIds(): NetworkId[]
```

```typescript theme={null}
const networks = getSupportedNetworkIds();
// Returns array of all NetworkId values
```

#### getNetworkIdsByChain

Get all networks for a specific blockchain.

```typescript theme={null}
getNetworkIdsByChain(chain: 'solana' | 'ethereum' | 'polygon' | ...): NetworkId[]
```

```typescript theme={null}
const solanaNetworks = getNetworkIdsByChain('solana');
// Returns: [SOLANA_MAINNET, SOLANA_DEVNET, SOLANA_TESTNET]
```

#### supportsTransactionSubmission

Check if a network supports automatic transaction submission.

```typescript theme={null}
supportsTransactionSubmission(networkId: NetworkId): boolean
```

```typescript theme={null}
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

```typescript theme={null}
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

1. Configuration errors: Missing or invalid configuration.
2. Authentication errors: Invalid credentials or unauthorized access.
3. Validation errors: Invalid parameters or data.
4. Network errors: Connection or timeout issues.
5. 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](https://github.com/phantom/phantom-connect-sdk/blob/main/LICENSE) file for details.

## Next steps

* [View example implementations](https://github.com/phantom/phantom-connect-sdk/tree/main/examples/server-sdk-examples)
* [Read the integration guide](/sdks/server-sdk/integration-guide)

## 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.