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/liquidations.py
View on GitHub#!/usr/bin/env python3
"""
Recent liquidations from OKX's public liquidation-orders endpoint.
OKX is the venue in this tracker that publishes filled liquidation orders over
a keyless REST endpoint. The result covers the most recent orders OKX returns
for the instrument family, so the time window varies; the report states it.
Liquidation "heatmaps" sold by data vendors are model estimates of where
positions would be closed; public data cannot reproduce them, so this tracker
does not draw one.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from typing import List
from http_client import FetchError, Http
OKX = "https://www.okx.com"
@dataclass
class LiquidationOrder:
time: datetime
side: str # position that was liquidated: "long" or "short"
price: float
size_base: float
@property
def value_usd(self) -> float:
return self.price * self.size_base
@dataclass
class LiquidationReport:
instrument: str
orders: List[LiquidationOrder]
source: str
notes: List[str] = field(default_factory=list)
@property
def window_start(self) -> datetime:
return min(o.time for o in self.orders)
@property
def window_end(self) -> datetime:
return max(o.time for o in self.orders)
def total(self, side: str) -> float:
return sum(o.value_usd for o in self.orders if o.side == side)
def count(self, side: str) -> int:
return sum(1 for o in self.orders if o.side == side)
def largest(self, n: int = 5) -> List[LiquidationOrder]:
return sorted(self.orders, key=lambda o: o.value_usd, reverse=True)[:n]
def _liquidated_side(detail: dict) -> str:
pos = detail.get("posSide")
if pos in ("long", "short"):
return pos
# One-way mode: a forced sell closes a long, a forced buy closes a short.
return "long" if detail.get("side") == "sell" else "short"
def fetch(http: Http, symbol: str, hours: int = 24, max_pages: int = 30) -> LiquidationReport:
inst = f"{symbol}-USDT-SWAP"
inst_url = f"{OKX}/api/v5/public/instruments?instType=SWAP&instId={inst}"
inst_data = http.get_json(inst_url).get("data") or []
if not inst_data:
raise FetchError(f"{inst} not listed")
contract_value = float(inst_data[0]["ctVal"]) # coins per contract
url = f"{OKX}/api/v5/public/liquidation-orders?instType=SWAP&uly={symbol}-USDT&state=filled&limit=100"
cutoff = http.now() - timedelta(hours=hours)
orders: List[LiquidationOrder] = []
seen = set()
page_url = url
for _ in range(max_pages):
data = http.get_json(page_url).get("data") or []
page = []
for group in data:
if group.get("instId") not in (None, inst):
continue
for d in group.get("details", []):
page.append(
LiquidationOrder(
time=datetime.fromtimestamp(int(d["ts"]) / 1000, tz=timezone.utc),
side=_liquidated_side(d),
price=float(d["bkPx"]),
size_base=float(d["sz"]) * contract_value,
)
)
if not page:
break
for o in page:
key = (o.time, o.side, o.price, o.size_base)
if o.time >= cutoff and key not in seen:
seen.add(key)
orders.append(o)
oldest = min(o.time for o in page)
if oldest < cutoff:
break
page_url = f"{url}&after={int(oldest.timestamp() * 1000)}"
if not orders:
raise FetchError(f"OKX returned no filled liquidations in the last {hours} hours")
report = LiquidationReport(instrument=inst, orders=orders, source=url)
if report.window_start > cutoff + timedelta(minutes=30):
report.notes.append(
f"OKX history reached back to {report.window_start:%Y-%m-%d %H:%M} UTC, "
f"short of the requested {hours} hours."
)
return report
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 |