Skip to main content

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.

​
The silent-merge problem

If you query DexPaprika for “USDC” across several chains and aggregate by symbol, you will silently merge bridge variants into native USDC. The numbers you compute will be wrong. The API will not warn you. Your dashboard will say “USDC volume: $X billion” and that number will be a quiet lie. This page explains why, and what to do instead.

​
Why symbol is not a safe key

A token’s symbol is metadata. There is no global registry that prevents two different smart contracts from claiming the same symbol. In practice this happens constantly with stablecoins and major tokens, because every cross-chain bridge issues its own representation under the same human-readable name. Concrete example. Search for “USDC”: 
curl -s "https://api.dexpaprika.com/search?query=USDC" | jq '.tokens[] | {chain, id, symbol}' | head -30
A real slice of the response today: 
chain=ethereum    id=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48  symbol=USDC
chain=solana      id=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v  symbol=USDC
chain=base        id=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913  symbol=USDC
chain=bsc         id=0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d  symbol=USDC
chain=arbitrum    id=0xaf88d065e77c8cc2239327c5edb3a432268e5831  symbol=USDC
chain=avalanche   id=0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e  symbol=USDC
Six different contracts. Six different id (address) values. One shared symbol. If you sum volume_usd across these by symbol, you produce a number that includes Avalanche-bridged USDC on Avalanche DEXes, Solana-native USDC on Solana DEXes, and Ethereum-native USDC on Ethereum DEXes — treated as if they were one token. They are not. They are six tokens that happen to share branding. The same trap exists for WETH, WBTC, USDT, DAI, and most other tokens that have been bridged to multiple chains.

​
The safe pattern: (chain, address) tuple

The only stable global identifier for a token is the combination of the chain it lives on and the contract address on that chain. Every DexPaprika response gives you both fields. Use both. Pseudocode: 
# Wrong:
totals = defaultdict(float)
for token in all_tokens:
    totals[token["symbol"]] += token["volume_usd"]

# Right:
totals = defaultdict(float)
for token in all_tokens:
    key = (token["chain"], token["id"].lower())
    totals[key] += token["volume_usd"]
The (chain, address) tuple is unique per token contract globally. There is no overlap. Lowercasing the address (for EVM chains) protects against checksum-vs-lowercase comparison bugs. See Identifiers for the case rules per chain.

​
When you really do want a cross-chain aggregate

Sometimes the bridge-merged number is the one you want. “How much USDC trading happens globally” is a reasonable question. Just make the merge explicit and intentional, not accidental. Pattern: maintain your own mapping of “this address on this chain is part of the same logical token as that address on the other chain.” Bridge tokens are a graph, not a set. The graph changes whenever a new chain integration ships. Sources for that mapping:
  • The bridge’s own canonical token list (Wormhole, Stargate, LayerZero, Across, Hop, etc.)
  • A symbology service that does this work for you (CoinGecko, CoinMarketCap, our sister product CoinPaprika)
  • Manual curation for the handful of tokens you actually care about
What you do not do is aggregate by symbol and assume the result is meaningful.

​
Searching across chains

When you start from a token name and don’t know the chains it lives on, use GET /search: 
curl -s "https://api.dexpaprika.com/search?query=jupiter" | jq '.tokens[] | {chain, id, name, symbol}'
The response is grouped by token (not by chain), and each entry includes the chain it lives on. From there you have your (chain, address) pair for any follow-up calls. For details on what fields the search endpoint returns, see Common patterns -> Pattern 1.

​
Checklist

Before you ship code that aggregates token data across chains:
  1. Confirm your join key is (chain, address), not symbol.
  2. Lowercase the address for EVM chains before comparing or hashing.
  3. If you intentionally collapse bridge variants, document the mapping somewhere a teammate will find.
  4. Write a unit test with at least two USDC addresses on different chains, asserting they do not collapse unless you explicitly want them to.