> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dexpaprika.com/llms.txt
> Use this file to discover all available pages before exploring further.
# DexPaprika DEX API Python SDK -- On‑chain Liquidity & Swap Data Client
> The official Python client library for the DexPaprika API, providing easy access to decentralized exchange data across multiple blockchain networks
See also: [REST intro](/api-reference/introduction),
[Networks](/api-reference/networks/get-a-list-of-available-blockchain-networks),
[Pools](/api-reference/pools/get-a-pool-on-a-network)
## Installation
```bash theme={null}
# Using pip
pip install dexpaprika-sdk
# Using poetry
poetry add dexpaprika-sdk
# From source
git clone https://github.com/coinpaprika/dexpaprika-sdk-python.git
cd dexpaprika-sdk-python
pip install -e .
```
## Prerequisites
* Python 3.8 or higher
* Connection to the internet to access the DexPaprika API
* No API key required
## Quick Example: Get Token Price
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
from dexpaprika_sdk.models import TokenDetails # Type hint example
# Create client and get WETH price on Ethereum
client = DexPaprikaClient()
token: TokenDetails = client.tokens.get_details("ethereum", "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2")
print(f"{token.name}: ${token.price_usd}")
# Output: Wrapped Ether: $3245.67
```
## API Methods Reference
Parameters marked with an asterisk (\*) are required.
### client.networks.list()
**Endpoint:** [GET `/networks`](/api-reference/networks/get-a-list-of-available-blockchain-networks)
Gets all supported blockchain networks including Ethereum, Solana, etc.
**Parameters:** None
**Returns:** Network IDs, names, and related information. [Response Structure](/api-reference/networks/get-a-list-of-available-blockchain-networks).
```python theme={null}
# Get all networks
networks = client.networks.list()
print(f"Found {len(networks)} networks")
```
### client.dexes.list\_by\_network(network\_id, page, limit)
**Endpoint:** [GET `/networks/{network}/dexes`](/api-reference/dexes/get-a-list-of-available-dexes-on-a-network)
Gets all DEXes on a specific network.
**Parameters:**
* `network_id`\* - ID of the network (e.g., 'ethereum', 'solana')
* `page` - Page number for pagination (starts at 0)
* `limit` - Number of results per page
**Returns:** DEX IDs, names, pool counts, and volume information. [Response Structure](/api-reference/dexes/get-a-list-of-available-dexes-on-a-network).
```python theme={null}
# Get all DEXes on Ethereum
dexes = client.dexes.list_by_network("ethereum")
print(f"Found {len(dexes.dexes)} DEXes on Ethereum")
```
### client.pools.list(page, limit, sort, order\_by)
**Endpoint:** [GET `/pools`](/api-reference/pools/get-top-x-pools)
Gets top pools across all networks with pagination.
**Parameters:**
* `page` - Page number for pagination (starts at 0)
* `limit` - Number of results per page
* `sort` - Sort direction ('asc' or 'desc')
* `order_by` - Field to sort by ('volume\_usd', 'liquidity\_usd', etc.)
**Returns:** Paginated list of pool objects with pricing data. [Response Structure](/api-reference/pools/get-top-x-pools).
```python theme={null}
# Get top 10 pools by volume
top_pools = client.pools.list(limit=10, order_by="volume_usd", sort="desc")
print(f"Top pool: {top_pools.pools[0].dex_name}")
```
***
### client.pools.list\_by\_network(network\_id, page, limit, sort, order\_by)
**Endpoint:** [GET `/networks/{network}/pools`](/api-reference/pools/get-top-x-pools-on-a-network)
Gets pools on a specific network with pagination and sorting options.
**Parameters:**
* `network_id`\* - ID of the network
* `page` - Page number for pagination (starts at 0)
* `limit` - Number of results per page
* `sort` - Sort direction ('asc' or 'desc')
* `order_by` - Field to sort by ('volume\_usd', 'liquidity\_usd', etc.)
**Returns:** Paginated list of pools for the given network. [Response Structure](/api-reference/pools/get-top-x-pools-on-a-network).
```python theme={null}
# Get top 5 pools on Ethereum by volume
pools = client.pools.list_by_network(
network_id="ethereum",
limit=5,
order_by="volume_usd",
sort="desc"
)
print(f"Found {len(pools.pools)} pools on Ethereum")
```
***
### client.pools.list\_by\_dex(network\_id, dex\_id, page, limit, sort, order\_by)
**Endpoint:** [GET `/networks/{network}/dexes/{dex}/pools`](/api-reference/pools/get-top-x-pools-on-a-networks-dex)
Gets pools on a specific DEX within a network with pagination.
**Parameters:**
* `network_id`\* - ID of the network
* `dex_id`\* - ID of the DEX
* `page` - Page number for pagination (starts at 0)
* `limit` - Number of results per page
* `sort` - Sort direction ('asc' or 'desc')
* `order_by` - Field to sort by ('volume\_usd', 'liquidity\_usd', etc.)
**Returns:** Paginated list of pools for the specified DEX. [Response Structure](/api-reference/pools/get-top-x-pools-on-a-networks-dex).
```python theme={null}
# Get top 10 Uniswap V2 pools on Ethereum
uniswap_pools = client.pools.list_by_dex(
network_id="ethereum",
dex_id="uniswap_v2",
limit=10,
order_by="volume_usd",
sort="desc"
)
print(f"Found {len(uniswap_pools.pools)} Uniswap V2 pools")
```
***
### client.pools.get\_details(network\_id, pool\_address, inversed)
**Endpoint:** [GET `/networks/{network}/pools/{pool_address}`](/api-reference/pools/get-a-pool-on-a-network)
Gets detailed information about a specific pool.
**Parameters:**
* `network_id`\* - ID of the network
* `pool_address`\* - On-chain address of the pool
* `inversed` - Whether to invert the price ratio (boolean)
**Returns:** Detailed pool information including tokens, volumes, liquidity, and more. [Response Structure](/api-reference/pools/get-a-pool-on-a-network).
```python theme={null}
from dexpaprika_sdk.models import PoolDetails # Type hint example
# Get details for a specific pool (WETH/USDC on Uniswap V2)
pool: PoolDetails = client.pools.get_details(
network_id="ethereum",
pool_address="0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc",
inversed=False
)
print(f"Pool: {pool.tokens[0].symbol}/{pool.tokens[1].symbol}")
```
***
### client.pools.get\_transactions(network\_id, pool\_address, page, limit)
**Endpoint:** [GET `/networks/{network}/pools/{pool_address}/transactions`](/api-reference/pools/get-transactions-of-a-pool-on-a-network-paging-can-be-used-up-to-100-pages)
Gets transaction history for a specific pool with pagination.
**Parameters:**
* `network_id`\* - ID of the network
* `pool_address`\* - On-chain address of the pool
* `page` - Page number for pagination
* `limit` - Number of transactions per page
**Returns:** List of transactions with details about tokens, amounts, and timestamps. [Response Structure](/api-reference/pools/get-transactions-of-a-pool-on-a-network-paging-can-be-used-up-to-100-pages).
```python theme={null}
# Get the latest 20 transactions for a pool
transactions = client.pools.get_transactions(
network_id="ethereum",
pool_address="0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc",
limit=20
)
from datetime import datetime
latest_tx_time = datetime.fromtimestamp(transactions.transactions[0].block_timestamp).strftime('%Y-%m-%d %H:%M:%S')
print(f"Latest transaction: {latest_tx_time}")
```
***
### client.pools.get\_ohlcv(network\_id, pool\_address, start, end, limit, interval, inversed)
**Endpoint:** [GET `/networks/{network}/pools/{pool_address}/ohlcv`](/api-reference/pools/get-ohlcv-data-for-a-pool-pair)
Gets OHLCV (Open, High, Low, Close, Volume) chart data for a pool.
**Parameters:**
* `network_id`\* - ID of the network
* `pool_address`\* - On-chain address of the pool
* `start`\* - Start time (ISO date string, YYYY-MM-DD, or Unix timestamp)
* `end` - End time (optional)
* `limit` - Number of data points to return
* `interval` - Time interval ('1m', '5m', '15m', '30m', '1h', '6h', '12h', '24h')
* `inversed` - Whether to invert the price ratio (boolean)
**Returns:** Array of OHLCV data points for the specified time range and interval. [Response Structure](/api-reference/pools/get-ohlcv-data-for-a-pool-pair).
```python theme={null}
from datetime import datetime, timedelta
# Get OHLCV data for the past 7 days with 1-hour intervals
end_date = datetime.now()
start_date = end_date - timedelta(days=7)
ohlcv = client.pools.get_ohlcv(
network_id="ethereum",
pool_address="0xb4e16d0168e52d35cacd2c6185b44281ec28c9dc",
start=start_date.strftime("%Y-%m-%d"),
end=end_date.strftime("%Y-%m-%d"),
interval="1h",
limit=168 # 24 * 7 hours
)
print(f"Received {len(ohlcv)} OHLCV data points")
```
### client.tokens.get\_details(network\_id, token\_address)
**Endpoint:** [GET `/networks/{network}/tokens/{token_address}`](/api-reference/tokens/get-a-tokens-latest-data-on-a-network)
Gets comprehensive token information.
**Parameters:**
* `network_id`\* - ID of the network
* `token_address`\* - Token contract address
**Returns:** Token details including price, market cap, volume, and metadata. [Response Structure](/api-reference/tokens/get-a-tokens-latest-data-on-a-network).
```python theme={null}
# Get WETH token details
weth = client.tokens.get_details(
network_id="ethereum",
token_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
)
print(f"{weth.name} price: ${weth.price_usd}")
```
***
### client.tokens.get\_pools(network\_id, token\_address, page, limit, sort, order\_by, address)
**Endpoint:** [GET `/networks/{network}/tokens/{token_address}/pools`](/api-reference/tokens/get-top-x-pools-for-a-token)
Gets pools containing a specific token.
**Parameters:**
* `network_id`\* - ID of the network
* `token_address`\* - Token contract address
* `page` - Page number for pagination (starts at 0)
* `limit` - Number of results per page
* `sort` - Sort direction ('asc' or 'desc')
* `order_by` - Field to sort by ('volume\_usd', 'price\_usd', etc.)
* `address` - Optional second token address to filter for pairs with both tokens
**Returns:** List of pools where the queried token is found. [Response Structure](/api-reference/tokens/get-top-x-pools-for-a-token).
```python theme={null}
# Get WETH/USDC pools
pools = client.tokens.get_pools(
network_id="ethereum",
token_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", # WETH
limit=5,
order_by="volume_usd",
sort="desc",
address="0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" # USDC
)
for pool in pools.pools:
print(f"{pool.dex_name}: ${pool.volume_usd:,.2f} 24h volume")
```
### client.search.search(query)
**Endpoint:** [GET `/search`](/api-reference/search/search-for-tokens-pools-and-dexes)
Searches across tokens, pools, and DEXes using a query string.
**Parameters:**
* `query`\* - Search query string
**Returns:** Matching entities from all categories (tokens, pools, DEXes). [Response Structure](/api-reference/search/search-for-tokens-pools-and-dexes).
```python theme={null}
# Search for "ethereum" across all entities
results = client.search.search("ethereum")
print(f"Found {len(results.tokens)} tokens")
print(f"Found {len(results.pools)} pools")
print(f"Found {len(results.dexes)} dexes")
```
### client.utils.get\_stats()
**Endpoint:** [GET `/stats`](/api-reference/utils/retrieve-high-level-asset-statistics)
Gets platform-wide statistics.
**Parameters:** None
**Returns:** Counts of chains, DEXes, pools, and tokens indexed. [Response Structure](/api-reference/utils/retrieve-high-level-asset-statistics).
```python theme={null}
# Get platform statistics
stats = client.utils.get_stats()
print(f"Total chains: {stats.chains}")
print(f"Total DEXes: {stats.dexes}")
print(f"Total pools: {stats.pools}")
print(f"Total tokens: {stats.tokens}")
```
## Complete Example
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
def main():
# Initialize client
client = DexPaprikaClient()
# Get Ethereum network details
networks = client.networks.list()
ethereum = next((n for n in networks if n.id == "ethereum"), None)
print(f"Found {ethereum.display_name} with {ethereum.dexes_count} DEXes")
# Get WETH token details
weth = client.tokens.get_details(
network_id="ethereum",
token_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
)
print(f"{weth.name} price: ${weth.price_usd}")
# Find WETH/USDC pools
pools = client.tokens.get_pools(
network_id="ethereum",
token_address="0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", # WETH
limit=5,
order_by="volume_usd",
sort="desc",
address="0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" # USDC
)
# Show top pools
print('Top WETH/USDC pools:')
for pool in pools.pools:
print(f"{pool.dex_name}: ${pool.volume_usd:,.2f} 24h volume")
if __name__ == "__main__":
main()
```
## Advanced Features
### Error Handling
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
import requests
# Basic error handling
try:
client = DexPaprikaClient()
token = client.tokens.get_details("ethereum", "0xinvalidaddress")
except Exception as e:
if "404" in str(e):
print("Token not found")
elif "429" in str(e):
print("Rate limit exceeded")
else:
print(f"An error occurred: {e}")
# The SDK automatically retries on these status codes:
# 408 (Request Timeout), 429 (Too Many Requests),
# 500, 502, 503, 504 (Server Errors)
# Custom retry configuration
client = DexPaprikaClient(
max_retries=4, # Number of retry attempts (default: 4)
backoff_times=[0.1, 0.5, 1.0, 5.0] # Backoff times in seconds
)
# All API requests will now use these retry settings
try:
networks = client.networks.list()
except requests.exceptions.RetryError as e:
print(f"Failed after multiple retries: {e}")
```
### Caching System
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
import time
# The SDK includes built-in caching by default
# Demonstration of cache behavior
# Create a regular client with default cache (5 minutes TTL)
client = DexPaprikaClient()
# First call - hits the API
start_time = time.time()
networks = client.networks.list()
first_call_time = time.time() - start_time
print(f"First call (API): {len(networks)} networks, took {first_call_time:.4f}s")
# Second call - served from cache (much faster)
start_time = time.time()
networks = client.networks.list()
second_call_time = time.time() - start_time
print(f"Second call (cached): {len(networks)} networks, took {second_call_time:.4f}s")
print(f"Cache speedup: {first_call_time / second_call_time:.1f}x")
# You can skip the cache when you need fresh data
fresh_networks = client.networks._get("/networks", skip_cache=True)
# Clear the entire cache
client.clear_cache()
# Clear cache only for specific endpoints
client.clear_cache(endpoint_prefix="/networks")
# Different types of data have different cache durations:
# - Network data: 24 hours
# - Pool data: 5 minutes
# - Token data: 10 minutes
# - Statistics: 15 minutes
# - Other data: 5 minutes (default)
```
### Pagination Helper
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
import time
def fetch_all_pools(network_id):
client = DexPaprikaClient()
all_pools = []
page = 0
limit = 50
has_more = True
while has_more:
response = client.pools.list_by_network(
network_id=network_id,
page=page,
limit=limit,
sort="desc",
order_by="volume_usd"
)
all_pools.extend(response.pools)
# Check if there are more pages
has_more = len(response.pools) == limit
page += 1
# Adding a small delay to avoid hitting rate limits
time.sleep(0.1)
print(f"Fetched a total of {len(all_pools)} pools on {network_id}")
return all_pools
# Usage example
ethereum_pools = fetch_all_pools("ethereum")
```
### Parameter Validation
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
# The SDK automatically validates parameters before making API requests
client = DexPaprikaClient()
# Invalid parameter examples will raise helpful error messages
try:
# Invalid network ID
client.pools.list_by_network(network_id="", limit=5)
except ValueError as e:
print(e) # "network_id is required"
try:
# Invalid sort parameter
client.pools.list(sort="invalid_sort")
except ValueError as e:
print(e) # "sort must be one of: asc, desc"
try:
# Invalid limit parameter
client.pools.list(limit=500)
except ValueError as e:
print(e) # "limit must be at most 100"
```
### Working with Models
```python theme={null}
from dexpaprika_sdk import DexPaprikaClient
from dexpaprika_sdk.models import PoolDetails # Type hint example
client = DexPaprikaClient()
# Get pool details
pool: PoolDetails = client.pools.get_details(
network_id="ethereum",
pool_address="0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640" # USDC/WETH Uniswap v3 pool
)
# Access pool properties with type checking and auto-completion
print(f"Pool: {pool.tokens[0].symbol}/{pool.tokens[1].symbol}")
print(f"Volume (24h): ${pool.day.volume_usd:.2f}")
print(f"Transactions (24h): {pool.day.txns}")
print(f"Price: ${pool.last_price_usd:.4f}")
# Time interval data is available for multiple timeframes
print(f"1h price change: {pool.hour1.last_price_usd_change:.2f}%")
print(f"24h price change: {pool.day.last_price_usd_change:.2f}%")
# All API responses are converted to typed Pydantic models
# This provides automatic validation, serialization/deserialization,
# and IDE auto-completion support through Python type hints
```
## Resources
* [GitHub Repository](https://github.com/coinpaprika/dexpaprika-sdk-python)
* [DexPaprika Website](https://dexpaprika.com)
* [API Reference](/api-reference/introduction)
* [Discord Community](https://discord.gg/DhJge5TUGM)
## API Status
The DexPaprika API provides consistent data with stable endpoints. No API key is currently required to access the service. We aim to maintain backward compatibility and provide notice of any significant changes.
### FAQs
No. The API is public; no keys or registration required.
Use Coverage Checker or list Networks and query Tokens/Pools to discover addresses.
Use pools/transactions endpoints with `pool_address`, `network`, and time/paging params as documented.
Handle retries for transient HTTP errors and keep calls reasonable for public endpoints.