jeremylongshore/tons-of-skills-marketplace / plugins/crypto/crypto-derivatives-tracker/skills/tracking-crypto-derivatives
tracking-crypto-derivatives
VerifiedResearch crypto perpetual swaps, dated futures and options from live public exchange data: funding rates, open interest, basis, liquidations, put/call ratios and max pain. Read-only, no API keys. Use when checking funding across exchanges, comparing open interest, reading the futures term structure, reviewing recent liquidations, or summarizing the options market for BTC or ETH. Trigger with phrases like "funding rate", "open interest", "perpetual swap", "futures basis", "liquidations", "put call ratio", "max pain", "derivatives analysis", or "BTC perps".
| File | Kind | Size |
|---|---|---|
| ARD.md | markdown | 2.7 KB |
| PRD.md | markdown | 2.7 KB |
| SKILL.md | skill md | 6.9 KB |
| assets/demo-recording.json | config | 187.6 KB |
| references/errors.md | markdown | 2.5 KB |
| references/examples.md | markdown | 17.4 KB |
| references/implementation.md | markdown | 4.8 KB |
| scripts/basis_data.py | script | 4.5 KB |
| scripts/derivatives_tracker.py | script | 25.0 KB |
| scripts/http_client.py | script | 6.4 KB |
| scripts/liquidations.py | script | 4.0 KB |
| scripts/options_data.py | script | 9.2 KB |
| scripts/perps.py | script | 17.6 KB |
| scripts/record_demo.py | script | 3.3 KB |
| tests/fixtures/binance-bybit-recording.json | config | 12.8 KB |
| tests/test_derivatives_tracker.py | script | 10.0 KB |
scripts/perps.py
View on GitHub#!/usr/bin/env python3
"""
Perpetual swaps: funding rates and open interest from public exchange endpoints.
Each venue adapter reads one public, keyless endpoint set and returns a
`PerpSnapshot` in common units:
- `funding_rate` is the venue's own rate for one funding interval, as a fraction.
- `interval_hours` is that interval (OKX, Binance, Bybit, KuCoin and Gate pay
every 8 hours by default; Hyperliquid, Kraken and dYdX pay hourly; Deribit
accrues continuously and publishes an 8-hour figure).
- `oi_base` is open interest counted on one side, in the coin.
Comparisons always use the 8-hour equivalent (`rate_8h`) so hourly and
8-hourly venues line up.
"""
from __future__ import annotations
import statistics
from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from typing import Callable, Dict, List, Optional, Tuple
from http_client import FetchError, Http
OKX = "https://www.okx.com"
DERIBIT = "https://www.deribit.com/api/v2/public"
HYPERLIQUID = "https://api.hyperliquid.xyz/info"
KRAKEN = "https://futures.kraken.com/derivatives/api/v3"
KUCOIN = "https://api-futures.kucoin.com/api/v1"
GATE = "https://api.gateio.ws/api/v4"
DYDX = "https://indexer.dydx.trade/v4"
BINANCE = "https://fapi.binance.com"
BYBIT = "https://api.bybit.com/v5"
@dataclass
class PerpSnapshot:
"""One venue's perpetual swap for one coin, in common units."""
venue: str
instrument: str
funding_rate: float
interval_hours: float
next_funding: Optional[datetime]
mark_price: Optional[float]
index_price: Optional[float]
oi_base: Optional[float]
source: str
@property
def rate_8h(self) -> float:
"""Funding rate scaled to an 8-hour period."""
return self.funding_rate * 8.0 / self.interval_hours
@property
def annualized_pct(self) -> float:
"""Simple (non-compounded) annual rate, in percent."""
return self.funding_rate * (24.0 * 365.0 / self.interval_hours) * 100.0
@property
def price(self) -> Optional[float]:
return self.mark_price or self.index_price
@property
def oi_usd(self) -> Optional[float]:
if self.oi_base is None or self.price is None:
return None
return self.oi_base * self.price
@dataclass
class VenueFailure:
venue: str
reason: str
@dataclass
class OIChange:
"""Open interest change over 24 hours, measured in coins so price moves do not count."""
venue: str
oi_base_now: float
oi_base_24h_ago: float
source: str
@property
def change_pct(self) -> float:
return (self.oi_base_now / self.oi_base_24h_ago - 1.0) * 100.0
@dataclass
class AccountRatio:
"""Share of the venue's accounts holding a net long position."""
venue: str
long_accounts_pct: float
source: str
def _f(value) -> Optional[float]:
if value in (None, ""):
return None
return float(value)
def _ms(value) -> Optional[datetime]:
if value in (None, "", 0, "0"):
return None
return datetime.fromtimestamp(int(value) / 1000, tz=timezone.utc)
def _next_hour(now: datetime) -> datetime:
return now.replace(minute=0, second=0, microsecond=0) + timedelta(hours=1)
def _kraken_symbol(symbol: str) -> str:
return "XBT" if symbol == "BTC" else symbol
# ---------------------------------------------------------------------------
# Venue adapters
# ---------------------------------------------------------------------------
def fetch_okx(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{symbol}-USDT-SWAP"
url = f"{OKX}/api/v5/public/funding-rate?instId={inst}"
fr = http.get_json(url)
if fr.get("code") != "0" or not fr.get("data"):
raise FetchError(f"{inst} not listed")
row = fr["data"][0]
oi = http.get_json(f"{OKX}/api/v5/public/open-interest?instType=SWAP&instId={inst}")["data"][0]
mark = http.get_json(f"{OKX}/api/v5/public/mark-price?instType=SWAP&instId={inst}")["data"][0]
this_time, next_time = int(row["fundingTime"]), int(row["nextFundingTime"])
return PerpSnapshot(
venue="okx",
instrument=inst,
funding_rate=float(row["fundingRate"]),
interval_hours=(next_time - this_time) / 3_600_000 or 8.0,
next_funding=_ms(this_time),
mark_price=_f(mark["markPx"]),
index_price=None,
oi_base=_f(oi["oiCcy"]),
source=url,
)
def fetch_deribit(http: Http, symbol: str) -> PerpSnapshot:
inverse = symbol in ("BTC", "ETH")
inst = f"{symbol}-PERPETUAL" if inverse else f"{symbol}_USDC-PERPETUAL"
url = f"{DERIBIT}/ticker?instrument_name={inst}"
res = http.get_json(url).get("result")
if not res:
raise FetchError(f"{inst} not listed")
mark = float(res["mark_price"])
oi = float(res["open_interest"])
return PerpSnapshot(
venue="deribit",
instrument=inst,
funding_rate=float(res["funding_8h"]),
interval_hours=8.0,
next_funding=None, # Deribit accrues funding continuously
mark_price=mark,
index_price=_f(res.get("index_price")),
# Inverse perpetuals report open interest in USD; USDC perpetuals in coins.
oi_base=oi / mark if inverse else oi,
source=url,
)
def fetch_hyperliquid(http: Http, symbol: str) -> PerpSnapshot:
meta, ctxs = http.post_json(HYPERLIQUID, {"type": "metaAndAssetCtxs"})
names = [u["name"] for u in meta["universe"]]
if symbol not in names:
raise FetchError(f"{symbol} not listed")
ctx = ctxs[names.index(symbol)]
return PerpSnapshot(
venue="hyperliquid",
instrument=symbol,
funding_rate=float(ctx["funding"]),
interval_hours=1.0,
next_funding=_next_hour(http.now()),
mark_price=_f(ctx["markPx"]),
index_price=_f(ctx.get("oraclePx")),
oi_base=_f(ctx["openInterest"]),
source=f"{HYPERLIQUID} metaAndAssetCtxs",
)
def fetch_kraken(http: Http, symbol: str) -> PerpSnapshot:
inst = f"PF_{_kraken_symbol(symbol)}USD"
url = f"{KRAKEN}/tickers/{inst}"
body = http.get_json(url)
tick = body.get("ticker")
if body.get("result") != "success" or not tick or tick.get("relativeFundingRate") is None:
raise FetchError(f"{inst} not listed")
return PerpSnapshot(
venue="kraken",
instrument=inst,
# relativeFundingRate is the hourly rate as a fraction of price.
funding_rate=float(tick["relativeFundingRate"]),
interval_hours=1.0,
next_funding=_next_hour(http.now()),
mark_price=_f(tick.get("markPrice")),
index_price=_f(tick.get("indexPrice")),
oi_base=_f(tick.get("openInterest")), # contract size is one coin
source=url,
)
def fetch_kucoin(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{_kraken_symbol(symbol)}USDTM"
url = f"{KUCOIN}/contracts/{inst}"
data = http.get_json(url).get("data")
if not data or data.get("status") != "Open":
raise FetchError(f"{inst} not listed")
return PerpSnapshot(
venue="kucoin",
instrument=inst,
funding_rate=float(data["fundingFeeRate"]),
interval_hours=float(data["currentFundingRateGranularity"]) / 3_600_000,
next_funding=_ms(data.get("nextFundingRateDateTime")),
mark_price=_f(data.get("markPrice")),
index_price=_f(data.get("indexPrice")),
oi_base=float(data["openInterest"]) * float(data["multiplier"]),
source=url,
)
def fetch_gate(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{symbol}_USDT"
url = f"{GATE}/futures/usdt/contracts/{inst}"
data = http.get_json(url)
if not isinstance(data, dict) or "funding_rate" not in data:
raise FetchError(f"{inst} not listed")
next_apply = data.get("funding_next_apply")
return PerpSnapshot(
venue="gate",
instrument=inst,
funding_rate=float(data["funding_rate"]),
interval_hours=float(data["funding_interval"]) / 3600,
next_funding=datetime.fromtimestamp(int(next_apply), tz=timezone.utc) if next_apply else None,
mark_price=_f(data.get("mark_price")),
index_price=_f(data.get("index_price")),
# position_size is the total long position in contracts (one side).
oi_base=float(data["position_size"]) * float(data["quanto_multiplier"]),
source=url,
)
def fetch_dydx(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{symbol}-USD"
url = f"{DYDX}/perpetualMarkets?ticker={inst}"
market = http.get_json(url).get("markets", {}).get(inst)
if not market or market.get("status") != "ACTIVE":
raise FetchError(f"{inst} not listed")
return PerpSnapshot(
venue="dydx",
instrument=inst,
funding_rate=float(market["nextFundingRate"]),
interval_hours=1.0,
next_funding=_next_hour(http.now()),
mark_price=None,
index_price=_f(market.get("oraclePrice")),
oi_base=_f(market.get("openInterest")),
source=url,
)
def fetch_binance(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{symbol}USDT"
url = f"{BINANCE}/fapi/v1/premiumIndex?symbol={inst}"
prem = http.get_json(url)
if "lastFundingRate" not in prem:
raise FetchError(f"{inst} not listed")
oi = http.get_json(f"{BINANCE}/fapi/v1/openInterest?symbol={inst}")
# fundingInfo lists only symbols whose interval differs from the 8-hour default.
info = http.get_json(f"{BINANCE}/fapi/v1/fundingInfo")
interval = next((float(i["fundingIntervalHours"]) for i in info if i.get("symbol") == inst), 8.0)
return PerpSnapshot(
venue="binance",
instrument=inst,
funding_rate=float(prem["lastFundingRate"]),
interval_hours=interval,
next_funding=_ms(prem.get("nextFundingTime")),
mark_price=_f(prem.get("markPrice")),
index_price=_f(prem.get("indexPrice")),
oi_base=_f(oi.get("openInterest")),
source=url,
)
def fetch_bybit(http: Http, symbol: str) -> PerpSnapshot:
inst = f"{symbol}USDT"
url = f"{BYBIT}/market/tickers?category=linear&symbol={inst}"
body = http.get_json(url)
rows = body.get("result", {}).get("list") or []
if body.get("retCode") != 0 or not rows:
raise FetchError(f"{inst} not listed")
row = rows[0]
return PerpSnapshot(
venue="bybit",
instrument=inst,
funding_rate=float(row["fundingRate"]),
interval_hours=float(row.get("fundingIntervalHour") or 8),
next_funding=_ms(row.get("nextFundingTime")),
mark_price=_f(row.get("markPrice")),
index_price=_f(row.get("indexPrice")),
# openInterest counts both sides; singleOpenInterest is one side.
oi_base=_f(row.get("singleOpenInterest")),
source=url,
)
VENUES: Dict[str, Callable[[Http, str], PerpSnapshot]] = {
"okx": fetch_okx,
"deribit": fetch_deribit,
"hyperliquid": fetch_hyperliquid,
"kraken": fetch_kraken,
"kucoin": fetch_kucoin,
"gate": fetch_gate,
"dydx": fetch_dydx,
"binance": fetch_binance,
"bybit": fetch_bybit,
}
def fetch_all(
http: Http, symbol: str, venues: Optional[List[str]] = None
) -> Tuple[List[PerpSnapshot], List[VenueFailure]]:
"""Fetch every venue in parallel; a failing venue is reported, never invented."""
names = venues or list(VENUES)
results: List[PerpSnapshot] = []
failures: List[VenueFailure] = []
def one(name: str):
try:
return VENUES[name](http, symbol), None
except FetchError as exc:
return None, VenueFailure(name, exc.reason)
except (KeyError, IndexError, TypeError, ValueError) as exc:
return None, VenueFailure(name, f"unexpected response shape ({type(exc).__name__}: {exc})")
with ThreadPoolExecutor(max_workers=len(names)) as pool:
for snap, failure in pool.map(one, names):
if snap is not None:
results.append(snap)
if failure is not None:
failures.append(failure)
return results, failures
# ---------------------------------------------------------------------------
# History and positioning (venues that publish it for the same instrument)
# ---------------------------------------------------------------------------
def _oi_change_okx(http: Http, symbol: str) -> OIChange:
inst = f"{symbol}-USDT-SWAP"
url = f"{OKX}/api/v5/rubik/stat/contracts/open-interest-history?instId={inst}&period=1H&limit=25"
rows = http.get_json(url)["data"] # newest first: [ts, oi, oiCcy, oiUsd]
if len(rows) < 25:
raise FetchError("less than 24 hours of history")
return OIChange("okx", float(rows[0][2]), float(rows[24][2]), url)
def _oi_change_bybit(http: Http, symbol: str) -> OIChange:
url = f"{BYBIT}/market/open-interest?category=linear&symbol={symbol}USDT&intervalTime=1h&limit=25"
rows = http.get_json(url)["result"]["list"] # newest first
if len(rows) < 25:
raise FetchError("less than 24 hours of history")
return OIChange("bybit", float(rows[0]["singleOpenInterest"]), float(rows[24]["singleOpenInterest"]), url)
def _oi_change_binance(http: Http, symbol: str) -> OIChange:
url = f"{BINANCE}/futures/data/openInterestHist?symbol={symbol}USDT&period=1h&limit=25"
rows = http.get_json(url) # oldest first
if len(rows) < 25:
raise FetchError("less than 24 hours of history")
return OIChange("binance", float(rows[-1]["sumOpenInterest"]), float(rows[0]["sumOpenInterest"]), url)
def _ratio_okx(http: Http, symbol: str) -> AccountRatio:
url = f"{OKX}/api/v5/rubik/stat/contracts/long-short-account-ratio-contract?instId={symbol}-USDT-SWAP&period=1H&limit=1"
ratio = float(http.get_json(url)["data"][0][1]) # longs / shorts
return AccountRatio("okx", ratio / (1 + ratio) * 100, url)
def _ratio_bybit(http: Http, symbol: str) -> AccountRatio:
url = f"{BYBIT}/market/account-ratio?category=linear&symbol={symbol}USDT&period=1h&limit=1"
row = http.get_json(url)["result"]["list"][0]
return AccountRatio("bybit", float(row["buyRatio"]) * 100, url)
def _ratio_binance(http: Http, symbol: str) -> AccountRatio:
url = f"{BINANCE}/futures/data/globalLongShortAccountRatio?symbol={symbol}USDT&period=1h&limit=1"
row = http.get_json(url)[0]
return AccountRatio("binance", float(row["longAccount"]) * 100, url)
OI_HISTORY = {"okx": _oi_change_okx, "bybit": _oi_change_bybit, "binance": _oi_change_binance}
ACCOUNT_RATIOS = {"okx": _ratio_okx, "bybit": _ratio_bybit, "binance": _ratio_binance}
def fetch_positioning(
http: Http, symbol: str, venues: List[str]
) -> Tuple[List[OIChange], List[AccountRatio], List[VenueFailure]]:
"""24-hour open interest change and account long share, where the venue publishes them."""
changes: List[OIChange] = []
ratios: List[AccountRatio] = []
failures: List[VenueFailure] = []
jobs = [("oi", v, OI_HISTORY[v]) for v in venues if v in OI_HISTORY]
jobs += [("ratio", v, ACCOUNT_RATIOS[v]) for v in venues if v in ACCOUNT_RATIOS]
def one(job):
kind, venue, fn = job
try:
return kind, fn(http, symbol), None
except FetchError as exc:
return (
kind,
None,
VenueFailure(f"{venue} ({'24h history' if kind == 'oi' else 'account ratio'})", exc.reason),
)
except (KeyError, IndexError, TypeError, ValueError) as exc:
return kind, None, VenueFailure(venue, f"unexpected response shape ({type(exc).__name__})")
if not jobs:
return changes, ratios, failures
with ThreadPoolExecutor(max_workers=len(jobs)) as pool:
for kind, value, failure in pool.map(one, jobs):
if failure is not None:
failures.append(failure)
elif kind == "oi":
changes.append(value)
else:
ratios.append(value)
return changes, ratios, failures
# ---------------------------------------------------------------------------
# Summaries (descriptive only)
# ---------------------------------------------------------------------------
@dataclass
class FundingSummary:
venues: int
positive: int
negative: int
mean_8h: float
median_8h: float
oi_weighted_8h: Optional[float]
highest: PerpSnapshot
lowest: PerpSnapshot
notes: List[str] = field(default_factory=list)
@property
def spread_8h(self) -> float:
return self.highest.rate_8h - self.lowest.rate_8h
def summarize_funding(snaps: List[PerpSnapshot]) -> FundingSummary:
if not snaps:
raise ValueError("no venue returned data")
rates = [s.rate_8h for s in snaps]
weighted = [(s.rate_8h, s.oi_usd) for s in snaps if s.oi_usd]
total_oi = sum(w for _, w in weighted)
summary = FundingSummary(
venues=len(snaps),
positive=sum(1 for r in rates if r > 0),
negative=sum(1 for r in rates if r < 0),
mean_8h=statistics.fmean(rates),
median_8h=statistics.median(rates),
oi_weighted_8h=(sum(r * w for r, w in weighted) / total_oi) if total_oi else None,
highest=max(snaps, key=lambda s: s.rate_8h),
lowest=min(snaps, key=lambda s: s.rate_8h),
)
if summary.positive == summary.venues:
summary.notes.append("Funding is positive on every venue: longs pay shorts.")
elif summary.negative == summary.venues:
summary.notes.append("Funding is negative on every venue: shorts pay longs.")
else:
zero = summary.venues - summary.positive - summary.negative
parts = [f"positive on {summary.positive}", f"negative on {summary.negative}"]
if zero:
parts.append(f"zero on {zero}")
summary.notes.append(f"Of {summary.venues} venues, funding is " + ", ".join(parts) + ".")
return summary
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |