---
title: "Kingfisher API Guide: Programmatic Crypto Derivatives Data"
description: "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."
cover: "/images/blog/kingfisher-api-guide.jpg"
tags: ["kingfisher api", "crypto api", "api documentation", "trading api", "developer guide", "rest api"]
createdAt: 2026-02-03T17:20:00
---

# Kingfisher API Guide: Programmatic Crypto Derivatives Data

## Structured Market Intelligence Delivered via REST

The Kingfisher REST API exposes core derivatives datasets—[liquidation maps](/blogs/liquidation-maps), [GEX+](/blogs/what-is-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](/liqmap-api).

---

## 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](/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](https://app.thekingfisher.io/).
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:

```bash
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`):

```bash
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](/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:

```python
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](/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](/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](https://app.thekingfisher.io/).

---

**[Explore API Plans & Endpoint Reference](/liqmap-api)** | **[Open Kingfisher App](https://app.thekingfisher.io/)**

## Related Articles

- [KF-OEMS Example Trades: Real Order Execution Setups with Entry, Exit and Risk Rules](/blogs/kf_oems_example_trades)
- [KF Index: How to Create and Trade Custom Crypto Indexes on Kingfisher](/blogs/kf_index_create_and_trade_your_own_instruments)
- [Kingfisher Review 2026: Honest Assessment from Real Traders](/blogs/kingfisher-review)
- [Getting Started on the Kingfisher: Complete Beginner's Guide](/blogs/getting_started_on_the_kingfisher)
