API Reference

Complete reference for all supported RPC methods and SDK features.

Supported Providers

runicRPC currently supports the following RPC providers with built-in configuration:

Supported RPC Methods

The SDK acts as a pass-through proxy for all standard Solana JSON-RPC methods. Below are the commonly used methods:

Auto-Cached Methods

These methods are automatically cached by runicRPC with configurable TTL:

const DEFAULT_CACHEABLE_METHODS = [
  'getSlot',
  'getBalance',
  'getAccountInfo',
  'getBlockHeight',
  'getEpochInfo',
  'getHealth',
  'getVersion',
  'getGenesisHash',
];

You can customize which methods are cached using the cacheableMethods config option:

const rpc = RunicRPC.create({
  cache: {
    enabled: true,
    cacheableMethods: ['getSlot', 'getBalance', 'getBlockHeight'] // custom list
  }
});

Account Methods

Block and Slot Methods

Network Methods

Transaction Methods

WebSocket Subscriptions

SDK API

RunicRPC Class

import { RunicRPC } from '@runic-rpc/sdk';

// Create instance
const rpc = RunicRPC.create(config?, options?);

// Make requests
const result = await rpc.request<T>(method: string, params?: unknown[]): Promise<T>;

// Batch requests (JSON-RPC 2.0)
const results = await rpc.batchRequest<T>(requests: BatchRequest[]): Promise<T[]>;

// Request to specific provider (for provider-specific APIs)
const result = await rpc.requestToProvider<T>(
  provider: string,
  method: string,
  params?: unknown[]
): Promise<T>;

// Select endpoint for method (provider-specific routing)
const endpoint = rpc.selectEndpointForMethod(method: string): Endpoint;

// Subscribe (WebSocket)
const subId = await rpc.subscribe(method: string, params: unknown[], callback: (data: unknown) => void): Promise<number>;

// Unsubscribe
await rpc.unsubscribe(subscriptionId: number): Promise<void>;

// Get statistics
const stats = rpc.getStats(): GlobalStats;

// Export Prometheus metrics
const metrics = rpc.exportPrometheusMetrics(): string;

// Event listeners
rpc.on(event: string, listener: (data: unknown) => void): void;
rpc.off(event: string, listener: (data: unknown) => void): void;

// Cleanup
await rpc.close(): Promise<void>;

Batch Requests

Send multiple RPC calls in a single HTTP request:

interface BatchRequest {
  method: string;
  params?: unknown[];
}

const results = await rpc.batchRequest([
  { method: 'getSlot' },
  { method: 'getBalance', params: [publicKey] },
  { method: 'getBlockHeight' },
]);

// Results are returned in the same order as requests
const [slot, balance, blockHeight] = results;

Provider-Specific Routing

Route requests to specific providers for their enhanced APIs:

// Route Helius DAS calls to Helius
const assets = await rpc.requestToProvider('helius', 'getAssetsByOwner', [
  { ownerAddress: 'wallet-address' }
]);

// The SDK automatically routes known provider-specific methods
// Helius: getAssetsByOwner, getAsset, searchAssets, getPriorityFeeEstimate
// Alchemy: getTokenBalances, getTokenMetadata

Configuration Interface

interface RunicRPCConfig {
  // Provider configurations
  providers?: {
    helius?: { apiKey: string };
    alchemy?: { apiKey: string };
    quicknode?: { rpcUrl: string; wsUrl?: string };
  };

  // Custom endpoints
  endpoints?: EndpointConfig[];

  // Routing strategy
  strategy?: 'round-robin' | 'latency-based' | 'weighted' | 'random';

  // Cache settings
  cache?: {
    enabled?: boolean;
    ttl?: number;      // milliseconds
    maxSize?: number;  // max entries
    cacheableMethods?: string[]; // custom cacheable methods
  };

  // Retry settings
  retry?: {
    maxAttempts?: number;
    initialDelay?: number;
    maxDelay?: number;
    backoffMultiplier?: number;
  };

  // Circuit breaker settings
  circuitBreaker?: {
    failureThreshold?: number;
    successThreshold?: number;
    timeout?: number;
  };

  // Health check settings
  healthCheck?: {
    enabled?: boolean;
    interval?: number;
    timeout?: number;
    unhealthyThreshold?: number;
    healthyThreshold?: number;
    probeMethod?: string;    // primary health check method (default: 'getHealth')
    probeFallback?: string;  // fallback method (default: 'getSlot')
  };

  // Middleware hooks
  middleware?: {
    beforeRequest?: (method: string, params?: unknown[]) => Promise<unknown[]>;
    afterResponse?: <T>(method: string, result: T) => Promise<T>;
    onError?: (method: string, error: Error) => Promise<void>;
  };

  // Rate limiting
  rateLimit?: number;  // requests per second

  // Logging
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
}

Event Types

type RunicRPCEvent =
  | { type: 'endpoint:healthy'; endpoint: string }
  | { type: 'endpoint:unhealthy'; endpoint: string; reason: string }
  | { type: 'endpoint:selected'; endpoint: string; method: string }
  | { type: 'request:start'; method: string; params?: unknown[] }
  | { type: 'request:success'; method: string; duration: number; endpoint: string }
  | { type: 'request:error'; method: string; error: Error; endpoint: string }
  | { type: 'request:retry'; method: string; attempt: number; endpoint: string }
  | { type: 'request:deduplicated'; method: string }
  | { type: 'cache:hit'; method: string }
  | { type: 'cache:miss'; method: string }
  | { type: 'circuit:open'; endpoint: string }
  | { type: 'circuit:halfOpen'; endpoint: string }
  | { type: 'circuit:closed'; endpoint: string }
  | { type: 'ws:reconnect'; endpoint: string; attempt: number }
  | { type: 'batch:start'; count: number }
  | { type: 'batch:complete'; count: number; duration: number };

Error Classes

import {
  RunicRpcError,
  RpcRequestError,
  CircuitBreakerOpenError,
  HealthCheckError,
  RateLimitError,
  NoHealthyEndpointsError,
  BatchRequestError,
  ProviderNotFoundError,
} from '@runic-rpc/sdk';

Provider Helper Functions

import {
  createHeliusEndpoint,
  createAlchemyEndpoint,
  createQuicknodeEndpoint,
  createPublicEndpoint,
} from '@runic-rpc/sdk';

// Helius
const helius = createHeliusEndpoint('your-api-key');

// Alchemy
const alchemy = createAlchemyEndpoint('your-api-key');

// QuickNode
const quicknode = createQuicknodeEndpoint(
  'https://your-endpoint.quiknode.pro/token/',
  'wss://your-endpoint.quiknode.pro/token/'
);

// Public (rate limited)
const publicRpc = createPublicEndpoint();

Next Steps

• Try the API Playground to test methods interactively
• Configure routing strategies
• Set up WebSocket subscriptions