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

# Market Cap Search API

> Search crypto and supported TradFi assets by name or symbol, with asset class, market cap, nullable prices, crypto FDV, and estimated ATH fields.

The Market Cap Search endpoint looks up crypto and supported TradFi assets by name or ticker. It returns current market cap, price, the day's return, and crypto-specific FDV and estimated ATH fields where available. Use it to power "what if" comparisons across tokens, stocks, indices, and commodities.

***

## Search assets

`GET /v1/market-cap/search`

Searches the same crypto and TradFi universe used by the terminal and returns up to 20 results. Results are filtered to assets with non-zero market cap and sorted by market cap descending. When CoinGecko fails and no TradFi asset matches, the request returns `503` (`service_unavailable`, `Retry-After: 60`, detail "CoinGecko is unavailable."); an answer missing its TradFi or CoinGecko half says so in `meta.runtime_status: "degraded"` and is never cached.

### Query parameters

**q** `string` *required*

Search query string. Minimum 2 characters, maximum 100. Matches asset ID, name, or symbol.

### Response fields

**assets** `array`

Array of matching asset objects (max 20). Returns an empty array if no matches are found.

**assets\[].id** `string`

Canonical asset identifier (e.g., `bitcoin`, `ethereum`).

**assets\[].name** `string`

Full asset name.

**assets\[].symbol** `string`

Uppercase ticker symbol (e.g., `BTC`, `ETH`).

**assets\[].assetClass** `string`

Asset class identifier: `crypto`, `stock`, `index`, or `commodity`.

**assets\[].price** `number`

Current price in USD. `null` when the upstream did not publish a price.

**assets\[].marketCap** `number`

Current market capitalization in USD.

**assets\[].fdv** `number`

Fully diluted valuation in USD. `null` when FDV is not available.

**assets\[].ath** `number`

All-time high price in USD. `null` when not available.

**assets\[].athMarketCap** `number`

Estimated market cap at all-time high using current circulating supply. This is not historical point-in-time market cap and can overstate inflationary assets. `null` when ATH or current price is unavailable.

**assets\[].dayReturn** `number`

The day's price return as a fraction (`0.0215` is +2.15%). For crypto it is the last 24 hours, to 4 decimal places; for stocks, ETFs, indices and commodity proxies it is the last trading session against the prior close, not a rolling 24 hours. `null` when unavailable.

**assets\[].image** `string`

URL to the asset's logo image. Empty string `""` if no logo is published.

`GET /v1/market-cap/search?q=bitcoin`

```bash cURL theme={null}
curl -G https://www.sharpe.ai/api/v1/market-cap/search \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -d q=bitcoin
```

```ts TypeScript theme={null}
const res = await fetch(
  'https://www.sharpe.ai/api/v1/market-cap/search?q=bitcoin',
  {
    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/market-cap/search",
    headers={"Authorization": "Bearer sk_live_your_key_here"},
    params={"q": "bitcoin"},
)
data = resp.json()["data"]
```

```json Response theme={null}
{
  "data": {
    "assets": [
      {
        "id": "bitcoin",
        "name": "Bitcoin",
        "symbol": "BTC",
        "assetClass": "crypto",
        "price": 95200,
        "marketCap": 1870000000000,
        "fdv": 1998000000000,
        "ath": 108786,
        "athMarketCap": 2137000000000,
        "dayReturn": 0.0215,
        "image": "https://assets.sharpe.ai/coins/bitcoin.png"
      },
      {
        "id": "bitcoin-cash",
        "name": "Bitcoin Cash",
        "symbol": "BCH",
        "assetClass": "crypto",
        "price": 482,
        "marketCap": 9560000000,
        "fdv": 10120000000,
        "ath": 4355,
        "athMarketCap": 86400000000,
        "dayReturn": 0.0087,
        "image": "https://assets.sharpe.ai/coins/bitcoin-cash.png"
      }
    ]
  },
  "meta": {
    "request_id": "req_abc123def456ghij",
    "timestamp": "2026-03-28T12:00: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.