Query Token by Ticker (Symbol)

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

Basic Ticker Search

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 = "search_score"
) -> 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

Parameter	Type	Description
`input`	string	The ticker/symbol to search for. Wrap in `"` for exact match.
`limit`	number	Number of results (1-20, default: 5)
`sortBy`	string	Sort metric: `volume_24h`, `market_cap`, `fees_paid_24h`, etc.
`filters`	JSON	Filter options including `blockchains`

Available Sort Options

search_score - Composite ranking (fees × liquidity) (default)
volume_24h - 24h trading volume
market_cap - Market capitalization
volume_5min / volume_1h - Short-term volume
fees_paid_5min / fees_paid_1h / fees_paid_24h - Trading fees
holders_count - Number of holders
created_at - Token creation date

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 search_score metric combines fees and liquidity - perfect for finding actively traded tokens:

curl "https://api.mobula.io/api/2/fast-search?input=pepe&sortBy=search_score&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: 'search_score' 
  });
}

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

Universal Search API Reference - Full API documentation
Token Details - Get complete token data by address
Token Price - Real-time price data

Support

Need help? Join our community:

Overview

Extra

Guides

Query Token by Ticker (Symbol)

Overview

Quick Start

Basic Ticker Search

Exact Symbol Match

Code Examples

TypeScript / JavaScript

Python

Parameters

Available Sort Options

Response Format

2. Filter by Chain for Precision

3. Use Search Score for Discovery

Common Use Cases

Token Autocomplete

Multi-chain Token Resolver

Next Steps

Support

Overview

Extra

Guides

​Overview

​Quick Start

​Basic Ticker Search

​Exact Symbol Match

​Code Examples

​TypeScript / JavaScript

​Python

​Parameters

​Available Sort Options

​Response Format

​2. Filter by Chain for Precision

​3. Use Search Score for Discovery

​Common Use Cases

​Token Autocomplete

​Multi-chain Token Resolver

​Next Steps

​Support

Overview

Quick Start

Basic Ticker Search

Exact Symbol Match

Code Examples

TypeScript / JavaScript

Python

Parameters

Available Sort Options

Response Format

2. Filter by Chain for Precision

3. Use Search Score for Discovery

Common Use Cases

Token Autocomplete

Multi-chain Token Resolver

Next Steps

Support