Xolium SDK

Production-grade TypeScript SDK for building on Solana with Xolium's infrastructure layer

Installation

Package Manager

# npm
npm install @xolium/sdk @solana/web3.js
# yarn
yarn add @xolium/sdk @solana/web3.js
# pnpm
pnpm add @xolium/sdk @solana/web3.js

Required Peer Dependencies

  • • @solana/web3.js: ^1.87.0 or higher
  • • Node.js: 18.x or higher (ESM support required)
  • • TypeScript: 5.0+ recommended for full type safety

Quick Start

Basic Setup
import { XoliumClient } from '@xolium/sdk'
import { Connection, Keypair, PublicKey } from '@solana/web3.js'

// Initialize Solana connection
const connection = new Connection(
  'https://api.mainnet-beta.solana.com',
  'confirmed'
)

// Create Xolium client
const client = new XoliumClient({
  connection,
  network: 'mainnet-beta',
  // Optional: provide API key for higher rate limits
  apiKey: process.env.XOLIUM_API_KEY
})

// Set payer for transactions
const payer = Keypair.fromSecretKey(/* your secret key */)
client.setPayer(payer)
Priority Transaction Example
import { SystemProgram, LAMPORTS_PER_SOL } from '@solana/web3.js'

// Create a simple transfer instruction
const instruction = SystemProgram.transfer({
  fromPubkey: payer.publicKey,
  toPubkey: new PublicKey('...'),
  lamports: 0.1 * LAMPORTS_PER_SOL
})

// Execute with priority
const result = await client.executePriorityTransaction({
  instructions: [instruction],
  priorityLevel: 'high', // 'low' | 'medium' | 'high' | 'ultra'
  options: {
    maxRetries: 3,
    skipPreflight: false,
    commitment: 'confirmed'
  }
})

console.log('Signature:', result.signature)
console.log('Slot:', result.slot)
console.log('Credits used:', result.creditsUsed)
Optimized Swap Routing
// Find optimal route for token swap
const route = await client.findOptimalRoute({
  inputMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  outputMint: 'So11111111111111111111111111111111111111112', // SOL
  amount: 1000_000000, // 1000 USDC (6 decimals)
  slippageBps: 50, // 0.5% slippage tolerance
  options: {
    splitRoutes: true, // Enable split routing for better execution
    maxHops: 2, // Maximum number of intermediate tokens
    excludeDexes: [], // Optionally exclude specific DEXs
    onlyDirectRoutes: false // Set true to skip multi-hop routes
  }
})

console.log('Expected output:', route.expectedOutput)
console.log('Price impact:', route.priceImpact, '%')
console.log('Route:', route.path.map(p => p.dex).join(' -> '))

// Execute the swap
const swapResult = await client.executeSwap({
  route,
  priorityLevel: 'medium'
})

console.log('Swap completed:', swapResult.signature)

SDK Features

Priority Execution

Submit transactions with guaranteed priority placement and MEV protection

client.executePriorityTransaction({ instructions: TransactionInstruction[], priorityLevel: 'high', options?: { maxRetries?: number, skipPreflight?: boolean, commitment?: Commitment } })
Returns: ExecutionResult with signature, slot, and credits consumed
Liquidity Routing

Multi-DEX aggregation with intelligent routing across Raydium, Orca, Meteora, and more

client.findOptimalRoute({ inputMint: string, outputMint: string, amount: number | bigint, slippageBps: number, options?: RouteOptions })
Supported DEXs: Raydium, Orca, Meteora, Phoenix, Lifinity
Max routes evaluated: 1000+ paths per query
Optimization target: Best output considering fees and slippage
Staking Operations

Stake XOL tokens with flexible lock periods and auto-compounding rewards

client.stake({ amount: number, duration: '7d' | '30d' | '90d' | '365d', autoCompound?: boolean })
APY by Duration:
  • • 7 days: 12% APY (flexible)
  • • 30 days: 18% APY
  • • 90 days: 28% APY
  • • 365 days: 45% APY
Analytics & Monitoring

Real-time network metrics, transaction history, and performance analytics

// Network metrics client.getNetworkMetrics({ timeframe: '1h' | '24h' | '7d' | '30d' }) // Transaction history client.getTransactionHistory({ address: publicKey, limit: 50 }) // Real-time monitoring client.subscribeToTransactions({ address: publicKey, callback: (tx) => console.log(tx) })
Available Metrics: TVL, 24h volume, success rate, avg confirmation time, active users

Advanced Usage

Error Handling & Retries
import { XoliumError, ErrorCode } from '@xolium/sdk'

try {
  const result = await client.executePriorityTransaction({
    instructions: [...],
    priorityLevel: 'high',
    options: {
      maxRetries: 3,
      retryDelay: 1000, // ms between retries
      skipPreflight: false
    }
  })
} catch (error) {
  if (error instanceof XoliumError) {
    switch (error.code) {
      case ErrorCode.INSUFFICIENT_CREDITS:
        console.error('Not enough execution credits')
        break
      case ErrorCode.TRANSACTION_EXPIRED:
        console.error('Transaction expired, please retry')
        break
      case ErrorCode.SLIPPAGE_EXCEEDED:
        console.error('Slippage tolerance exceeded')
        break
      default:
        console.error('Unknown error:', error.message)
    }
  }
}
WebSocket Subscriptions
// Subscribe to transaction updates
const subscription = client.subscribeToTransactions({
  address: wallet.publicKey,
  callback: (update) => {
    console.log('Status:', update.status) // 'pending' | 'confirmed' | 'finalized' | 'failed'
    console.log('Signature:', update.signature)
    console.log('Confirmations:', update.confirmations)
  },
  onError: (error) => {
    console.error('Subscription error:', error)
  }
})

// Subscribe to price updates
const priceSubscription = client.subscribeToPrices({
  tokens: ['SOL', 'USDC', 'XOL'],
  callback: (prices) => {
    console.log('Updated prices:', prices)
  }
})

// Cleanup
subscription.unsubscribe()
priceSubscription.unsubscribe()
Batch Operations
// Execute multiple transactions atomically
const results = await client.executeBatch({
  transactions: [
    {
      instructions: [...],
      priorityLevel: 'medium'
    },
    {
      instructions: [...],
      priorityLevel: 'high'
    }
  ],
  options: {
    atomic: true, // All succeed or all fail
    parallel: false // Execute sequentially
  }
})

results.forEach((result, index) => {
  console.log(`Transaction ${index + 1}: ${result.signature}`)
})

Supported Environments

Node.js

Version 18.x or higher with ESM support

type: "module"

Required in package.json for ESM imports

TypeScript

Version 5.x with full type definitions

Recommended tsconfig.json settings:

"moduleResolution": "bundler"
"strict": true

Browsers

Modern browsers with ES2020+ support

Works with all major wallets:

  • • Phantom
  • • Solflare
  • • Backpack

API Reference

XoliumClient

constructor(config: ClientConfig)

Initialize a new Xolium client instance

Parameters:
  • • connection: Connection - Solana RPC connection
  • • network: 'mainnet-beta' | 'devnet' - Network selection
  • • apiKey?: string - Optional API key for rate limits
executePriorityTransaction(params: ExecuteParams): Promise<ExecutionResult>

Execute transaction with priority placement

Returns: ExecutionResult
  • • signature: string - Transaction signature
  • • slot: number - Confirmed slot number
  • • creditsUsed: number - Execution credits consumed
findOptimalRoute(params: RouteParams): Promise<RouteInfo>

Calculate best swap route across DEXs

Returns: RouteInfo
  • • path: RouteStep[] - Swap path with DEXs
  • • expectedOutput: bigint - Expected output amount
  • • priceImpact: number - Estimated price impact %
  • • estimatedGas: number - Gas cost estimate
stake(params: StakeParams): Promise<StakeResult>

Stake XOL tokens for yield

Parameters:
  • • amount: number - Amount of XOL to stake
  • • duration: '7d' | '30d' | '90d' | '365d'
  • • autoCompound?: boolean - Auto-compound rewards

Resources

GitHub Repository

View source code, report issues, and contribute to the SDK development

⭐ 1.2k stars
🔀 89 forks
🐛 12 issues
View on GitHub

NPM Package

View package details, version history, and download statistics

📦 v2.1.3
⬇️ 45k/week
📄 MIT License
View on NPM