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

# Gem Finder API

> Screen market-ranked assets by market cap, volume, price change, ATH history, FDV/MCap, chain scope, and observed exchange availability.

The Gem Finder endpoint returns up to 1,000 market-ranked assets after stablecoin, derivative-asset (wrapped, bridged, pegged, liquid-staking, synthetic, tokenized-stock), quote-freshness (quotes older than 24 hours are treated as no-longer-trading), minimum-market-cap, and minimum-volume filters. Rows include market, supply, ATH/ATL, dilution, chain-scope, and observed exchange-availability fields; no proprietary token score or wallet signal is returned. The complete dataset refreshes every 6 hours.

***

## Get gem finder data

`GET /v1/gem-finder/data`

Returns the gem finder dataset including coins, available exchanges, and metadata.

### Query parameters

**chain** `string`

Keep only assets whose home chain (`chainSlug`: CoinGecko's primary asset platform, or the chain itself for its own coin) is this chain, e.g. `solana`, `base`, `arbitrum`, `bsc`. A token only bridged there (listed in `chainSlugs`) does not match. A chain's own coin is homed on that chain (SOL under `solana`, BNB under `bsc`); a coin or token whose home chain is unsupported (BTC, ICP) matches none. An unknown chain is a `400`. Send the same `chain` with each `cursor`.

**limit** `integer`

Maximum number of coins per page. `1` to `1000`. When omitted, the complete cached payload is returned. When provided, the response contains a page array plus a `pagination` object.

**cursor** `string`

Opaque cursor for fetching the next page. It is bound to one cache snapshot and expires after a refresh; restart without a cursor after an expiry error.

### Response fields

**coins** `array`

Array of coin objects containing symbol, name, price, market cap, nullable FDV, 24-hour volume, nullable 24-hour and 7-day price returns (`return24h`, `return7d`), a nullable 24-hour market cap return (`marketCapReturn24h`), nullable circulating supply, nullable ATH price and date and the price against it (`fromAth`), nullable ATL price and the price against it (`fromAtl`), nullable FDV/MCap ratio, exchange coverage, a nullable preferred chain slug, and a nullable `lastUpdated` quote timestamp. The returns, `fromAth` and `fromAtl` are fractions: `0.0532` is +5.32%, and `-0.9` is 90% below the ATH. Missing or invalid upstream values stay `null` — they are never coerced to zero; ambiguous same-ticker assets do not receive exchange attribution from symbol-only venue feeds.

**availableExchanges** `array`

List of exchange identifiers that appear across the coin set. Useful for building client-side filters.

**totalCoins** `integer`

Total number of coins in the dataset.

**updatedAt** `string`

ISO 8601 timestamp of the last data refresh. `null` if data has not yet been populated.

**syncStatus** `object`

Sync completeness and enrichment-coverage metadata when present. `enrichment.platform` reports fresh versus preserved chain assignments; `enrichment.exchanges` lists successful and failed venue sources plus preserved last-good listings. Degraded enrichment is surfaced through `X-Sharpe-Data-State: partial`; incomplete market pages still preserve the entire last-good cache.

When `limit` is supplied, the response is wrapped with a sibling `pagination` object alongside `data`:

**pagination.cursor** `string | null`

Opaque, snapshot-bound cursor to pass back as `cursor` on the next request. `null` when there are no more pages.

**pagination.has\_more** `boolean`

`true` when more rows are available after this page; `false` when this is the last page.

**pagination.total** `number`

Total number of rows in the unpaginated dataset, when available. Omitted for endpoints that do not compute a count.

A missing-but-readable cache row returns a legitimate empty dataset with
`X-Sharpe-Data-State: empty`. A cache/database read failure returns `503`
(`service_unavailable`, `Retry-After: 30`) instead of masquerading as an
empty market.

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/gem-finder/data \
  -H "Authorization: Bearer sk_live_your_key_here"
```

```ts TypeScript theme={null}
const res = await fetch('https://www.sharpe.ai/api/v1/gem-finder/data', {
  headers: { Authorization: 'Bearer sk_live_your_key_here' },
})
const { data } = await res.json()
```

```python Python theme={null}
import requests

resp = requests.get(
    "https://www.sharpe.ai/api/v1/gem-finder/data",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "coins": [
      {
        "id": "example-token",
        "symbol": "EXM",
        "name": "Example Token",
        "image": "https://assets.coingecko.com/example.png",
        "price": 0.142,
        "marketCap": 12500000,
        "fdv": 18750000,
        "volume24h": 890000,
        "return24h": 0.0532,
        "return7d": 0.124,
        "athPrice": 1.42,
        "fromAth": -0.9,
        "athDate": "2025-11-18T00:00:00Z",
        "fdvMcapRatio": 1.5,
        "exchangeCount": 2,
        "exchanges": ["Binance", "Bybit"],
        "chainSlug": "ethereum",
        "chainSlugs": ["ethereum", "arbitrum"],
        "lastUpdated": "2026-03-28T11:54:31Z"
      }
    ],
    "availableExchanges": [
      "Binance",
      "Bybit"
    ],
    "totalCoins": 997,
    "updatedAt": "2026-03-28T11:55:00Z"
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T11:55:05Z",
    "elapsed_ms": 12
  }
}
```

[Read the error reference](https://docs.sharpe.ai/errors.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.