@elizaos/plugin-arkham

A comprehensive Arkham Intelligence integration plugin for ElizaOS agents. This plugin provides advanced transaction and swap analysis for Ethereum and EVM-compatible chains, enabling agents to analyze wallet activity, detect trading patterns, and track DEX swaps.

Features

• 🔍 Transaction Analysis: Fetch and parse complete transaction history for any wallet address
• 💱 Swap Detection: Automatically detect and extract token swap information from transactions
• 📊 Trading Statistics: Comprehensive analytics including:
  • Total transaction and swap counts
  • Trading volume in USD
  • Unique tokens traded
  • Top traded tokens by volume and frequency
  • Recent activity metrics (24h and 7d)
• 🔗 Multi-Chain Support: Works with Ethereum, Polygon, Arbitrum, Optimism, and other EVM chains
• 🏛️ DEX Protocol Detection: Identifies swaps from major protocols:
  • Uniswap V2 & V3
  • SushiSwap
  • 1inch
  • Curve
  • Balancer
• ⚡ Rate Limiting: Built-in rate limiting and retry logic for API reliability
• 💾 Caching: Intelligent 5-minute caching to reduce API calls and improve performance

Installation

bun add @elizaos/plugin-arkham

Configuration

Environment Variables

Add your Arkham Intelligence API key and optional settings to your .env file:

# Required
ARKHAM_API_KEY=your_arkham_api_key_here

# Optional
ARKHAM_CHAIN=ethereum          # Default: ethereum (supports polygon, arbitrum, optimism, etc.)
ARKHAM_TX_LIMIT=100            # Default: 100 (max transactions to fetch)
WALLET_ADDRESS=0x...           # Fallback wallet address if not in context
ETH_ADDRESS=0x...              # Alternative fallback for Ethereum addresses

Get API Key

Obtain your Arkham Intelligence API key from: Arkham API Access Documentation

Plugin Registration

Register the plugin in your agent configuration:

import { arkhamPlugin } from '@elizaos/plugin-arkham';

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

Usage

As a Provider

The Arkham provider automatically activates when an Ethereum wallet address is detected in conversation. It will:

1. Extract Ethereum addresses (0x...) from message text
2. Fall back to state.walletAddress, WALLET_ADDRESS, or ETH_ADDRESS settings
3. Fetch comprehensive transaction and swap analysis
4. Format and inject the data into the agent's context

Example Queries

Users can interact with the provider through natural language:

• "Analyze wallet 0x1234567890abcdef..."
• "What are my recent swaps?"
• "Show me trading activity for this address"
• "What tokens has 0xabcd... traded?"
• "Get transaction history for my wallet"

Direct API Usage

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

import { ArkhamAPI } from '@elizaos/plugin-arkham';

const arkhamAPI = new ArkhamAPI(runtime.getSetting('ARKHAM_API_KEY'));

// Get transactions
const transactions = await arkhamAPI.getTransactions('0x...', {
  limit: 100,
  chain: 'ethereum',
});

// Get swaps only
const swaps = await arkhamAPI.getSwaps('0x...', {
  limit: 50,
  chain: 'ethereum',
});

// Comprehensive wallet analysis
const analysis = await arkhamAPI.analyzeWallet('0x...', {
  limit: 100,
  chain: 'ethereum',
});

// Cache management
arkhamAPI.clearCache();
const stats = arkhamAPI.getCacheStats();

API Reference

ArkhamAPI Class

Constructor

new ArkhamAPI(apiKey: string)

Methods

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

  • Fetch complete transaction history
  • Options: { limit?, offset?, chain? }

• getSwaps(address: string, options?: SwapOptions): Promise<ISwap[]>

  • Get detected swaps from transactions
  • Options: { limit?, chain? }

• analyzeWallet(address: string, options?: AnalysisOptions): Promise<IWalletAnalysis>

  • Comprehensive wallet analysis with statistics
  • Options: { limit?, chain? }

• clearCache(): void

  • Clear the internal cache

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

  • Get cache statistics

Provider Response Structure

{
  data: {
    analysis: {
      address: string;
      totalTransactions: number;
      totalSwaps: number;
      totalVolumeUsd: number;
      uniqueTokens: string[];
      topTokens: Array<{
        symbol: string;
        address: string;
        swapCount: number;
        volumeUsd: number;
      }>;
      recentActivity: {
        lastTransactionTime: number;
        last24hSwaps: number;
        last7dSwaps: number;
      };
    },
    recentSwaps: Array<{
      transactionHash: string;
      timestamp: number;
      tokenIn: { symbol, address, amount, amountUsd };
      tokenOut: { symbol, address, amount, amountUsd };
      protocol: string;
      gasCost: number;
      gasCostUsd: number;
    }>
  },
  values: {
    walletAddress: string;
    chain: string;
    totalTransactions: number;
    totalSwaps: number;
    totalVolumeUsd: number;
    uniqueTokenCount: number;
  },
  text: string  // Formatted summary for display
}

Supported Chains

• Ethereum (mainnet)
• Polygon
• Arbitrum
• Optimism
• And other EVM-compatible chains supported by Arkham Intelligence

Supported DEX Protocols

The plugin automatically detects swaps from:

• Uniswap V2 & V3
• SushiSwap
• 1inch Aggregator
• Curve Finance
• Balancer
• And more via method signature detection

Features in Detail

Swap Detection

The plugin uses sophisticated logic to detect swaps:

• Analyzes token transfer patterns
• Identifies DEX contract interactions
• Matches method signatures for swap functions
• Extracts tokenIn and tokenOut details with USD values

Rate Limiting

• 250ms delay between API calls
• Automatic retry with exponential backoff
• Maximum 3 retry attempts for failed requests
• Handles 429 rate limit responses gracefully

Caching

• 5-minute cache duration for transaction data
• Per-request cache key generation
• Reduces redundant API calls
• Cache statistics and manual clearing available

Development

Build

bun run build

Development Mode

bun run dev

Clean Build Artifacts

bun run clean

Testing

To test the plugin:

# Set your API key
export ARKHAM_API_KEY=your_key

# Set a test wallet
export WALLET_ADDRESS=0x1234...

# Run your agent
elizaos start

Error Handling

The plugin handles errors gracefully:

• Returns null if API key is not configured
• Retries failed requests automatically
• Logs detailed error messages for debugging
• Never crashes the agent on API failures

Performance

• Efficient caching reduces API load
• Parallel-safe for multiple concurrent requests
• Optimized transaction parsing
• Minimal memory footprint

Requirements

• ElizaOS Core ^1.0.0
• Arkham Intelligence API Key (free tier available)

License

MIT

Contributing

Contributions are welcome! Please ensure:

• All tests pass
• Code follows project style guidelines
• Documentation is updated
• Changes are backward compatible

Support

For issues and questions:

• GitHub Issues: elizaos-plugins/plugin-arkham
• Arkham Intelligence Docs: docs.arkhamintelligence.com

Acknowledgments

Built for the ElizaOS ecosystem. Powered by Arkham Intelligence API.