---
title: "Token Rankings"
method: GET
path: "/gateway/v1/market/ranking"
tags: ["Market"]
---

# Token Rankings

`GET /gateway/v1/market/ranking`

## Request

- Base URL: `https://api.asksurf.ai`
- URL: `https://api.asksurf.ai/gateway/v1/market/ranking`
- Auth: HTTP bearer

Returns a token leaderboard sorted by market cap, 24h change, or volume. Each entry includes price, market cap, FDV, supply, ATH/ATL, and 24h range. Supports category filtering (MEME, AI, L1, L2, DEFI, GAMING, etc.).

**Available metrics:** `market_cap`, `top_gainers`, `top_losers`, `volume`.

**Note:** `top_gainers` and `top_losers` rank by 24h price change within the top 250 coins by market cap.

For circulating supply, FDV, ATH/ATL, use `/project/detail?fields=token_info`.

## Query parameters

- `sort_by` 'market_cap' | 'change_24h' | 'volume_24h': Field to sort by. `market_cap` sorts by total market capitalisation, `change_24h` sorts by 24-hour price change percentage (fetches top 250 by market cap then sorts client-side), `volume_24h` sorts by 24-hour trading volume.
- `order` 'asc' | 'desc': Sort order: `desc` (default, highest first) or `asc` (lowest first).
- `category` 'MEME' | 'AI' | 'AI_AGENTS' | 'L1' | 'L2' | 'DEFI' | 'GAMING' | 'STABLECOIN' | 'RWA' | 'DEPIN' | 'SOL_ECO' | 'BASE_ECO' | 'LST': Optional token category filter. When provided, results are limited to coins in that category. Supported values: MEME, AI, AI_AGENTS, L1, L2, DEFI, GAMING, STABLECOIN, RWA, DEPIN, SOL_ECO, BASE_ECO, LST.
- `limit` integer: Results per page
- `offset` integer: Pagination offset

## Response `200`

OK

- DataResponseMarketTopCoinItem
  - `$schema` string, uri: A URL to the JSON Schema for this object.
  - `data` MarketTopCoinItem[], nullable, required
    - `ath` number, double: All-time high price in USD
    - `ath_date` integer: Unix timestamp in seconds when the all-time high price was reached
    - `atl` number, double: All-time low price in USD
    - `atl_date` integer: Unix timestamp in seconds when the all-time low price was reached
    - `change_24h_pct` number, double, required: Price change percentage over the last 24 hours
    - `circulating_supply` number, double: Circulating token supply
    - `fdv` number, double: Fully diluted valuation in USD
    - `high_24h` number, double, required: Highest price in the last 24 hours in USD
    - `id` string: Surf project UUID. Empty when no matching Surf project metadata is available.
    - `image` string: Token logo image URL
    - `low_24h` number, double, required: Lowest price in the last 24 hours in USD
    - `market_cap_usd` number, double, required: Total market capitalization in USD
    - `max_supply` number, double: Maximum token supply (e.g. 21M for BTC). Not available for all tokens.
    - `name` string, required: Full token name
    - `price_usd` number, double, required: Current price in USD
    - `rank` integer, required: Rank position in the list (1 = highest)
    - `slug` string: Surf project slug. Empty under the same conditions as id.
    - `symbol` string, required: Token ticker symbol like `BTC` or `ETH`
    - `total_supply` number, double: Total token supply
    - `volume_24h_usd` number, double, required: 24-hour trading volume in USD
  - `meta` OffsetMeta, required
    - `cached` boolean, required: Whether this response was served from cache
    - `credits_used` integer, required: Credits deducted for this request
    - `empty_reason` string: Hint explaining why the data array is empty, when applicable
    - `has_more` boolean: Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required: Maximum number of items returned in this response
    - `offset` integer, required: Number of items skipped (pagination offset)
    - `total` integer: Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer: Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) - [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/revisions/91774fdd5302?raw)