---
updatedAt: 2026-10-29T07:00:11.000Z
agentTools:
  projectIndex: https://docs.coinglass.com/v4.0-zhtw/llms.txt
---

# 帳號等級查詢

查詢當前 API Key 的訂閱資訊，包括當前 API 等級、到期時間以及是否已過期。適合在程式啟動時自檢，或在訂閱到期前提醒續費。

<DesignTheme />

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

<ApiParamsSlot />

## 響應數據

本接口沒有請求參數，查詢的是請求標頭 `CG-API-KEY` 中這個 API Key 本身的訂閱資訊。`data` 為物件，包含當前 API 等級、到期時間，以及是否已過期。

> 🚧 API Key 只放在服務端
>
> 本接口返回的是你的帳戶訂閱資訊。請在服務端調用，從環境變數讀取 API Key，不要把密鑰放進前端頁面、日誌或公開倉庫。懷疑洩露時，請在 [API Key 管理頁面](https://www.coinglass.com/zh-TW/account)重置。詳見[身份驗證](https://docs.coinglass.com/v4.0-zhtw/reference/authentication)。

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

| 欄位                 | 類型             | 必返 | 說明                                                                               |
| :----------------- | :------------- | :- | :------------------------------------------------------------------------------- |
| `code`             | string         | 是  | 業務狀態碼，`"0"` 表示成功                                                                 |
| `msg`              | string         | 否  | 結果說明，例如認證失敗時的錯誤原因；成功時可能不返回                                                       |
| `data`             | object         | 是  | 當前 API Key 的訂閱資訊                                                                 |
| `data.level`       | string         | 是  | 當前 API 等級的英文名稱，取值 `HOBBYIST`（業餘）、`STARTUP`（創業）、`STANDARD`（標準）、`PROFESSIONAL`（專業） |
| `data.expire_time` | integer（int64） | 是  | 訂閱到期時間，毫秒時間戳（UTC）                                                                |
| `data.expired`     | boolean        | 是  | 是否已過期。按請求時的當前時間是否晚於 `expire_time` 計算：晚於時為 `true`，否則為 `false`                     |

API Key 缺失或無效時，HTTP 狀態碼仍為 200，需要看返回 JSON 中的 `code`：缺少 `CG-API-KEY` 請求標頭時返回 `{"code": "401", "msg": "API key missing."}`；API Key 無效時返回 `{"code": "400", "msg": "Invalid API key provided"}`。詳見[身份驗證](https://docs.coinglass.com/v4.0-zhtw/reference/authentication)和[錯誤碼與頻率限制](https://docs.coinglass.com/v4.0-zhtw/reference/responses-error-codes)。

## API 等級

**所有 API 等級都可以調用本接口**。本接口不按 API 等級限制，會校驗請求標頭中的 API Key 及其訂閱資訊。各等級價格見 [API 等級](https://www.coinglass.com/zh-TW/pricing)。

| API 等級 | 能否調用 |
| :----- | :--- |
| 業餘     | ✅ 可以 |
| 創業     | ✅ 可以 |
| 標準     | ✅ 可以 |
| 專業     | ✅ 可以 |
| 企業     | ✅ 可以 |

各等級可調用的接口、每分鐘請求上限和歷史數據範圍，見[API 等級與權限](https://docs.coinglass.com/v4.0-zhtw/reference/plans-and-permissions)。

## 用 AI 調用本接口

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

<AskAi
  prompts={[
    { label: "到期提醒腳本", desc: "讓 AI 寫一個 Python 腳本，檢查訂閱是否快到期並提醒。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/user-account-subscription.md ，用 Python 寫一個腳本：調用帳號等級查詢接口，API Key 從環境變數 COINGLASS_API_KEY 讀取，打印當前 level、到期時間（expire_time 是毫秒，轉為 UTC 日期）和剩餘天數；expired 為 true 或剩餘不到 7 天時打印提醒。code 不是 \"0\" 時打印 code 和 msg。不要在輸出中打印 API Key。" },
    { label: "服務啟動自檢", desc: "讓 AI 寫一個 Node.js 函式，在服務啟動時檢查 API Key 是否有效。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/user-account-subscription.md ，用 Node.js 寫一個函式：服務啟動時調用一次帳號等級查詢接口，API Key 從環境變數 COINGLASS_API_KEY 讀取；code 為 \"0\" 且 expired 為 false 時返回 level 和到期時間，code 為 \"401\" 或 \"400\" 時拋出清楚的錯誤（缺少或無效的 API Key）。同時讀取響應頭 API-KEY-MAX-LIMIT 和 API-KEY-USE-LIMIT 並打印。" },
    { label: "看懂這個接口", desc: "讓 AI 用白話解釋返回欄位，以及認證失敗時的返回。", text: "請閱讀 https://docs.coinglass.com/v4.0-zhtw/reference/user-account-subscription.md ，用通俗的話告訴我：這個接口返回的 level、expire_time、expired 分別是什麼意思，expire_time 怎麼轉換成日期，以及 API Key 缺失或無效時會返回什麼。" },
  ]}
/>

本接口透過 REST API 提供數據，可使用上方提示詞讓 AI 編寫調用代碼。MCP 可調用的工具見 [CoinGlass MCP](https://docs.coinglass.com/v4.0-zhtw/reference/mcp-service)。

## 應用場景

<ChoiceCards columns={2}>

| 場景 | 說明 |
| :-- | :-- |
| 啟動時自檢 | 服務啟動時調用一次，確認 API Key 有效、等級符合預期，避免上線後才發現無權限。 |
| 到期提醒 | 根據 `expire_time` 計算剩餘天數，在訂閱到期前提醒續費。 |
| 按等級調整功能 | 根據 `level` 決定啟用哪些功能或調整請求頻率，各等級的差異見[API 等級與權限](https://docs.coinglass.com/v4.0-zhtw/reference/plans-and-permissions)。 |
| 排查無權限問題 | 調用其他接口提示無權限或沒有數據時，先確認當前等級和是否已過期。 |

</ChoiceCards>

## 相關接口

| 接口                                                                                | 區別                         |
| :-------------------------------------------------------------------------------- | :------------------------- |
| [身份驗證](https://docs.coinglass.com/v4.0-zhtw/reference/authentication)             | `CG-API-KEY` 請求標頭與認證失敗的返回碼 |
| [API 等級與權限](https://docs.coinglass.com/v4.0-zhtw/reference/plans-and-permissions) | 各等級可用接口、每分鐘請求上限與歷史數據範圍     |
| [錯誤碼與頻率限制](https://docs.coinglass.com/v4.0-zhtw/reference/responses-error-codes)  | 返回碼說明與 429 限流處理            |
| [快速開始](https://docs.coinglass.com/v4.0-zhtw/reference/quickstart)                 | 從獲取 API Key 到發出第一個請求       |

## 常見問題

<Accordion title="怎麼計算還剩幾天到期？" icon="fa-circle-question">
  用 `expire_time` 減去當前時間的毫秒時間戳，再除以 86,400,000，就是剩餘天數。`expired` 按請求時的當前時間是否晚於 `expire_time` 計算，為 `true` 表示已經過期。
</Accordion>

<Accordion title="expire_time 是秒還是毫秒？" icon="fa-circle-question">
  毫秒時間戳（UTC）。例如 `1805943491000` 對應 2027-03-25 02:58:11 UTC。
</Accordion>

<Accordion title="為什麼返回 401 或 400？" icon="fa-circle-question">
  缺少 `CG-API-KEY` 請求標頭時返回 `code` 為 `"401"`（`API key missing.`）；API Key 無效時返回 `"400"`（`Invalid API key provided`）。兩種情況 HTTP 狀態碼都是 200，排查方法見[身份驗證](https://docs.coinglass.com/v4.0-zhtw/reference/authentication)。
</Accordion>

<Accordion title="升級 API 等級後需要更換 API Key 嗎？" icon="fa-circle-question">
  不需要。升級後原 API Key 可以繼續使用，新 API 等級的權限立即生效。升級後可以再調用本接口，確認 `level` 已經更新。
</Accordion>

## 深入了解：CoinGlass API 等級與 API Key

### 如何查看 API Key 剩餘的請求額度？

響應頭中會返回 `API-KEY-MAX-LIMIT`（每分鐘最大請求次數）和 `API-KEY-USE-LIMIT`（當前時間段內已使用的次數），兩者相減就是剩餘額度。詳見[身份驗證](https://docs.coinglass.com/v4.0-zhtw/reference/authentication)。

### 不同 API 等級有什麼區別？

等級決定可以調用哪些接口、每分鐘可以請求多少次（業餘、創業、標準、專業分別為 30、80、300、1,200 次，企業定製），以及能查詢多長的歷史數據。詳見[API 等級與權限](https://docs.coinglass.com/v4.0-zhtw/reference/plans-and-permissions)。

### 如何安全地保管 API Key？

把密鑰存放在環境變數或密鑰管理服務中，只在服務端使用；不要寫進前端代碼、日誌或代碼倉庫，也不要分享給第三方。懷疑洩露時，立即在 API Key 管理頁面重置，並更新所有使用它的服務。

# 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/user/account/subscription": {
      "get": {
        "description": "",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": {
                      "code": "0",
                      "data": {
                        "level": "PROFESSIONAL",
                        "expire_time": 1805943491000,
                        "expired": false
                      }
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "業務狀態碼，\"0\" 表示成功",
                      "example": "0"
                    },
                    "msg": {
                      "type": "string",
                      "description": "結果說明，例如認證失敗時的錯誤原因；成功時可能不返回",
                      "example": "success"
                    },
                    "data": {
                      "type": "object",
                      "description": "當前 API Key 的訂閱資訊",
                      "properties": {
                        "level": {
                          "type": "string",
                          "description": "當前 API 等級的英文名稱，取值 HOBBYIST（業餘）、STARTUP（創業）、STANDARD（標準）、PROFESSIONAL（專業）"
                        },
                        "expire_time": {
                          "type": "integer",
                          "description": "訂閱到期時間，毫秒時間戳（UTC）",
                          "format": "int64"
                        },
                        "expired": {
                          "type": "boolean",
                          "description": "是否已過期。按請求時的當前時間是否晚於 expire_time 計算：晚於時為 true，否則為 false"
                        }
                      },
                      "required": [
                        "level",
                        "expire_time",
                        "expired"
                      ]
                    }
                  },
                  "required": [
                    "code",
                    "data"
                  ]
                }
              }
            }
          }
        },
        "parameters": [],
        "operationId": "get_api-user-account-subscription"
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```