# 幣種市場

**API:** Data API

**Endpoint:** `GET /v1/beta/coingecko/coins/markets`

**Tags:** CoinGecko

一次涵蓋多個幣種的排名市場表：每幣種一列，包含 `current_price`、`market_cap`、`market_cap_rank`、`total_volume`、`high_24h`、`low_24h`、`price_change_percentage_24h`、`circulating_supply`、`total_supply`、`max_supply`、`ath` 與 `atl`（含日期）以及 `image`。以 `per_page` 與 `page` 分頁，以 `order` 排序（市值、成交量或 id，遞增或遞減），並以 `ids` 或 `category` 縮小範圍。傳入 `price_change_percentage` 會加入對應的 `price_change_percentage_24h_in_currency` 欄位。適用於排行榜與區段掃描。若只要幾個已知幣種的價格，`get_coingecko_simple_price` 輕量許多；若要看單一幣種的完整資料，請用 `get_coingecko_coins_id`。

### 定價參考

- 計量方式：方案資源單位。
- 參考請求預估：USD 0.008。
- 單位成本基礎：USD 0.0。
- 資源單位：`provider_credit`。
- 成本基礎不構成最終客戶價格，即使為零亦同。

僅供參考的中繼資料，並非帳戶報價、保證價格或消費上限。資源額度並非 Felo 額度。最終費用依 Felo 計費記錄為準。

## Base URL

- `https://openapi.felo.ai`

## Authentication

- `FeloBearerAuth` (http bearer, bearer format Felo API Key)
- `FeloApiKey` (apiKey in header `X-API-Key`)

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `category` | query | no | string | 依幣種類別篩選。 *參見 [`/coins/categories/list`](/reference/coins-categories-list) |
| `ids` | query | no | string, default: "bitcoin" | 幣種 ID，查詢多個幣種時以逗號分隔。 *參見 [`/coins/list`](/reference/coins-list) |
| `include_rehypothecated` | query | no | boolean | 在結果中包含再質押代幣。為 true 時傳回 `market_cap_rank_with_rehypothecated` 欄位。 預設：false |
| `include_tokens` | query | no | string, enum: "top", "all" | 使用 `symbols` 查詢時，指定 `all` 可包含所有相符的代幣。 預設的 `top` 會依市值或成交量傳回排名最前的代幣。 |
| `locale` | query | no | string, enum: "ar", "bg", "cs", "da", "de", "el", … | 語言背景。 預設：en |
| `names` | query | no | string, default: "Bitcoin" | 幣種名稱，查詢多個幣種時以逗號分隔。 |
| `order` | query | no | string, enum: "market_cap_asc", "market_cap_desc", "volume_asc", "volume_desc", "id_asc", "id_desc" | 依欄位排序結果。 預設：market_cap_desc |
| `page` | query | no | integer | 分頁瀏覽結果。 預設：1 |
| `per_page` | query | no | integer | 每頁結果總數。 預設：100 有效值：1...250 |
| `precision` | query | no | string, enum: "full", "0", "1", "2", "3", "4", … | 貨幣價格值的小數位數 |
| `price_change_percentage` | query | no | string | 包含價格變化百分比的時間範圍，查詢多個時間範圍時以逗號分隔。 有效值：`1h`、`24h`、`7d`、`14d`、`30d`、`200d`、`1y` |
| `sparkline` | query | no | boolean | 包含 7 天 sparkline 資料。 預設：false |
| `symbols` | query | no | string, default: "btc" | 幣種符號，查詢多個幣種時以逗號分隔。 |
| `vs_currency` | query | yes | string, default: "usd" | 幣種與市場資料的計價貨幣。 *參見 [`/simple/supported_vs_currencies`](/reference/simple-supported-currencies) |

## Responses

### 200 — 附市場資料的幣種列表

Headers:
- `X-Request-Id` (string) — 聯絡 Felo 支援時需提供的請求識別碼。

**application/json**

Schema: `Response860C3Ae68Ea5_CoinsMarkets` (`#/components/schemas/Response860C3Ae68Ea5_CoinsMarkets`)

Example:

```json
[
  {
    "id": "bitcoin",
    "symbol": "btc",
    "name": "Bitcoin",
    "image": "https://coin-images.coingecko.com/coins/images/1/large/bitcoin.png?1696501400",
    "current_price": 77671,
    "market_cap": 1555886872303,
    "market_cap_rank": 1,
    "fully_diluted_valuation": 1555914058873,
    "total_volume": 33235034316,
    "high_24h": 78419,
    "low_24h": 76696,
    "price_change_24h": -747.3360347281705,
    "price_change_percentage_24h": -0.95302,
    "market_cap_change_24h": -15184401491.513184,
    "market_cap_change_percentage_24h": -0.9665,
    "circulating_supply": 20030493,
    "total_supply": 20030843,
    "max_supply": 21000000,
    "ath": 126080,
    "ath_change_percentage": -38.39571,
    "ath_date": "2025-10-06T18:57:42.558Z",
    "atl": 67.81,
    "atl_change_percentage": 114443.23093,
    "atl_date": "2013-07-06T00:00:00.000Z",
    "roi": null,
    "last_updated": "2026-05-18T12:49:21.599Z",
    "market_cap_rank_with_rehypothecated": 1,
    "sparkline_in_7d": {
      "price": [
        81045.84776489827,
        81001.73089268175,
        80898.20817826076
      ]
    },
    "price_change_percentage_1h_in_currency": 0.5823392426906319,
    "price_change_percentage_24h_in_currency": -0.9530164743774191,
    "price_change_percentage_7d_in_currency": -4.042267423689584,
    "price_change_percentage_14d_in_currency": -1.5720857443461431,
    "price_change_percentage_30d_in_currency": 1.9453890367549207,
    "price_change_percentage_200d_in_currency": -29.452371850925864,
    "price_change_percentage_1y_in_currency": -25.214612207475373
  }
]
```

### 400 — 無法處理該要求。請檢查請求參數。

### 401 — 需要有效的 Felo API 金鑰。

### 402 — 由於未符合計費要求，要求無法繼續。

### 403 — 該帳戶無權執行此操作。

### 429 — 已達到要求或支出上限。

### 502 — 服務無法完成該要求。

### 503 — API 或計費服務暫時無法使用。

### 504 — 服務在處理要求時逾時。

### default — 錯誤回應；上游透傳回應可能採用供應商格式

**application/json**

Schema:

```json
{}
```

## Schema definitions

### Response860C3Ae68Ea5_CoinsMarkets

`#/components/schemas/Response860C3Ae68Ea5_CoinsMarkets`

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "required": [
      "id",
      "symbol",
      "name",
      "image",
      "current_price",
      "market_cap",
      "market_cap_rank",
      "fully_diluted_valuation",
      "total_volume",
      "high_24h",
      "low_24h",
      "price_change_24h",
      "price_change_percentage_24h",
      "market_cap_change_24h",
      "market_cap_change_percentage_24h",
      "circulating_supply",
      "total_supply",
      "max_supply",
      "ath",
      "ath_change_percentage",
      "ath_date",
      "atl",
      "atl_change_percentage",
      "atl_date",
      "roi",
      "last_updated"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "代幣 ID"
      },
      "symbol": {
        "type": "string",
        "description": "代幣符號"
      },
      "name": {
        "type": "string",
        "description": "代幣名稱"
      },
      "image": {
        "type": "string",
        "description": "代幣圖片 URL"
      },
      "current_price": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的當前價格"
      },
      "market_cap": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的市值"
      },
      "market_cap_rank": {
        "type": [
          "integer",
          "null"
        ],
        "description": "市值排名"
      },
      "fully_diluted_valuation": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的完全稀釋估值"
      },
      "total_volume": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的總交易量"
      },
      "high_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 24 小時最高價"
      },
      "low_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 24 小時最低價"
      },
      "price_change_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 24 小時價格變動"
      },
      "price_change_percentage_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "24 小時價格漲跌幅"
      },
      "market_cap_change_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 24 小時市值變動"
      },
      "market_cap_change_percentage_24h": {
        "type": [
          "number",
          "null"
        ],
        "description": "24 小時市值變動百分比"
      },
      "circulating_supply": {
        "type": [
          "number",
          "null"
        ],
        "description": "流通供應量"
      },
      "total_supply": {
        "type": [
          "number",
          "null"
        ],
        "description": "總供給量"
      },
      "max_supply": {
        "type": [
          "number",
          "null"
        ],
        "description": "最大供給量"
      },
      "ath": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的歷史最高價"
      },
      "ath_change_percentage": {
        "type": [
          "number",
          "null"
        ],
        "description": "歷史最高價變化百分比"
      },
      "ath_date": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "歷史最高價日期"
      },
      "atl": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的歷史最低價"
      },
      "atl_change_percentage": {
        "type": [
          "number",
          "null"
        ],
        "description": "歷史最低價變化百分比"
      },
      "atl_date": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "歷史最低價日期"
      },
      "roi": {
        "type": [
          "object",
          "null"
        ],
        "description": "投資報酬率資料",
        "properties": {
          "times": {
            "type": "number",
            "description": "投資報酬率倍數"
          },
          "currency": {
            "type": "string",
            "description": "投資報酬率貨幣"
          },
          "percentage": {
            "type": "number",
            "description": "投資報酬率百分比"
          }
        }
      },
      "last_updated": {
        "type": "string",
        "format": "date-time",
        "description": "最後更新時間戳記"
      },
      "market_cap_rank_with_rehypothecated": {
        "type": [
          "integer",
          "null"
        ],
        "description": "包含再抵押代幣的市值排名"
      },
      "sparkline_in_7d": {
        "type": "object",
        "description": "最近 7 天的 sparkline 價格資料",
        "properties": {
          "price": {
            "type": "array",
            "items": {
              "type": "number"
            },
            "description": "價格值陣列"
          }
        }
      },
      "price_change_percentage_1h_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 1 小時價格漲跌幅"
      },
      "price_change_percentage_24h_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 24 小時價格漲跌幅"
      },
      "price_change_percentage_7d_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 7 天價格漲跌幅"
      },
      "price_change_percentage_14d_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 14 天價格漲跌幅"
      },
      "price_change_percentage_30d_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 30 天價格漲跌幅"
      },
      "price_change_percentage_200d_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 200 天價格漲跌幅"
      },
      "price_change_percentage_1y_in_currency": {
        "type": [
          "number",
          "null"
        ],
        "description": "以目標貨幣計的 1 年價格漲跌幅"
      }
    }
  }
}
```