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.
| Item | Details |
|---|---|
| Base URL | https://open-api-v4.coinglass.com |
| Authentication | CG-API-KEY header |
| Test endpoint | GET /api/futures/supported-coins |
| Success check | HTTP status code is 200 and code is "0" |
| Common errors | 400: 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
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 safeYour 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.
| Parameter | Required | Example | Description |
|---|---|---|---|
symbol | Yes | BTC | Coin |
interval | Yes | 1d | Candle 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 |
limit | No | 7 | Number 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.
| Case | Symptom | How to Handle |
|---|---|---|
| Missing or invalid key | code 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 requests | Return code 429 | Wait and retry, doubling the wait time each time; if you exceed the limit over a long period, consider upgrading your API plan |
| Business failure | code 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
- Authentication: Get and manage your CoinGlass API Key
- API Plans and Permissions: Crypto API pricing and request limits
- Error Codes and Rate Limits: API return codes and rate limiting
- CoinGlass MCP (Beta): Query crypto data in AI tools
