---
updatedAt: 2026-11-11T00:36:15.000Z
agentTools:
  projectIndex: https://docs.coinglass.com/v4.0-zhtw/llms.txt
---

# 現貨聚合累計成交量差值（CVD）

獲取某個幣種在指定交易所的現貨累計成交量差值（CVD）歷史，是該幣種多個交易對的聚合數據。每個週期包含主動買入、主動賣出，以及從本次返回第一條起累加的買賣差。

<DesignTheme />

以下 API 等級可以調用本接口：<PlanBadge plan="Startup" /> <PlanBadge plan="Standard" /> <PlanBadge plan="Professional" /> <PlanBadge plan="Enterprise" />

<Tag variant="freq" text="即時" />

<ApiParamsSlot />

## 響應數據

`data` 為陣列，每個元素是一個週期，`time` 為週期的開始時間（毫秒）。`agg_taker_buy_vol`、`agg_taker_sell_vol` 是所選交易所合計的現貨主動買入、主動賣出；`cum_vol_delta` 是從本次返回的第一條開始，逐週期累加「買入 − 賣出」得到的累計值。數值單位由 `unit` 決定。

> 📘 累計值從本次返回的第一條開始計算
>
> `cum_vol_delta` 不是從幣種上線起算的累計值。第一條的 `cum_vol_delta` 等於該週期的 `agg_taker_buy_vol − agg_taker_sell_vol`，之後每條在前一條基礎上累加。時間範圍不同，同一時間點的 `cum_vol_delta` 也不同，分段獲取時請勿直接拼接，見下方常見問題。

`200` · application/json · 響應範例見右側面板。

| 欄位                          | 類型              | 必返 | 說明                                             |
| :-------------------------- | :-------------- | :- | :--------------------------------------------- |
| `code`                      | string          | 是  | 業務狀態碼，`"0"` 表示成功                               |
| `msg`                       | string          | 否  | 結果說明                                           |
| `data`                      | array of object | 是  | 週期陣列，每個元素是一個週期                                 |
| `data[].time`               | integer（int64）  | 是  | 週期開始時間，13 位毫秒時間戳（UTC）                          |
| `data[].agg_taker_buy_vol`  | number          | 是  | 所選交易所合計的現貨主動買入；`unit=usd` 時為美元，`coin` 時為幣的數量   |
| `data[].agg_taker_sell_vol` | number          | 是  | 所選交易所合計的現貨主動賣出；單位同上                            |
| `data[].cum_vol_delta`      | number          | 是  | 累計成交量差值：從本次返回的第一條起，逐週期累加（主動買入 − 主動賣出）；單位同上，可為負 |

某個週期缺少主動買入或主動賣出數據時按 0 計算，所以數值為 0 不一定表示該週期沒有成交。

## API 等級

本接口的開放範圍和可用週期見下表。 價格見[API 等級](https://www.coinglass.com/zh-TW/pricing)。

| API 等級 | 能否調用    | 可用週期（`interval`）                               |
| :----- | :------ | :--------------------------------------------- |
| 業餘     | ❌ 不可以   | —                                              |
| 創業     | ✅ 可以    | `30m`、`1h`、`2h`、`4h`、`6h`、`8h`、`12h`、`1d`、`1w` |
| 標準     | ✅ 可以    | 本接口支援的全部週期，最短 `1m`                             |
| 專業     | ✅ 可以    | 本接口支援的全部週期，最短 `1m`                             |
| 企業     | 按實際授權約定 | 按實際授權約定                                        |

可選週期以本頁 `interval` 參數列出的值為準，不能傳入任意大於最短週期的值。這些限制針對採樣或計算週期，不代表數據更新頻率或可查詢的歷史長度。

## 用 AI 調用本接口

選一個任務，點「在 ChatGPT 中開啟」或「在 Claude 中開啟」，AI 會先讀取本頁說明，再直接給出結果；也可以點「複製」，把完整提示詞貼上到你常用的 AI 工具裡。

<AskAi
  prompts={[
    { label: "對比現貨和合約 CVD", desc: "讓 AI 寫代碼，把 BTC 現貨和合約的聚合 CVD 畫在同一張圖裡。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/spot-aggregated-cvd-history.md 和 https://docs.coinglass.com/v4.0-zhtw/reference/futures-aggregated-cvd-history.md ，用 Python 獲取 BTC 最近 7 天的小時級現貨聚合 CVD 和合約聚合 CVD（interval=1h，exchange_list=Binance,OKX,Bybit，unit=usd），按 time 對齊後畫在同一張折線圖裡，觀察兩者是否同向。API Key 從環境變數 COINGLASS_API_KEY 讀取。" },
    { label: "分段下載並續算", desc: "讓 AI 寫代碼，分段下載 90 天現貨聚合 CVD，並正確續算累計值。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/spot-aggregated-cvd-history.md 和 https://docs.coinglass.com/v4.0-zhtw/reference/timestamps-and-pagination.md ，用 Python 寫一個函式：分段獲取 BTC 最近 90 天的 15 分鐘現貨聚合 CVD（interval=15m，exchange_list=Binance,OKX,Bybit），按 time 去重排序，不要直接拼接各段的 cum_vol_delta，而是用 agg_taker_buy_vol − agg_taker_sell_vol 從頭重新累加，最後畫出完整的 CVD 曲線。API Key 從環境變數 COINGLASS_API_KEY 讀取。" },
    { label: "看懂這個接口", desc: "讓 AI 用白話解釋現貨聚合 CVD 和返回欄位。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/spot-aggregated-cvd-history.md ，用通俗的話告訴我：這個接口返回的每個欄位是什麼意思，cum_vol_delta 從哪裡開始累計，exchange_list 和 unit 怎麼填，以及和單個交易對的現貨 CVD 有什麼區別。" },
  ]}
/>

想讓 AI 直接查詢即時數據、不寫代碼？在 Claude、Cursor 中接入 [CoinGlass MCP](https://docs.coinglass.com/v4.0-zhtw/reference/mcp-service) 後直接用中文提問，例如「BTC 現貨市場最近 7 天的聚合 CVD 是上升還是下降？」。

## 應用場景

<ChoiceCards columns={2}>

| 場景 | 說明 |
| :-- | :-- |
| 觀察現貨整體買賣累積 | 彙總多個交易所後，CVD 更能代表整個現貨市場主動買賣的累積方向。 |
| 發現價格背離 | 價格新高而現貨聚合 CVD 走低，說明現貨主動賣出在增加，上漲可能乏力。 |
| 自選交易所範圍 | 只統計你關心的交易所，例如只看 Binance、OKX、Bybit 三個平台。 |
| 與合約對比 | 與[合約聚合累計成交量差值（CVD）](https://docs.coinglass.com/v4.0-zhtw/reference/futures-aggregated-cvd-history)對比，判斷行情由現貨還是合約主導。 |

</ChoiceCards>

## 相關接口

| 接口                                                                                                 | 區別                          |
| :------------------------------------------------------------------------------------------------- | :-------------------------- |
| [現貨累計成交量差值（CVD）](https://docs.coinglass.com/v4.0-zhtw/reference/spot-cvd-history)                  | 單個交易所、單個現貨交易對的 CVD          |
| [現貨幣種主動買賣歷史](https://docs.coinglass.com/v4.0-zhtw/reference/spot-aggregated-taker-buysell-history) | 彙總方式相同，不帶累計值，只返回美元          |
| [合約聚合累計成交量差值（CVD）](https://docs.coinglass.com/v4.0-zhtw/reference/futures-aggregated-cvd-history)  | 合約市場的同類數據                   |
| [現貨支援的交易所和交易對](https://docs.coinglass.com/v4.0-zhtw/reference/spot-suported-exchange-pairs)        | 查詢 `exchange_list` 可填的交易所名稱 |

## 常見問題

<Accordion title="分段獲取時，cum_vol_delta 可以直接拼接嗎？" icon="fa-circle-question">
  不能。`cum_vol_delta` 從本次返回的第一條開始累加，每次請求都會從各自的第一條重新起算，時間範圍不同，同一時間點的 `cum_vol_delta` 也不同。分段下載長歷史時，請按 `time` 去重並排序，保存每個週期的 `agg_taker_buy_vol` 和 `agg_taker_sell_vol`，自己按時間順序累加「買入 − 賣出」續算累計值。分段方法見[時間戳與分頁](https://docs.coinglass.com/v4.0-zhtw/reference/timestamps-and-pagination)。
</Accordion>

<Accordion title="unit 怎麼填？" icon="fa-circle-question">
  `usd` 返回美元金額（預設），`coin` 返回幣的數量，大小寫均可。注意傳 `usd` 以外的任何值都會按幣的數量返回，`cum_vol_delta` 的單位與 `unit` 相同。
</Accordion>

<Accordion title="exchange_list 寫錯了會報錯嗎？" icon="fa-circle-question">
  不一定。寫錯或不支援的交易所名稱可能被直接忽略，返回的只是其餘交易所的合計。建議先用「[現貨支援的交易所和交易對](https://docs.coinglass.com/v4.0-zhtw/reference/spot-suported-exchange-pairs)」接口核對名稱。
</Accordion>

<Accordion title="聚合包含哪些交易對？" icon="fa-circle-question">
  只彙總本接口已接入、且有數據的現貨市場，結果不一定包含交易所的全部現貨交易對。例如 `exchange_list=Binance`、`symbol=BTC`、`interval=1h` 時，返回的主動買賣數值與 Binance `BTCUSDT` 交易對完全相同。需要某一個交易對的數據時，請改用對應的交易對接口。
</Accordion>

## 深入了解：現貨聚合 CVD

### 聚合 CVD 和單交易對 CVD 有什麼不同？

聚合 CVD 把一個幣種在所選交易所的現貨交易對合在一起計算，反映整個現貨市場；單交易對 CVD 只反映某個平台某個交易對的訂單流。

### CVD 用美元還是幣數量看更好？

美元金額會隨價格變化，價格高時同樣的成交量對應更大的金額；幣的數量更能反映實際成交規模。比較不同時期時，幣的數量更穩定。

### 為什麼要對比現貨和合約的 CVD？

合約 CVD 上升而現貨 CVD 不動，說明行情主要由槓桿資金推動；兩者同向上升，上漲的基礎通常更紮實。合約數據見「[合約聚合累計成交量差值（CVD）](https://docs.coinglass.com/v4.0-zhtw/reference/futures-aggregated-cvd-history)」。

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "CoinGlass API",
    "version": "4.0.0"
  },
  "servers": [
    {
      "url": "https://open-api-v4.coinglass.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "CG-API-KEY"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/api/spot/aggregated-cvd/history": {
      "get": {
        "description": "",
        "operationId": "get_apispotaggregated-cvdhistory",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": {
                      "code": "0",
                      "data": [
                        {
                          "time": 1792458000000,
                          "agg_taker_buy_vol": 23461495.6515,
                          "agg_taker_sell_vol": 24062727.834,
                          "cum_vol_delta": -601232.1825
                        },
                        {
                          "time": 1792461600000,
                          "agg_taker_buy_vol": 15050379.4852,
                          "agg_taker_sell_vol": 13239579.7582,
                          "cum_vol_delta": 1209567.5445
                        }
                      ]
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "業務狀態碼，\"0\" 表示成功",
                      "example": "0"
                    },
                    "msg": {
                      "type": "string",
                      "description": "結果說明",
                      "example": "success"
                    },
                    "data": {
                      "type": "array",
                      "description": "週期陣列，每個元素是一個週期",
                      "items": {
                        "type": "object",
                        "properties": {
                          "time": {
                            "type": "integer",
                            "description": "週期開始時間，13 位毫秒時間戳（UTC）",
                            "format": "int64"
                          },
                          "agg_taker_buy_vol": {
                            "type": "number",
                            "description": "所選交易所合計的現貨主動買入；unit=usd 時為美元，coin 時為幣的數量"
                          },
                          "agg_taker_sell_vol": {
                            "type": "number",
                            "description": "所選交易所合計的現貨主動賣出；單位同上"
                          },
                          "cum_vol_delta": {
                            "type": "number",
                            "description": "累計成交量差值：從本次返回的第一條起，逐週期累加（主動買入 − 主動賣出）；單位同上，可為負"
                          }
                        },
                        "required": [
                          "time",
                          "agg_taker_buy_vol",
                          "agg_taker_sell_vol",
                          "cum_vol_delta"
                        ]
                      }
                    }
                  },
                  "required": [
                    "code",
                    "data"
                  ]
                }
              }
            }
          }
        },
        "parameters": [
          {
            "in": "query",
            "name": "exchange_list",
            "schema": {
              "type": "string",
              "default": "Binance"
            },
            "description": "參與彙總的現貨交易所，必填，多個用英文逗號分隔，例如 `Binance,OKX,Bybit`。寫錯或不支援的名稱可能被直接忽略、不會報錯，可查詢的交易所見「[現貨支援的交易所和交易對](https://docs.coinglass.com/v4.0-zhtw/reference/spot-suported-exchange-pairs)」接口。",
            "required": true,
            "example": "Binance"
          },
          {
            "in": "query",
            "name": "symbol",
            "schema": {
              "type": "string",
              "default": "BTC"
            },
            "description": "幣種代碼，必填，例如 `BTC`、`ETH`、`SOL`。可查詢的幣種見「[現貨支援的幣種](https://docs.coinglass.com/v4.0-zhtw/reference/spot-supported-coins)」接口。",
            "required": true,
            "example": "BTC"
          },
          {
            "in": "query",
            "name": "interval",
            "schema": {
              "type": "string",
              "default": "1d"
            },
            "description": "數據週期，必填，例如 `1h`。可選 `1m`、`3m`、`5m`、`15m`、`30m`、`1h`、`2h`、`4h`、`6h`、`8h`、`12h`、`1d`、`1w`。\n\n週期權限：業餘不開放本接口；創業最短 `30m`，標準和專業最短 `1m`；企業按實際授權約定。僅限本接口支援的週期。",
            "required": true,
            "example": "1h"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "default": 1000,
              "maximum": 1000
            },
            "description": "返回的數據條數，預設 `1000`，可傳 1～1000。同時傳 `start_time` 和 `end_time` 時，返回條數由時間範圍決定，不一定等於 `limit`。",
            "required": false
          },
          {
            "in": "query",
            "name": "start_time",
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "開始時間，毫秒時間戳（UTC），例如 `1790812800000`（2026-10-01 00:00 UTC）。返回數據的 `time` 滿足 `start_time ≤ time < end_time`：包含開始時間，不包含結束時間。",
            "required": false
          },
          {
            "in": "query",
            "name": "end_time",
            "schema": {
              "type": "integer",
              "format": "int64"
            },
            "description": "結束時間，毫秒時間戳（UTC），例如 `1792022400000`（2026-10-15 00:00 UTC）。返回數據的 `time` 滿足 `start_time ≤ time < end_time`：包含開始時間，不包含結束時間。不傳起止時間時，以當前時間為終點，按 `interval × limit` 向前推算；結束時間晚於當前時間時按當前時間處理。",
            "required": false
          },
          {
            "in": "query",
            "name": "unit",
            "schema": {
              "type": "string",
              "default": "usd"
            },
            "description": "返回數值的單位：`usd` 為美元（預設），`coin` 為幣的數量。大小寫均可；傳 `usd` 以外的值都按幣的數量返回。",
            "required": false
          }
        ]
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```