@solana-api-toolkit/token-service NPM

@solana-api-toolkit/token-service

A powerful and flexible token data service for Solana with multi-provider support, automatic fallbacks, and caching.

Note: This is not fully tested and is still under development. Use at your own risk. Please open a github issue or PR if you run into issues or have feature requests!

Features

Multi-Provider Support: Seamlessly integrates with multiple token data providers including Helius, Jupiter, Birdeye, Solscan, CoinMarketCap, CoinGecko, and Pyth
Automatic Fallbacks: Gracefully falls back to alternative providers if a primary provider fails
Intelligent Caching: Reduces api calls and improves performance with configurable TTL caching
Comprehensive Token Data: Easily access token prices, metadata, balances, and wallet portfolios
Type-Safe: Written in TypeScript with full type definitions
Error Handling: Robust error handling with detailed error messages
Circuit Breaker Pattern: Prevents cascading failures with built-in circuit breaker
Coin mappings: Included maps of CoinGecko and CoinMarketCap coins to Solana addresses, and scripts to update them
Bundling rpc with api calls: Bundles direct rpc calls with api calls as needed (e.g. a single getWalletPortfolio() call from the Helius provider uses both connection.getBalance() for native SOL and the Helius SDK's getAssetsByOwner() for SPL token balances)

Installation

npm install @solana-api-toolkit/token-service

Usage

Basic Usage

import { TokenService } from '@solana-api-toolkit/token-service';

// Initialize with your API keys
const tokenService = new TokenService({
  jupiter: { apiKey: 'YOUR_JUPITER_API_KEY' },
  birdeye: { apiKey: 'YOUR_BIRDEYE_API_KEY' },
  // Add other providers as needed
});

// Get token price
const price = await tokenService.getTokenPrice('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'); // USDC
console.log(`USDC price: $${price.priceUsd}`);

// Get token metadata
const metadata = await tokenService.getTokenMetadata('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');
console.log(`Token: ${metadata.name} (${metadata.symbol})`);

// Get wallet portfolio
const portfolio = await tokenService.getWalletPortfolio('YOUR_WALLET_ADDRESS');
console.log(`Total portfolio value: $${portfolio.totalValueUsd}`);

Advanced Configuration

import { TokenService } from '@solana-api-toolkit/token-service';

const tokenService = new TokenService({
  // Configure multiple providers with different priorities
  heliusDas: { 
    apiKey: 'YOUR_HELIUS_API_KEY',
    priority: 1, // Highest priority
    maxRetries: 3,
    timeout: 5000
  },
  jupiter: { 
    apiKey: 'YOUR_JUPITER_API_KEY',
    priority: 2,
    maxRetries: 2
  },
  birdeye: { 
    apiKey: 'YOUR_BIRDEYE_API_KEY',
    priority: 3
  },
  // Configure cache TTL
  cacheTtl: 10 * 60 * 1000 // 10 minutes
});

// Get comprehensive token data (metadata + price)
const tokenData = await tokenService.getTokenData('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v');
console.log(tokenData);

API Reference

`TokenService`

The main class for interacting with token data.

Constructor

constructor(config: TokenServiceConfig = {})

Configuration Options

The TokenServiceConfig interface supports the following providers:

heliusDas: Helius DAS provider configuration
jupiter: Jupiter provider configuration
birdeye: Birdeye provider configuration
solscan: Solscan provider configuration
coinmarketcap: CoinMarketCap provider configuration
coingecko: CoinGecko provider configuration
pyth: Pyth provider configuration (not yet implemented)

Each provider configuration accepts:

apiKey: API key for the provider (required)
baseUrl: Custom base URL (optional)
timeout: Request timeout in milliseconds (optional)
maxRetries: Maximum number of retry attempts (optional)
priority: Provider priority (lower is higher priority) (optional)
cacheTtl: Cache TTL in milliseconds (optional)

Methods

getTokenPrice(mint: string): Promise<TokenPrice>
Get token price with automatic fallback between providers.
getTokenMetadata(mint: string): Promise<TokenInfo>
Get token metadata with automatic fallback between providers.
getTokenBalances(address: string): Promise<TokenBalance[]>
Get token balances for a wallet with automatic fallback between providers.
getWalletPortfolio(address: string): Promise<WalletPortfolio>
Get wallet portfolio with automatic fallback between providers. Enriches with price data when available.
getTokenData(mint: string): Promise<TokenInfo>
Get comprehensive token data combining metadata and price.

Why Use This Package?

Reliability: Never worry about API downtime with automatic provider fallbacks
Simplicity: One unified API for multiple token data sources
Performance: Built-in caching reduces API calls and improves response times
Flexibility: Configure multiple providers to suit your needs and budget
Comprehensive: Get all the token data you need in one place