Skip to main content

​
Overview

While most APIs require contract addresses to retrieve token data, Mobula’s Universal Search (/api/2/fast-search) allows you to query tokens directly by their ticker symbol (like USDC, ETH, SOL). This is perfect for:
  • Building search interfaces for users
  • Quick token lookups without knowing the address
  • Supporting multiple chains with a single query
The API responds in under 30ms and returns detailed token information matching your query.

​
Quick Start

curl "https://api.mobula.io/api/2/fast-search?input=usdc"
This returns all tokens with the symbol or name starting with “usdc”, sorted by trading activity.

​
Exact Symbol Match

Wrap your ticker in double quotes for exact matching (useful for short tickers): 
curl "https://api.mobula.io/api/2/fast-search?input=\"W\""
This returns only tokens with the exact symbol “W” (like Wormhole), not “WETH”, “WBTC”, etc.

​
Code Examples

​
TypeScript / JavaScript

interface TokenResult {
  name: string | null;
  symbol: string | null;
  address: string;
  chainId: string;
  decimals: number;
  priceUSD: number;
  priceChange24hPercentage: number;
  volume24hUSD: number;
  marketCapUSD: number;
  liquidityUSD?: number;
  logo: string | null;
  createdAt: string | null;
  holdersCount: number;
  // ... many more fields available
}

interface SearchResponse {
  data: TokenResult[];
}

async function searchByTicker(
  ticker: string, 
  options?: { 
    exact?: boolean;
    chains?: string[];
    limit?: number;
    sortBy?: string;
  }
): Promise<TokenResult[]> {
  const params = new URLSearchParams();
  
  // Use exact match syntax if specified
  const input = options?.exact ? `"${ticker}"` : ticker;
  params.set('input', input);
  
  // Optional: filter by blockchains
  if (options?.chains?.length) {
    params.set('filters', JSON.stringify({ 
      blockchains: options.chains.join(',') 
    }));
  }
  
  // Optional: limit results (1-20, default: 5)
  if (options?.limit) {
    params.set('limit', options.limit.toString());
  }
  
  // Optional: sort by metric
  if (options?.sortBy) {
    params.set('sortBy', options.sortBy);
  }
  
  const response = await fetch(
    `https://api.mobula.io/api/2/fast-search?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.MOBULA_API_KEY}`,
      },
    }
  );
  
  const data: SearchResponse = await response.json();
  return data.data;
}

// Usage examples
const usdcTokens = await searchByTicker('usdc');
console.log(usdcTokens[0]); // Most traded USDC

const exactW = await searchByTicker('W', { exact: true });
console.log(exactW[0]); // Wormhole token

const solanaUsdc = await searchByTicker('usdc', { 
  chains: ['solana'],
  limit: 1 
});
console.log(solanaUsdc[0]); // USDC on Solana only

​
Python

import requests
import json
from typing import Optional

def search_by_ticker(
    ticker: str,
    exact: bool = False,
    chains: Optional[list[str]] = None,
    limit: int = 5,
    sort_by: str = "searchScore"
) -> list[dict]:
    """Search for tokens by ticker symbol."""
    
    # Use exact match syntax if specified
    input_query = f'"{ticker}"' if exact else ticker
    
    params = {
        "input": input_query,
        "limit": limit,
        "sortBy": sort_by
    }
    
    # Optional chain filter
    if chains:
        params["filters"] = json.dumps({"blockchains": ",".join(chains)})
    
    response = requests.get(
        "https://api.mobula.io/api/2/fast-search",
        params=params,
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    
    return response.json()["data"]


# Usage examples
usdc_tokens = search_by_ticker("usdc")
print(f"Top USDC: {usdc_tokens[0]['name']} at ${usdc_tokens[0]['priceUSD']}")

# Exact match for short symbols
w_token = search_by_ticker("W", exact=True)
print(f"W token: {w_token[0]['name']}")

# Filter by chain
sol_pepe = search_by_ticker("pepe", chains=["solana"], limit=3)
for token in sol_pepe:
    print(f"{token['symbol']}: {token['address']}")

​
Parameters

ParameterTypeDescription
inputstringThe ticker/symbol to search for. Wrap in " for exact match.
limitnumberNumber of results (1-20, default: 5)
sortBystringSort metric: volume24h, marketCap, feesPaid24h, etc. (default: searchScore)
filtersJSONFilter options including blockchains

​
Available Sort Options

  • searchScore - Composite ranking (fees × liquidity) (default)
  • volume24h - 24h trading volume
  • marketCap - Market capitalization
  • volume5min / volume1h - Short-term volume
  • feesPaid5min / feesPaid1h / feesPaid24h - Trading fees
  • holdersCount - Number of holders
  • organicVolume1h - Organic 1h volume
  • totalFeesPaidUsd - Total fees paid in USD
  • createdAt - Token creation date
  • trendingScore24h - 24h trending score

​
Response Format

Each token in the response follows the full Token Details data model. Here’s an example with key fields: 
{
  "data": [
    {
      "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "chainId": "solana:solana",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "logo": "https://...",

      "priceUSD": 0.9999,
      "priceToken": 1.0001,
      "priceTokenString": "1000100000000000000",
      "marketCapUSD": 25000000000,
      "marketCapDilutedUSD": 30000000000,
      "totalSupply": 30000000000,
      "circulatingSupply": 25000000000,

      "liquidityUSD": 500000000,
      "approximateReserveUSD": 250000000,
      "approximateReserveToken": 250000000,

      "priceChange5minPercentage": 0.01,
      "priceChange1hPercentage": 0.02,
      "priceChange24hPercentage": 0.05,

      "volume5minUSD": 1000000,
      "volume1hUSD": 50000000,
      "volume24hUSD": 1234567890,

      "trades5min": 500,
      "trades1h": 5000,
      "trades24h": 50000,
      "buys24h": 28000,
      "sells24h": 22000,
      "buyers24h": 15000,
      "sellers24h": 12000,
      "traders24h": 20000,

      "feesPaid24hUSD": 123456,
      "totalFeesPaidUSD": 9876543,

      "holdersCount": 1500000,
      "createdAt": "2020-10-15T00:00:00.000Z",
      "latestTradeDate": "2026-01-27T15:30:00.000Z",

      "deployer": "...",
      "poolAddress": "...",
      "factory": "...",
      "exchange": {
        "name": "Raydium",
        "logo": "https://..."
      },

      "socials": {
        "twitter": "https://twitter.com/...",
        "website": "https://...",
        "telegram": "https://t.me/..."
      },

      "security": {
        "mintable": false,
        "freezable": false,
        "lpBurned": true
      }
    }
  ]
}
The response includes 100+ fields per token including organic metrics, trending scores, DEXScreener data, and more. See the Token Details endpoint for the complete schema.

## Best Practices

### 1. Use Exact Match for Short Symbols

Short symbols (1-3 characters) can return noisy results. Use double quotes:

```bash
# Returns many results: "W", "WETH", "WBTC", "WRAPPED"...
curl "https://api.mobula.io/api/2/fast-search?input=w"

# Returns only exact "W" symbol
curl "https://api.mobula.io/api/2/fast-search?input=\"w\""

​
2. Filter by Chain for Precision

If you know the target chain, filter to avoid cross-chain duplicates: 
curl "https://api.mobula.io/api/2/fast-search?input=usdc&filters={\"blockchains\":\"solana\"}"

​
3. Use Search Score for Discovery

The searchScore metric combines fees and liquidity - perfect for finding actively traded tokens: 
curl "https://api.mobula.io/api/2/fast-search?input=pepe&sortBy=searchScore&limit=10"

​
Common Use Cases

​
Token Autocomplete

Build a search bar with live suggestions: 
async function getAutocomplete(query: string): Promise<TokenResult[]> {
  if (query.length < 2) return [];
  
  return searchByTicker(query, { 
    limit: 5,
    sortBy: 'searchScore'
  });
}

​
Multi-chain Token Resolver

Get the same token across multiple chains: 
async function getTokenAcrossChains(ticker: string): Promise<Map<string, TokenResult>> {
  const results = await searchByTicker(ticker, { 
    exact: true,
    limit: 20 
  });
  
  const byChain = new Map<string, TokenResult>();
  for (const token of results) {
    if (!byChain.has(token.chainId)) {
      byChain.set(token.chainId, token);
    }
  }
  
  return byChain;
}

const usdcByChain = await getTokenAcrossChains('USDC');
console.log('USDC on Ethereum:', usdcByChain.get('evm:1')?.address, 'at $', usdcByChain.get('evm:1')?.priceUSD);
console.log('USDC on Solana:', usdcByChain.get('solana:solana')?.address);

​
Next Steps

​
Support

Need help? Join our community: