CoinNudge research data API documentation

Free public Research access

Every published Research article is free to read. Eligible live Research pages also expose the current source-backed dataset shown on that page as no-key JSON and CSV through /api/research/live/PAGE_KEY and /api/research/live/PAGE_KEY.csv.

Fair-use limit: 60 requests per minute per IP, shared across all public Research JSON and CSV endpoints. Follow each page's published refresh interval instead of polling continuously. Free access does not include a bulk feed of article text, unpublished or internal material, historical snapshots, the internal archive, or paid Market Events v1 releases.

Free API key: authentication and request URLs

Every signed-in account can create one free key and read the current datasets behind CoinNudge Research pages at up to 60 requests per minute. Paid data plans additionally unlock Market Events history, filtered rows and complete JSON, CSV and Parquet releases.

1. Create and save your key. Sign in, open API Keys, enter a label, and click Create API key. A paid plan is not required for the free Research scope. Copy the complete key beginning with cnd_; the shortened prefix in the table is not usable. The secret is shown once. If lost, revoke it and create a replacement.
2. Send it as a request header. Base URL: https://coinnudge.site/api/data/v1. Every endpoint below uses GET and the header Authorization: Bearer YOUR_API_KEY. Replace YOUR_API_KEY with your full key; do not include quotation marks around the key in the header value. Opening the URL in a browser tab does not attach this header.
3. Choose the correct scope. Free Research: request /research/catalog, copy a dataset id, then request /research/DATASET_ID or /research/DATASET_ID/csv. Paid Market Events: start with /catalog and /releases?limit=30.
4. Preserve the dataset context. A Research response is a current snapshot and declares its observation time, calculation version and limitations. A paid release ID is immutable; keep the same ID while paging and save it with your analysis.

Security: use the key in your own backend or local notebook, never in a public website’s JavaScript, URL, shared notebook or chat message. Giving a key to an agent lets it consume your account quota. These endpoints only read public Research datasets or data covered by your paid entitlement; they do not place trades or expose internal logs and customer records.

Free Research API endpoints

All three endpoints use GET. Send Authorization: Bearer YOUR_API_KEY on every request. There is no request body and the key must never be placed in the query string.

Free Research API fields

The API has a stable common envelope and dataset-specific measurements. Do not assume that a funding-rate row has the same columns as market breadth or liquidation data. Use the catalog to select an ID, then inspect that dataset's JSON keys or CSV header before binding fields in production.

Example row fields: market-breadth

For another dataset, call its JSON URL and inspect items[0]; for CSV, the first line is the exact current row schema. Fields may be absent or null when the source did not provide a valid observation. Never convert missing values to zero. JSON also contains page-level summaries and provenance that CSV cannot represent, so retain the JSON response when audit context matters.

Paid Market Events API endpoints

Paid Market Events filters

The parameters below apply to /rows/RELEASE_ID and require an active Researcher or Research Desk data plan. Current Research endpoints use the stable dataset ID returned by /research/catalog and do not accept these release-row filters.

items contains this page’s records; total counts all records matching your filters. If has_more is true, request next_offset with the same release ID and filters. An empty items list with total 0 is a valid result, not an API failure. No event may have qualified for that coin on that day.

Times are Unix seconds in UTC. Inspect feature_status, feature_pit_eligible and window status fields before analysis. Retrospective context was obtained later; pending or gap outcomes are missing, not zero returns. Future returns must not be used as predictor inputs. Read real rows and field definitions →

Copy a working example

The first example works with a free account and shows all three Research API requests. The paid Python example needs no third-party package and automatically selects an immutable Market Events release, queries matching BTC events and optionally verifies a full CSV download.

# Available to every signed-in CoinNudge account.
read -r -s -p "CoinNudge API key: " COINNUDGE_DATA_KEY
echo

# List all current Research datasets.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  https://coinnudge.site/api/data/v1/research/catalog

# Read one current dataset as JSON.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  https://coinnudge.site/api/data/v1/research/market-breadth

# Download the same current dataset as CSV.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  https://coinnudge.site/api/data/v1/research/market-breadth/csv \
  --output coinnudge-market-breadth.csv
unset COINNUDGE_DATA_KEY

# Python 3: standard library only. Works on Windows, macOS and Linux.
# Save as coinnudge_example.py, then run: python coinnudge_example.py
import getpass
import hashlib
import json
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

BASE = "https://coinnudge.site/api/data/v1"
key = getpass.getpass("CoinNudge API key (hidden): ").strip()

def fetch(path):
    request = Request(BASE + path, headers={"Authorization": "Bearer " + key})
    try:
        with urlopen(request, timeout=30) as response:
            return response.read()
    except HTTPError as error:
        detail = error.read().decode("utf-8", errors="replace")
        raise SystemExit(f"HTTP {error.code}: {detail}") from None

def get_json(path):
    return json.loads(fetch(path))

catalog = get_json("/catalog")
print("Dataset coverage:", catalog["datasets"])
releases = get_json("/releases?limit=30")["items"]
if not releases:
    raise SystemExit("No published releases yet; try again later.")

# Latest available daily release; change this selection for another day.
release = releases[0]
release_id = release["id"]
print("Selected day:", release["day"], "version:", release["version"])

# Query BTC events. Keep the SAME release ID on every page.
offset = 0
rows = []
while True:
    query = urlencode({"symbol": "BTCUSDT", "sample_type": "event",
                       "limit": 500, "offset": offset})
    page = get_json(f"/rows/{release_id}?{query}")
    rows.extend(page["items"])
    if not page["has_more"]:
        break
    offset = page["next_offset"]
    if not isinstance(offset, int) or offset > 100000:
        raise SystemExit("Use a full file download for this larger release.")
print("Matching BTC event rows:", len(rows))

# Save filtered JSON without overwriting an existing file.
filtered = Path(f"btc-events-{release_id}.json")
if not filtered.exists():
    with filtered.open("x", encoding="utf-8") as file:
        json.dump(rows, file, indent=2)

# Optional full daily CSV: includes ALL six markets and event/control rows.
if input("Also download the full daily CSV? [y/N] ").lower() == "y":
    content = fetch(f"/download/{release_id}/csv")
    expected = release["files"]["csv"]["sha256"]
    if hashlib.sha256(content).hexdigest() != expected:
        raise SystemExit("Checksum mismatch; do not use this file.")
    output = Path(f"coinnudge-{release_id}.csv")
    if not output.exists():
        with output.open("xb") as file:
            file.write(content)
    print("Verified CSV:", output)

# Inspect field definitions before analysis. Never replace null with 0.
schema = get_json("/schema")
print("Field count:", len(schema["fields"]))

# Bash on macOS / Linux. If using zsh, run bash first.
# Enter your key without displaying it.
read -r -s -p "CoinNudge API key: " COINNUDGE_DATA_KEY
echo
export COINNUDGE_DATA_KEY

# 1. Check access and current coverage.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  https://coinnudge.site/api/data/v1/catalog

# 2. List daily releases. Copy the full id for the day you need.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  "https://coinnudge.site/api/data/v1/releases?limit=30"

# 3. Replace this placeholder with that full 64-character id.
RELEASE_ID="REPLACE_WITH_RELEASE_ID"
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  "https://coinnudge.site/api/data/v1/rows/$RELEASE_ID?symbol=BTCUSDT&sample_type=event&limit=100&offset=0"

# 4. Download the ENTIRE daily release, not just the BTC filter above.
curl --fail-with-body -H "Authorization: Bearer $COINNUDGE_DATA_KEY" \
  "https://coinnudge.site/api/data/v1/download/$RELEASE_ID/csv" \
  --output "coinnudge-$RELEASE_ID.csv"
unset COINNUDGE_DATA_KEY

Limits, refreshes and common errors

Free: 1 key and 60 requests/minute for current Research datasets. Researcher: 1 key, 60 requests/minute and 1 GiB/day. Research Desk: 5 keys, 300 requests/minute and 5 GiB/day. Limits are account-wide, not per key. Paid byte budgets use UTC calendar days. Read each Research dataset's declared refresh interval instead of polling continuously; reuse downloaded immutable releases.