jupiter-api-client

A comprehensive TypeScript wrapper for the Jupiter API with full type support and all endpoints.

Features

• =� Complete API Coverage: All Jupiter API endpoints including Token Search, Price, Categories, and more
• =� Full TypeScript Support: Comprehensive type definitions exported with the package
• =�� Modern Tooling: Built with Bun, ESLint, and Prettier configured with strict rules
• =� Type Safe: Strict TypeScript configuration with no any types allowed
• � Axios-based: Reliable HTTP client with proper error handling
• <� Zero Dependencies: Only axios as a runtime dependency

Installation

npm install jupiter-api-client
# or
yarn add jupiter-api-client
# or
bun add jupiter-api-client

Quick Start

import { JupiterAPIClient } from 'jupiter-api-client';

const client = new JupiterAPIClient();

// Search for tokens
const tokens = await client.tokens.search({ query: 'SOL' });

// Get token prices
const price = await client.price.getOne('So11111111111111111111111111111111111111112');
console.log(`SOL Price: $${price?.usdPrice}`);

API Reference

Client Initialization

import { JupiterAPIClient } from 'jupiter-api-client';

// Using default base URL
const client = new JupiterAPIClient();

// Using custom base URL
const client = new JupiterAPIClient({
  baseUrl: 'https://custom-api.jup.ag'
});

Token Endpoints

Search Tokens

Search for tokens by symbol, name, or mint address.

// Search by symbol or name
const tokens = await client.tokens.search({ query: 'SOL' });

// Search by mint address
const tokens = await client.tokens.search({ 
  query: 'So11111111111111111111111111111111111111112' 
});

// Search for multiple mints (comma-separated, up to 100)
const tokens = await client.tokens.search({ 
  query: 'So11111111111111111111111111111111111111112,EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' 
});

Get Tokens by Tag

Get all tokens belonging to a specific tag.

// Get verified tokens
const verifiedTokens = await client.tokens.getByTag({ query: 'verified' });

// Get LST (Liquid Staking Tokens)
const lstTokens = await client.tokens.getByTag({ query: 'lst' });

Get Tokens by Category

Get top tokens in different trading categories with time intervals.

// Get top traded tokens in the last hour
const topTraded = await client.tokens.getByCategory({
  category: 'toptraded',
  interval: '1h',
  limit: 10 // optional, default 50, max 100
});

// Get top trending tokens in the last 24 hours
const topTrending = await client.tokens.getByCategory({
  category: 'toptrending',
  interval: '24h',
  limit: 5
});

// Get top organic score tokens in the last 5 minutes
const topOrganic = await client.tokens.getByCategory({
  category: 'toporganicscore',
  interval: '5m'
});

Available categories:

• toporganicscore - Tokens with highest organic trading score
• toptraded - Most traded tokens by volume
• toptrending - Trending tokens

Available intervals:

• 5m - 5 minutes
• 1h - 1 hour
• 6h - 6 hours
• 24h - 24 hours

Get Recent Tokens

Get tokens that recently had their first pool created.

// Returns ~30 most recent tokens
const recentTokens = await client.tokens.getRecent();

Price Endpoints

Get Single Token Price

const price = await client.price.getOne('So11111111111111111111111111111111111111112');
if (price) {
  console.log(`Price: $${price.usdPrice}`);
  console.log(`24h Change: ${price.priceChange24h}%`);
  console.log(`Decimals: ${price.decimals}`);
}

Get Multiple Token Prices

const mints = [
  'So11111111111111111111111111111111111111112', // SOL
  'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB'  // USDT
];

const prices = await client.price.getMany(mints);

// Access individual prices
Object.entries(prices).forEach(([mint, price]) => {
  console.log(`${mint}: $${price.usdPrice}`);
});

Alternative Price Method

// Using the general get method with single mint
const prices = await client.price.get({ 
  ids: 'So11111111111111111111111111111111111111112' 
});

// Using the general get method with multiple mints
const prices = await client.price.get({ 
  ids: ['mint1', 'mint2', 'mint3'] 
});

Type Exports

All types are exported and available for use in your TypeScript projects:

import type {
  Token,
  TokenPool,
  TokenAudit,
  TokenStats,
  TokenPrice,
  TokenTag,
  TokenCategory,
  TimeInterval,
  OrganicScoreLabel,
  TokenSearchResponse,
  TokenTagResponse,
  TokenCategoryResponse,
  TokenRecentResponse,
  PriceResponse,
  JupiterAPIError
} from 'jupiter-api-client';

Token Type Structure

interface Token {
  id: string;                        // Mint address
  name: string;
  symbol: string;
  icon?: string | null;
  decimals: number;
  circSupply?: number | null;
  totalSupply?: number | null;
  tokenProgram: string;
  usdPrice?: number | null;
  fdv?: number | null;              // Fully diluted valuation
  mcap?: number | null;              // Market cap
  liquidity?: number | null;
  holderCount?: number | null;
  isVerified?: boolean | null;
  tags?: string[] | null;
  organicScore?: number;
  organicScoreLabel?: 'high' | 'medium' | 'low';
  stats5m?: TokenStats | null;      // 5-minute stats
  stats1h?: TokenStats | null;      // 1-hour stats
  stats6h?: TokenStats | null;      // 6-hour stats
  stats24h?: TokenStats | null;     // 24-hour stats
  // ... and more fields
}

Price Type Structure

interface TokenPrice {
  usdPrice: number;
  blockId: number;
  decimals: number;
  priceChange24h?: number;
}

Error Handling

The library includes a custom error class for better error handling:

import { JupiterAPIError } from 'jupiter-api-client';

try {
  const tokens = await client.tokens.search({ query: 'INVALID' });
} catch (error) {
  if (error instanceof JupiterAPIError) {
    console.error('API Error:', error.message);
    console.error('Status:', error.status);
    console.error('Response:', error.response);
  }
}

Complete Example

import { JupiterAPIClient } from 'jupiter-api-client';
import type { Token, TokenPrice } from 'jupiter-api-client';

async function main() {
  const client = new JupiterAPIClient();

  try {
    // Search for SOL
    const searchResults = await client.tokens.search({ query: 'SOL' });
    const sol = searchResults[0];
    console.log(`Found ${sol?.name} (${sol?.symbol})`);

    // Get verified tokens
    const verifiedTokens = await client.tokens.getByTag({ query: 'verified' });
    console.log(`Total verified tokens: ${verifiedTokens.length}`);

    // Get top traded tokens
    const topTraded = await client.tokens.getByCategory({
      category: 'toptraded',
      interval: '24h',
      limit: 5
    });
    
    console.log('Top 5 traded tokens (24h):');
    topTraded.forEach((token: Token, i: number) => {
      console.log(`${i + 1}. ${token.symbol}: $${token.usdPrice?.toFixed(4)}`);
    });

    // Get prices for multiple tokens
    const prices = await client.price.getMany([
      'So11111111111111111111111111111111111111112',
      'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
    ]);
    
    Object.entries(prices).forEach(([mint, price]) => {
      console.log(`Price for ${mint}: $${price.usdPrice}`);
    });

  } catch (error) {
    console.error('Error:', error);
  }
}

main();

Development

Setup

# Install dependencies
bun install

# Run tests
bun run example.ts

# Type checking
bun run typecheck

# Linting
bun run lint

# Format code
bun run format

Building

bun run build

Requirements

• Node.js 16+ or Bun
• TypeScript 5.0+

License

MIT

Contributing

Contributions are welcome! Please ensure all code passes linting and type checks:

bun run typecheck && bun run lint

API Documentation

For detailed API documentation, visit the Jupiter API Documentation.

Support

For issues or questions, please open an issue on GitHub.