> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Token by Ticker (Symbol)

> Learn how to search and retrieve token data using a ticker symbol like USDC, ETH, or SOL instead of contract addresses

## 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

```bash theme={null}
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):

```bash theme={null}
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

```typescript theme={null}
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

```python theme={null}
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

| 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: `volume24h`, `marketCap`, `feesPaid24h`, etc. (default: `searchScore`) |
| `filters` | JSON   | Filter 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](/rest-api-reference/endpoint/token-details) data model. Here's an example with key fields:

```json theme={null}
{
  "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
      }
    }
  ]
}
```

<Info>
  The response includes 100+ fields per token including organic metrics, trending scores, DEXScreener data, and more. See the [Token Details endpoint](/rest-api-reference/endpoint/token-details) for the complete schema.
</Info>

````

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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](/rest-api-reference/endpoint/fast-search) - Full API documentation
* [Token Details](/rest-api-reference/endpoint/token-details) - Get complete token data by address
* [Token Price](/rest-api-reference/endpoint/token-price) - Real-time price data

## Support

Need help? Join our community:

* [Discord](https://discord.gg/JVT7xKm3AD)
* [Telegram](https://t.me/mobuladevelopers)
* Email: [contact@mobulalabs.org](mailto:contact@mobulalabs.org)