# Token search

- Method: `GET`
- Path: `/tokens/search`
- Tier: Basic
- HTML docs: https://docs.ruma.fun/reference/get-tokens-search/
- Interactive docs: https://docs.ruma.fun/#endpoint=get-tokens-search

## Description

Search tokens by symbol, name, or contract address. Returns matching tokens ordered by relevance. Use q for the query string and limit (max 50) to cap results.

## cURL Example

```bash
curl --request GET \
  --url 'https://api.ruma.fun/api/v1/public/tokens/search?q=string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `q` (string, required): Search query. For tokens this matches symbol, name, or contract address; for accounts it matches display name or handle.
- `limit` (integer, optional): Maximum number of results to return (default 10, max 50).

## Response

OK

- `query` (string): Normalized query string that was searched.
- `tokens` (array<object>): Matching tokens ordered by relevance.
- `tokens[].coingecko_id` (string): CoinGecko asset identifier when available; null otherwise.
- `tokens[].followers` (integer (int64)): Project follower count when available; null otherwise.
- `tokens[].handle` (string): Primary social handle for the token's project; null when unknown.
- `tokens[].image_url` (string): Token logo URL.
- `tokens[].market_cap_usd` (number (double)): Latest known market capitalization in USD; null when unavailable.
- `tokens[].name` (string): Human-readable token name.
- `tokens[].price_change_24h_pct` (number (double)): 24h price change percentage; null when unavailable.
- `tokens[].price_usd` (number (double)): Latest known USD price; null when unavailable.
- `tokens[].symbol` (string): Primary trading symbol.
- `tokens[].token_id` (integer (int64)): Internal Ruma token identifier.
- `total` (integer): Number of tokens returned in this response.

Media type: `application/json`

## JSON Response

```json
{
  "query": "string",
  "tokens": [
    {
      "coingecko_id": "string",
      "followers": 0,
      "handle": "string",
      "image_url": "string",
      "market_cap_usd": 0,
      "name": "string",
      "price_change_24h_pct": 0,
      "price_usd": 0,
      "symbol": "string",
      "token_id": 0
    }
  ],
  "total": 0
}
```