How to Use runicRPC

This guide covers how to use runicRPC packages from npm for different use cases.

For Developers (SDK)

The SDK is the core library for adding load-balanced RPC functionality to your Solana applications.

1. Install the SDK

npm install @runic-rpc/sdk @solana/web3.js

2. Use in your project

import { RunicRPC } from '@runic-rpc/sdk';
import { PublicKey } from '@solana/web3.js';

// Auto-loads from .env (set HELIUS_API_KEY there)
const rpc = RunicRPC.create({
  strategy: 'latency-based',
});

// Or provide config directly
const rpc = RunicRPC.create({
  providers: {
    helius: { apiKey: 'YOUR_HELIUS_KEY' },
  },
  strategy: 'latency-based',
});

const balance = await rpc.request('getBalance', [new PublicKey('...')]);

Learn more: Getting Started | Configuration

---

For Quick Testing (CLI)

The CLI provides operational tools for testing your RPC providers from the terminal.

1. Install the CLI globally

npm install -g @runic-rpc/cli

2. Test your providers

Point the CLI to your .env file containing your API keys:

runic-rpc test --env .env

The CLI looks for HELIUS_API_KEY, ALCHEMY_API_KEY, or their NEXT_PUBLIC_ prefixed variants.

Example .env file:

HELIUS_API_KEY=your-helius-key
ALCHEMY_API_KEY=your-alchemy-key

Test specific providers:

runic-rpc test --providers helius --env .env

Available Commands:

• runic-rpc test - Test provider connectivity and latency
• runic-rpc init - Generate a config template (optional, for advanced settings)
• runic-rpc --help - Show all available commands

---

For Monitoring (Dashboard)

The dashboard provides a web-based monitoring interface for your RPC infrastructure.

1. Install the dashboard globally

npm install -g @runic-rpc/dashboard

2. Configure your endpoints

The dashboard reads configuration from your project. Create either:

Option A: Environment variables (.env file in your project root)

HELIUS_API_KEY=your-helius-api-key
ALCHEMY_API_KEY=your-alchemy-api-key

Option B: Config file (runic.config.json in your project root)

{
  "providers": {
    "helius": { "apiKey": "your-helius-api-key" },
    "alchemy": { "apiKey": "your-alchemy-api-key" }
  },
  "strategy": "latency-based"
}

3. Launch the dashboard

runic-rpc-dashboard --port 3000

4. Open in browser

Navigate to http://localhost:3000 to view the monitoring dashboard.

If no configuration is found, the dashboard will display setup instructions.

Features:

• Real-time provider health monitoring
• Request latency visualization
• Circuit breaker status
• Success/failure rate tracking
• Historical metrics

---

For Building Custom UIs (UI Components)

The UI package provides a shared design system with reusable React components for building custom monitoring interfaces.

1. Install the UI package

npm install @runic-rpc/ui

2. Add the Tailwind preset

In your tailwind.config.js:

module.exports = {
  presets: [require('@runic-rpc/ui/tailwind-preset')],
  // ... your other config
}

3. Import styles

In your main CSS file:

@import '@runic-rpc/ui/styles';

4. Use components

import { Button, AppShell, Sidebar } from '@runic-rpc/ui';

export default function App() {
  return (
    <AppShell>
      <Sidebar>...</Sidebar>
      <Button>Click me</Button>
    </AppShell>
  );
}

Available Components:

• AppShell - Main application layout
• Sidebar - Navigation sidebar
• Button - Styled button component
• Card - Content card component
• And more...

---

Summary Table

Package	Install Command	Use Case
@runic-rpc/sdk	npm i @runic-rpc/sdk @solana/web3.js	Add load-balanced RPC to your app
@runic-rpc/cli	npm i -g @runic-rpc/cli	Test providers from terminal
@runic-rpc/dashboard	npm i -g @runic-rpc/dashboard	Monitor RPC infrastructure
@runic-rpc/ui	npm i @runic-rpc/ui	Build custom monitoring UIs

Next Steps

• New to runicRPC? Start with the Getting Started guide
• Ready to configure? See Configuration reference
• Need help? Check Troubleshooting
• Going to production? Read Production Tips