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

# CoinGecko Coins API

> Get live market data for cryptocurrencies listed on CoinGecko: price, market cap and rank, 24h volume, supply, all-time high and low, and 1h/24h/7d price changes, by coin id, by ticker, or as the top coins by market cap in any of 60+ currencies.

`POST /v1/data/coingecko/coins/run`

**Pricing:** $0.0015 per coin ($1.50 per 1,000).

## Ways to call it

* **Top coins** (optional: `currency`, `maxResults`)
* **By coin ID**: set `coinIds` (optional: `currency`, `maxResults`)
* **By ticker**: set `symbols` (optional: `currency`, `maxResults`)
* **By category**: set `category` (optional: `currency`, `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**coinIds** `string[]`

CoinGecko coin ids, the last part of the coin page URL coingecko.com/en/coins/\<id> (e.g. bitcoin, ethereum, jasmycoin). One row per coin found; an unknown id returns no row and is not billed. Not allowed with Tickers.

**symbols** `string[]`

Coin tickers such as btc, eth, sol (any case). Each ticker returns its highest-ranked coin, so use Coin IDs when several coins share a ticker. Not allowed with Coin IDs.

**category** `string`

CoinGecko category id, the last part of coingecko.com/en/categories/\<id>, e.g. meme-token, layer-1, stablecoins. Returns the coins in that category by market cap.

**currency** `string` (default: USD)

Currency for price, market cap, volume, highs and lows. USD by default.

63 allowed values, for example `USD`, `EUR`, `GBP`, `JPY`, `CNY`, `KRW`, `INR`, `RUB`, `TRY`, `BRL`. Fetch the full list with `GET /v1/data/coingecko/coins?expand=options`.

**maxResults** `integer` (default: 100)

How many coins to return in total, up to 1000. Defaults to 100; use 0 for all.

Max `1000`.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/coingecko/coins/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "coinIds": [
      "bitcoin",
      "ethereum",
      "tether"
    ],
    "maxResults": 10
  }
}'
```

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

r = requests.post(
    "https://api.mindcase.co/v1/data/coingecko/coins/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "coinIds": [
        "bitcoin",
        "ethereum",
        "tether"
    ],
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/coingecko/coins/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "coinIds": [
    "bitcoin",
    "ethereum",
    "tether"
  ],
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one coin, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `coinId` | Coin ID | text |
| `coinUrl` | Coin URL | url |
| `symbol` | Symbol | text |
| `name` | Name | text |
| `rank` | Rank | number |
| `price` | Price | currency |
| `currency` | Currency | text |
| `change1h` | Change 1h | percentage |
| `change24h` | Change 24h | percentage |
| `change7d` | Change 7d | percentage |
| `marketCap` | Market Cap | currency |
| `marketCapChange24h` | Market Cap Change 24h | percentage |
| `fdv` | FDV | currency |
| `volume24h` | Volume 24h | currency |
| `high24h` | High 24h | currency |
| `low24h` | Low 24h | currency |
| `circulatingSupply` | Circulating Supply | number |
| `totalSupply` | Total Supply | number |
| `maxSupply` | Max Supply | number |
| `ath` | ATH | currency |
| `athChangePct` | ATH Change Pct | percentage |
| `athDate` | ATH Date | datetime |
| `atl` | ATL | currency |
| `atlDate` | ATL Date | datetime |
| `image` | Image | image |
| `lastUpdated` | Last Updated | datetime |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "coingecko/coins",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "circulatingSupply": 20105365,
      "coinId": "bitcoin",
      "atl": 67.81,
      "fdv": 1570613221434,
      "atlDate": "2013-07-05T16:00:00.000Z",
      "name": "Bitcoin",
      "marketCap": 1570613221434,
      "coinUrl": "https://www.coingecko.com/en/coins/bitcoin",
      "rank": 1,
      "change24h": 0.31,
      "marketCapChange24h": 0.3,
      "change7d": -2.1,
      "low24h": 77616,
      "volume24h": 17016910013,
      "ath": 126080,
      "change1h": -0.06,
      "totalSupply": 20105365,
      "athChangePct": -38.04,
      "athDate": "2025-10-06T10:57:42.000Z",
      "lastUpdated": "2026-11-02T06:31:43.000Z",
      "maxSupply": 21000000,
      "high24h": 78733,
      "symbol": "BTC",
      "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
      "currency": "usd"
    }
  ]
}
```

## Related APIs

For funding, investors and contract addresses use [`crypto/projects`](https://docs.mindcase.co/apis/crypto/projects).


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