DexPaprika SDK

The official JavaScript client library for the DexPaprika API, providing easy access to decentralized exchange data across multiple blockchain networks.

Developed and maintained by Coinpaprika.

Installation

npm install dexpaprika-sdk

Important: migration notices

Breaking changes in v1.6.0: The API removed the per-network list/filter REST endpoints (now HTTP 410). pools.listByNetwork(), pools.filter(), tokens.getTop(), and tokens.filter() now call the unified search endpoints and return the cursor-paginated shape { results, has_next_page, next_cursor }. Method signatures are unchanged; legacy sort/filter values are mapped internally. See the CHANGELOG for field-level details.

// Cursor pagination (page is ignored on search endpoints):
const first = await client.pools.listByNetwork('ethereum', { limit: 10 });
console.log(first.results, first.has_next_page);
if (first.next_cursor) {
  const next = await client.pools.listByNetwork('ethereum', {
    limit: 10,
    cursor: first.next_cursor
  });
}

Breaking changes in v1.4.0: The global pools endpoint has been deprecated. All pool queries now require a network specification.

// ❌ OLD (deprecated) - will throw DeprecatedEndpointError:
const pools = await client.pools.list();

// ✅ NEW (required) - specify network:
const ethereumPools = await client.pools.listByNetwork('ethereum');
const solanaPools = await client.pools.listByNetwork('solana');

Usage

import { DexPaprikaClient } from 'dexpaprika-sdk';

// Create client
const client = new DexPaprikaClient();

// Get supported networks
const networks = await client.networks.list();
console.log(networks);

// Get top pools on Ethereum (cursor-paginated search endpoint)
const pools = await client.pools.listByNetwork('ethereum', {
  limit: 10
});
console.log(pools.results);            // pool rows
console.log(pools.has_next_page, pools.next_cursor); // pagination

// Search for tokens
const results = await client.search.search('bitcoin');
console.log(`Found ${results.tokens.length} tokens`);

Options Pattern API

The DexPaprika SDK uses an options pattern for API method parameters, which provides better flexibility, readability, and extensibility:

import { DexPaprikaClient } from 'dexpaprika-sdk';

const client = new DexPaprikaClient();

// Get top pools with sorting and cursor pagination
const pools = await client.pools.listByNetwork('ethereum', {
  limit: 10,
  sort: 'desc',
  orderBy: 'volume_usd_24h' // legacy 'volume_usd' is also accepted and mapped
});

// Get pool details with options
const poolDetails = await client.pools.getDetails(
  'ethereum', 
  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  { inversed: false }
);

// Get pools that contain a token (network-scoped /pools/search filter,
// cursor-paginated: rows under `results`, page via `cursor`)
const tokenPools = await client.tokens.getPools(
  'ethereum',
  '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
  {
    limit: 5,
    sort: 'desc',
    orderBy: 'volume_usd_24h' // legacy 'volume_usd' is also accepted and mapped
  }
);

// Get OHLCV data with options
const ohlcv = await client.pools.getOHLCV(
  'ethereum',
  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  {
    start: '2023-01-01',
    end: '2023-01-07',
    limit: 7,
    interval: '24h',
    inversed: false
  }
);

Advanced Configuration

The SDK supports automatic retry with exponential backoff and response caching, both enabled by default:

import { DexPaprikaClient } from 'dexpaprika-sdk';

// Custom configuration
const client = new DexPaprikaClient(
  'https://api.dexpaprika.com', // Default API URL
  {}, // Axios options (optional)
  {
    // Retry configuration (optional)
    retry: {
      maxRetries: 4,              // Maximum retry attempts
      delaySequenceMs: [100, 500, 1000, 5000], // Specific delay for each retry (in ms)
      retryableStatuses: [408, 429, 500, 502, 503, 504] // HTTP statuses to retry
    },
    // Cache configuration (optional)
    cache: {
      ttl: 5 * 60 * 1000,         // Time-to-live: 5 minutes
      maxSize: 1000,              // Maximum cache entries
      enabled: true               // Enable/disable caching
    }
  }
);

// Working with cache
const firstCall = await client.networks.list(); // Hits API
const secondCall = await client.networks.list(); // Uses cache

// Manual cache operations
client.clearCache();             // Clear all cached data
console.log(client.cacheSize);   // Get current cache size
client.setCacheEnabled(false);   // Temporarily disable caching

API Reference

For detailed API documentation, visit docs.dexpaprika.com

Networks & DEXes

// Networks
const networks = await client.networks.list();

// DEXes on a network
const dexes = await client.dexes.listByNetwork('ethereum', {
  limit: 10
});

Pools & Transactions

// Top pools on Ethereum (cursor-paginated; read results / has_next_page / next_cursor)
const topPools = await client.pools.listByNetwork('ethereum', {
  limit: 10,
  sort: 'desc',
  orderBy: 'volume_usd_24h'
});
console.log(`Got ${topPools.results.length} pools`);

// Fetch the next page with the returned cursor
if (topPools.has_next_page && topPools.next_cursor) {
  const nextPage = await client.pools.listByNetwork('ethereum', {
    limit: 10,
    cursor: topPools.next_cursor
  });
  console.log(`Next page: ${nextPage.results.length} pools`);
}

// Top pools on different networks
const solanaPools = await client.pools.listByNetwork('solana', { limit: 5 });
const fantomPools = await client.pools.listByNetwork('fantom', { limit: 5 });

// Pool details
const poolDetails = await client.pools.getDetails(
  'ethereum',
  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640'
);

// Transactions
const txs = await client.pools.getTransactions(
  'ethereum',
  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  { limit: 20 }
);

OHLCV Data

For price charts:

// Price history (daily candles for a week)
const startDate = new Date();
startDate.setDate(startDate.getDate() - 7);

const ohlcv = await client.pools.getOHLCV(
  'ethereum', 
  '0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640',
  {
    start: startDate.toISOString(),
    interval: '24h',
    limit: 7
  }
);

Tokens

// Token details (WETH)
const token = await client.tokens.getDetails(
  'ethereum', 
  '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'
);

// Find WETH pools (network-scoped /pools/search with token_address).
// Rows come back under `results`; page with `cursor` from `next_cursor`.
const pools = await client.tokens.getPools(
  'ethereum', 
  '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
  {
    limit: 10,
    sort: 'desc',
    orderBy: 'volume_usd_24h'
  }
);
for (const p of pools.results) {
  console.log(p.id, p.volume_usd_24h);
}

// The removed /tokens/{address}/pools endpoint supported pair queries
// (`pairWith`); /pools/search has no equivalent, so `pairWith` is deprecated
// and ignored. To match a pair, filter client-side:
const usdc = '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48';
const wethUsdcPools = pools.results.filter(
  p => (p.tokens ?? []).some(t => t.id === usdc)
);

Pool Filtering

Backed by the unified /networks/{network}/pools/search endpoint. Results come back as { results, has_next_page, next_cursor }; legacy sortBy values such as volume_24h are accepted and mapped to canonical fields.

// Find high-volume pools on Ethereum
const filtered = await client.pools.filter('ethereum', {
  volume24hMin: 100000,
  txns24hMin: 50,
  sortBy: 'volume_usd_24h', // legacy 'volume_24h' also accepted
  sortDir: 'desc',
  limit: 10
});
console.log(`Found ${filtered.results.length} pools matching criteria`);
// Next page: pass filtered.next_cursor as `cursor`

Top Tokens & Token Filtering

Both are backed by /networks/{network}/tokens/search and return { results, has_next_page, next_cursor }. Token rows are flat: address, volume_usd_24h, fdv_usd, txns_24h, price_change_percentage_24h, etc.

// Get top tokens by 24h volume
const topTokens = await client.tokens.getTop('ethereum', {
  orderBy: 'volume_usd_24h', // legacy 'volume_24h' also accepted
  limit: 10
});
console.log(topTokens.results.map(t => t.address));

// Filter tokens by criteria
const filtered = await client.tokens.filter('ethereum', {
  volume24hMin: 100000,
  fdvMin: 1000000,
  limit: 10
});

Batch Token Prices

// Get prices for multiple tokens in one request (max 10)
const prices = await client.tokens.getMultiPrices('ethereum', [
  '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
  '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
]);
prices.forEach(p => console.log(`${p.id}: $${p.price_usd}`));

Search & Stats

// Search
const results = await client.search.search('bitcoin');

// Stats
const stats = await client.utils.getStats();

TypeScript Types

The SDK includes TypeScript types for easier development. See the documentation for response type details.

Error Handling

The SDK includes specific error classes for better error handling:

import { 
  DexPaprikaClient, 
  DeprecatedEndpointError, 
  NetworkNotFoundError,
  PoolNotFoundError,
  ApiError 
} from 'dexpaprika-sdk';

const client = new DexPaprikaClient();

try {
  // This will throw DeprecatedEndpointError
  const pools = await client.pools.list();
} catch (error) {
  if (error instanceof DeprecatedEndpointError) {
    console.log('Migration required:', error.message);
    // Use network-specific method instead
    const pools = await client.pools.listByNetwork('ethereum');
  } else if (error instanceof NetworkNotFoundError) {
    console.log('Invalid network:', error.message);
  } else if (error instanceof PoolNotFoundError) {
    console.log('Pool not found:', error.message);
  } else {
    console.error('Other error:', error.message);
  }
}

Using the error helper:

import { parseError } from 'dexpaprika-sdk/dist/utils/helpers';

try {
  const pools = await client.pools.listByNetwork('ethereum');
  // Process results
} catch (err) {
  console.error(parseError(err));
}

Utilities

Helper functions:

import { formatVolume, formatPair } from 'dexpaprika-sdk/dist/utils/helpers';

// Format volume like $1.23M
console.log(formatVolume(1234567));  // $1.23M

// Format token pair
console.log(formatPair('ETH', 'USDC')); // ETH/USDC

Retry & Caching

You can also use the retry and caching utilities directly:

import { withRetry, Cache } from 'dexpaprika-sdk';

// Retry a function with custom settings
const result = await withRetry(
  async () => {
    // Your async operation here
    return await someAsyncFunction();
  },
  { maxRetries: 4, delaySequenceMs: [100, 200, 300, 400] }
);

// Create a standalone cache
const cache = new Cache({ ttl: 60 * 1000 }); // 1 minute TTL
cache.set('key', value);
const cachedValue = cache.get('key');

Resources

• Official Documentation - Comprehensive API reference
• DexPaprika Website - Main product website
• CoinPaprika - Related cryptocurrency data platform
• Discord Community - Get support and connect with other developers

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a Pull Request.

Development and Testing

The SDK includes a comprehensive test suite to verify functionality:

# Run basic functionality tests
npm test

# Run real-world API tests
npx ts-node tests/test-real-world.ts

# Run all tests sequentially
npm run test:all

All test files are located in the tests/ directory:

• test-basic.ts - Basic API functionality tests
• test-real-world.ts - Tests with actual API calls and simulated failures

Support

For issues, questions, or feedback, please:

• Open an issue on our GitHub repository
• Reach out to the DexPaprika team at [email protected]

Disclaimer

This SDK is created and maintained by Coinpaprika. While we strive to provide accurate and up-to-date data, we make no guarantees regarding the accuracy, reliability, or completeness of the data provided through the DexPaprika API.