Quickstart

CoinGlass API tutorial: going from getting an API Key to your first set of Bitcoin open interest data takes about 5 minutes. This page provides ready-to-run cURL, Python and JavaScript examples and explains how to handle errors and rate limiting.

Key Facts
ItemDetails
Base URLhttps://open-api-v4.coinglass.com
AuthenticationCG-API-KEY header
Test endpointGET /api/futures/supported-coins
Success checkHTTP status code is 200 and code is "0"
Common errors400: invalid parameters or API key; 401: key, endpoint permission or plan issue (check msg); 429: rate limit. Check both HTTP status and business code

Prerequisites

Account
A CoinGlass account subscribed to an API plan
Environment
A terminal (cURL), Python 3, or Node.js 18 and above
Estimated time
5 minutes

Step 1: Get an API Key

Log in to your CoinGlass account and find your API Key in the user center. If you don't have an account yet, sign up first; if you haven't subscribed to the API yet, first choose a suitable API plan in API Plans and Permissions.

⚠️

Keep your API Key safe

Your API Key is equivalent to your account password. Do not put it in web frontend code, app installation packages or public code repositories; we recommend storing it in environment variables on your server.

Step 2: Confirm the Connection

First call the Supported Coins endpoint to confirm that your key works. Replace YOUR_API_KEY with your key; a returned code of "0" means the connection succeeded.

curl --request GET \
  --url 'https://open-api-v4.coinglass.com/api/futures/supported-coins' \
  --header 'accept: application/json' \
  --header 'CG-API-KEY: YOUR_API_KEY'
import requests

resp = requests.get(
    "https://open-api-v4.coinglass.com/api/futures/supported-coins",
    headers={"CG-API-KEY": "YOUR_API_KEY"},
    timeout=10,
)
print(resp.status_code, resp.json()["code"])
const res = await fetch(
  "https://open-api-v4.coinglass.com/api/futures/supported-coins",
  { headers: { "CG-API-KEY": "YOUR_API_KEY" } }
);
const body = await res.json();
console.log(res.status, body.code);

Step 3: Query Bitcoin Open Interest

The example below calls the Aggregated Open Interest OHLC History endpoint to get Bitcoin's market-wide open interest for the last 7 days. The example reads the key from the environment variable COINGLASS_API_KEY.

ParameterRequiredExampleDescription
symbolYesBTCCoin
intervalYes1dCandle interval; available values: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 1w. For the range available on each API plan, see Intervals
limitNo7Number of records to return; default 1000, accepts 1–1000
import os
import requests

API_KEY = os.environ["COINGLASS_API_KEY"]
BASE_URL = "https://open-api-v4.coinglass.com"

resp = requests.get(
    BASE_URL + "/api/futures/open-interest/aggregated-history",
    headers={"CG-API-KEY": API_KEY},
    params={"symbol": "BTC", "interval": "1d", "limit": 7},
    timeout=10,
)
body = resp.json()
for candle in body["data"]:
    print(candle["time"], candle["close"])
const params = new URLSearchParams({ symbol: "BTC", interval: "1d", limit: "7" });
const res = await fetch(
  "https://open-api-v4.coinglass.com/api/futures/open-interest/aggregated-history?" + params,
  { headers: { "CG-API-KEY": process.env.COINGLASS_API_KEY } }
);
const body = await res.json();
for (const candle of body.data) {
  console.log(candle.time, candle.close);
}

The response structure is shown below. time is a timestamp in milliseconds; open, high, low and close are the open interest values for the interval and are mostly returned as strings; in the most recent candle, which has not closed yet, some fields may be returned as numbers, so convert them all to numbers before calculating.

{
  "code": "0",
  "data": [
    {
      "time": 1760313600000,
      "open": "<open interest at the start of the interval>",
      "high": "<highest open interest within the interval>",
      "low": "<lowest open interest within the interval>",
      "close": "<open interest at the end of the interval>"
    }
  ]
}

Step 4: Handle Errors and Rate Limiting

Before going live, handle at least the three cases below. Note: the HTTP status code for these errors is usually still 200, so check the code in the JSON. For the full list of return codes, see Error Codes and Rate Limits.

CaseSymptomHow to Handle
Missing or invalid keycode is "401" (missing) or "400" (invalid)Check that the header name is CG-API-KEY and that the key was copied in full
Too many requestsReturn code 429Wait and retry, doubling the wait time each time; if you exceed the limit over a long period, consider upgrading your API plan
Business failurecode is not "0"Read the msg field to troubleshoot; common causes are invalid parameters or a request beyond what your API plan covers

FAQ

Can I call the CoinGlass API directly from a web frontend?

Not recommended. Sending requests from the browser exposes your API Key to every visitor. Call the CoinGlass API from your own server instead, then return the results to the frontend.

Why does the response contain fewer records than limit?

The length of history you can query is determined by both your API plan and the interval; the part outside that range is not returned. For the historical data range of each API plan, see API Plans and Permissions.

Why do I get a 429?

Your requests per minute exceeded your API plan's limit. The limits are 30, 80, 300 and 1,200 requests per minute for Hobbyist, Startup, Standard and Professional respectively; Enterprise can be customized.

CoinGlass API Tutorial: More Languages and Tools

Call the API from JavaScript (Node.js)

Node.js 18 and above has built-in fetch, so you can request the CoinGlass API directly. Store your API Key in the environment variable COINGLASS_API_KEY and send it in the CG-API-KEY header; for the code, see the JavaScript example in Step 3 above.

Get Crypto Data in Google Sheets

In Google Apps Script, request the endpoints with UrlFetchApp and add CG-API-KEY to the request headers to write data such as Bitcoin open interest and funding rates into a spreadsheet; combine this with a time-driven trigger to build a market sheet that refreshes automatically.

Recommended First Endpoints for Beginners

Supported Coins, Aggregated Open Interest OHLC History, Funding Rate OHLC History, Coin Liquidation History and Crypto Fear & Greed Index cover the starting points of most crypto market analysis.

Related Docs