@elizaos/plugin-helius

A comprehensive Helius blockchain data provider plugin for ElizaOS agents. This plugin enables agents to access Solana blockchain data including wallet information, transaction history, trades, and token balances through the Helius API.

Features

• Wallet Information: Get detailed wallet data including SOL balance and account info
• Transaction History: Fetch and parse recent transactions for any Solana wallet
• Trade Tracking: Monitor swap and trade activity with detailed information
• Token Balances: Retrieve all SPL token holdings for a wallet
• Rate Limiting: Built-in rate limiting and retry logic for API reliability
• Caching: Intelligent caching system to reduce API calls and improve performance
• Batch Analysis: Analyze multiple wallets concurrently with controlled parallelism

Installation

bun add @elizaos/plugin-helius

Configuration

Environment Variables

Add your Helius API key to your .env file:

HELIUS_API_KEY=your_helius_api_key_here
WALLET_PUBLIC_KEY=optional_default_wallet_address

Plugin Registration

Register the plugin in your agent configuration:

import { heliusPlugin } from '@elizaos/plugin-helius';

const agent = {
  // ... other config
  plugins: [heliusPlugin],
};

Usage

As a Provider

The Helius provider automatically enriches agent context with wallet information when a Solana wallet address is mentioned in conversation or available in the agent's state.

The provider will:

1. Extract wallet addresses from message text
2. Fall back to state.walletAddress or WALLET_PUBLIC_KEY setting
3. Fetch comprehensive wallet data from Helius API
4. Format and inject the data into the agent's context

Direct API Usage

You can also use the Helius API class directly in your actions or services:

import { HeliusAPI } from '@elizaos/plugin-helius';

const heliusAPI = new HeliusAPI(runtime.getSetting('HELIUS_API_KEY'));

// Get wallet info
const walletInfo = await heliusAPI.getWalletInfo('wallet_address');

// Get recent transactions
const transactions = await heliusAPI.getTransactions('wallet_address', { limit: 10 });

// Get trades
const trades = await heliusAPI.getTrades('wallet_address', { limit: 10 });

// Get token balances
const tokenBalances = await heliusAPI.getTokenBalances('wallet_address');

// Comprehensive wallet analysis
const analysis = await heliusAPI.analyzeWallet('wallet_address');

// Batch analyze multiple wallets
const results = await heliusAPI.analyzeWalletsBatch(['wallet1', 'wallet2'], 5);

API Reference

HeliusAPI Class

Constructor

new HeliusAPI(apiKey: string)

Methods

• getWalletInfo(walletAddress: string): Promise<IWalletInfo>

  • Get wallet balance and account information

• getTransactions(walletAddress: string, options?: TransactionOptions): Promise<ITransaction[]>

  • Fetch transaction history with optional filters

• getTrades(walletAddress: string, options?: TradeOptions): Promise<ITrade[]>

  • Get swap/trade activity

• getTokenBalances(walletAddress: string): Promise<any[]>

  • Retrieve all SPL token balances

• analyzeWallet(walletAddress: string): Promise<WalletAnalysis>

  • Comprehensive wallet analysis combining all data sources

• analyzeWalletsBatch(walletAddresses: string[], maxConcurrent?: number): Promise<Map<string, any>>

  • Batch analyze multiple wallets with concurrency control

• clearCache(): void

  • Clear the internal cache

• getCacheStats(): { size: number; keys: string[] }

  • Get cache statistics

Features in Detail

Rate Limiting

The plugin implements automatic rate limiting with:

• 200ms delay between API calls
• Automatic retry with exponential backoff for 429 errors
• Maximum of 3 retry attempts

Caching

Built-in caching with:

• 60-second cache duration by default
• Automatic cache invalidation
• Per-request cache key generation

Error Handling

Comprehensive error handling with:

• Network error retry logic
• Graceful degradation on API failures
• Detailed error logging

Development

Build

bun run build

Development Mode

bun run dev

Clean Build Artifacts

bun run clean

Requirements

• ElizaOS Core ^1.0.0
• Helius API Key (get one at helius.dev)

License

MIT

Contributing

Contributions are welcome! Please ensure all tests pass and code follows the project style guidelines.

Support

For issues and questions:

• GitHub Issues: elizaos-plugins/plugin-helius
• Helius Documentation: docs.helius.dev