--
--MAP
Kingfisher Liquidation heatmap visualization showing market leverage clusters with color-coded buy and sell walls indicating potential price targets

kingfisher api

Kingfisher API Guide: Programmatic Crypto Derivatives Data

Guide to The Kingfisher REST API: X-API-Key authentication, https://app.thekingfisher.io/api endpoints for liquidation maps, GEX+, and TOF, plus credit-based plans.

Published ⏱ 6 min readkingfisher apicrypto apiapi documentationtrading apideveloper guiderest api

Structured Market Intelligence Delivered via REST

The Kingfisher REST API exposes core derivatives datasets—liquidation maps, GEX+ dealer gamma profiles, Toxic Order Flow (TOF), liquidation ratios, and screener snapshots—over standard HTTPS JSON endpoints for scripts, internal dashboards, research pipelines, and risk tooling.

Live endpoint specifications, active credit schedules, and billing tiers are maintained on the Liquidation Map API documentation page.


Access Tiers & Monthly Credits

API access uses credit-based allowances rather than unlimited unthrottled feeds. Current plans documented on /liqmap-api and /pricing include:

Workspace Subscriptions with API Credits

  • Pro ($780/year): Core analytical web workspace plus 420 API credits/month.
  • Max ($1,080/year): Full web workspace (including aggregated and multi-coin liquidation maps) plus 600 API credits/month.

Dedicated API Plans

  • Individual ($499/month): 2,000 monthly credits, BTC & ETH scope, and 3 months of historical archive depth.
  • Professional ($1,499/month): 5,000 monthly credits, BTC, ETH & altcoin scope, and 1 year of historical archive depth.
  • Enterprise ($2,499/month): 15,000 monthly credits, all supported instruments, and full historical archive depth.

(Check the live interactive pricing selector on /liqmap-api for quarterly, semi-annual, and annual billing terms and overage rates.)


Authentication

Generating Your API Key

  1. Sign in to The Kingfisher dashboard.
  2. Open your API / subscription settings and generate a key.
  3. Store the key securely in an environment variable (never commit keys into git).

Making Authenticated Requests

Pass your key via the X-API-Key HTTP request header:

X-API-Key: kf_your_api_key_here

Example request:

curl -H "X-API-Key: kf_your_api_key_here" \
  "https://app.thekingfisher.io/api/map/latest?symbol=BTCUSDT&exchange=binance"

Verify subscription status and remaining credits without spending credits (0 credits):

curl -H "X-API-Key: kf_your_api_key_here" \
  https://app.thekingfisher.io/api/api-subscription/status

Base URL

Base URL: https://app.thekingfisher.io/api

Core Endpoints Reference

Treat the interactive endpoint table on /liqmap-api as the authoritative reference for supported parameters, credit weights, and response shapes.

1. Liquidation Maps (1–5 credits)

  • GET /api/map/latest — Latest estimated liquidation map snapshot for a supported pair and exchange (1 credit; multi-timeframe/aggregated queries may carry 5 credits).
  • GET /api/map/timestamp — Historical liquidation map snapshot at a given Unix timestamp rounded to the nearest hour (historical lookback depends on your plan tier).

Model boundary: Treat liquidation map cluster outputs as modeled estimates derived from proprietary inputs and market structure—never as exact counts of private exchange accounts, guaranteed liquidation volumes, or price predictions. Preserve request parameters and response timestamps when logging observations.

2. GEX+ & Options Analytics (2 credits)

  • GET /api/map/gexplus — Gamma exposure profile by strike and estimated dealer flip level.
  • GET /api/map/gevex — Combined gamma/vega exposure views.
  • GET /api/map/greeks — Options Greeks breakdown (expiry filter supported, e.g. "ALL" or DDMMMYY).
  • GET /api/map/charm_pin, GET /api/map/charm_tide, GET /api/map/charm_heatmap — Charm pin, tide, and heatmap views.
  • GET /api/map/volbeta — Volatility beta metrics across assets.

Reading dealer regimes: A flip zone estimates where modeled dealer hedging flows switch between dampening volatility (positive gamma) and amplifying swings (negative gamma). Use it as context alongside liquidation clusters and spot order flow rather than a standalone signal.

3. Toxic Order Flow (1–2 credits)

  • GET /api/tof/get_available — List supported pairs for TOF endpoints.
  • GET /api/tof — Latest TOF snapshot (approx. 30d at 1h, approx. 90d at 4h).
  • GET /api/tof/historical — Historical TOF series across date ranges permitted by your plan tier.

4. Ratios, Screeners & Account Usage (0–5 credits)

  • GET /api/ratios/latest — Liquidation ratios (1 credit, multi views 5 credits).
  • GET /api/rsi — Relative Strength Index screener (1 credit).
  • GET /api/markets-surge — Trending / elevated-volatility asset screener (2 credits).
  • GET /api/api-subscription/status, GET /api/api-subscription/usage, GET /api/api-subscription/instruments — Plan limits, credit usage, and permitted symbols (0 credits).

Python Quickstart Example

Any standard HTTPS client can consume /api using X-API-Key without third-party proprietary SDK wrappers:

import os
import time
import requests

API_KEY = os.environ["KF_API_KEY"]
BASE_URL = "https://app.thekingfisher.io/api"
HEADERS = {"X-API-Key": API_KEY}

def kf_get(path, params=None, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(
            f"{BASE_URL}{path}",
            headers=HEADERS,
            params=params,
            timeout=15,
        )
        if resp.status_code in (429, 500, 502, 503, 504):
            time.sleep(2 ** attempt)
            continue
        resp.raise_for_status()
        return resp.json()
    return None

if __name__ == "__main__":
    usage = kf_get("/api-subscription/usage")
    liq_map = kf_get("/map/latest", params={"symbol": "BTCUSDT", "exchange": "binance"})
    gex_profile = kf_get("/map/gexplus", params={"symbol": "BTC"})
    print("Remaining usage:", usage)
    print("LiqMap keys:", list(liq_map.keys()) if isinstance(liq_map, dict) else type(liq_map))
    print("GEX+ keys:", list(gex_profile.keys()) if isinstance(gex_profile, dict) else type(gex_profile))

(Inspect live JSON response payloads directly from your authenticated account or /liqmap-api before writing parser logic.)


Error Handling & Credit Discipline

  • 400 Bad Request: Verify symbol format, exchange name, and optional timeframe/timestamp parameters against /liqmap-api.
  • 401 / 403 Unauthorized: Confirm your X-API-Key header is valid and check /api/api-subscription/instruments to ensure the requested asset is enabled for your tier.
  • 402 / 429 Credit or Rate Limit: Pause polling and use exponential backoff. Cache immutable historical timestamp responses rather than re-querying unchanged windows.
  • 5xx Server Error: Retry transiently with bounded exponential backoff (2 ** attempt) and timeouts.

Best Practices

Cache Immutable Historical Snapshots

Historical /api/map/timestamp and historical /api/tof/historical windows do not change once closed. Cache them locally so your monthly credit allocation focuses on fresh market checks.

Reuse HTTPS Connections

Use requests.Session() (Python) or keep-alive HTTP agents (Node.js/Go/Rust) to eliminate repeated TLS handshakes across scheduled polls.

Monitor Credits Before Heavy Scans

Call GET /api/api-subscription/usage (0 credits) before running multi-symbol jobs so scripts degrade gracefully instead of exhausting mid-session credit budgets.


FAQ

Q: Which authentication header does the API use? A: Send your key in the X-API-Key header (X-API-Key: kf_your_api_key_here) to https://app.thekingfisher.io/api.

Q: How should I size my credit budget? A: Account for both polling cadence and endpoint weight (1 credit for LiqMap/ratios/RSI, 2 credits for GEX+/TOF/Markets Surge, 5 credits for multi-asset queries, 0 credits for status/usage). Workspace tiers include 420–600 credits/month; dedicated API tiers provide 2,000–15,000 credits/month.

Q: Which programming languages are supported? A: Any language capable of standard HTTPS GET requests with custom headers and JSON parsing (Python, TypeScript/Node.js, Go, Rust, etc.) works directly with https://app.thekingfisher.io/api—no language-specific vendor SDK required.

Q: What latency should automated scripts assume? A: Observed REST round-trip times vary with payload size, network route, and market activity. Rely on timestamps returned in API payloads, enforce explicit HTTP timeouts and retries, and handle stale responses gracefully rather than assuming fixed delivery latency.

Q: Can I redistribute Kingfisher API data in third-party products? A: Standard API tiers cover personal trading workflows and internal research tooling. Commercial redistribution or SaaS embedding requires prior licensing terms via The Kingfisher.


Explore API Plans & Endpoint Reference | Open Kingfisher App