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/options_data.py
View on GitHub#!/usr/bin/env python3
"""
Options market data from Deribit's public API.
Everything here is computed from Deribit's published instrument summaries,
volatility index (DVOL) and recent trades; nothing is estimated or simulated.
- Put/call ratios by open interest and by 24-hour volume, per expiry.
- Max pain: the settlement price at which option holders' total intrinsic
value would be smallest, computed from open interest by strike.
- At-the-money implied volatility: Deribit's mark IV at the strike nearest the
expiry's underlying price.
- DVOL rank and percentile over the trailing 365 days.
- Large recent trades above a notional threshold.
"""
from __future__ import annotations
from collections import defaultdict
from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from typing import Dict, List, Optional
from http_client import FetchError, Http
DERIBIT = "https://www.deribit.com/api/v2/public"
OPTION_CURRENCIES = ("BTC", "ETH")
@dataclass
class OptionRow:
expiry: datetime
expiry_code: str
strike: float
kind: str # "C" or "P"
open_interest: float # coins
volume: float # coins, 24h
mark_iv: Optional[float]
underlying_price: float
@dataclass
class ExpirySummary:
expiry: datetime
expiry_code: str
underlying_price: float
call_oi: float
put_oi: float
call_volume: float
put_volume: float
atm_strike: float
atm_iv: Optional[float]
max_pain: float
@property
def pcr_oi(self) -> Optional[float]:
return self.put_oi / self.call_oi if self.call_oi else None
@property
def pcr_volume(self) -> Optional[float]:
return self.put_volume / self.call_volume if self.call_volume else None
@property
def max_pain_distance_pct(self) -> float:
return (self.max_pain / self.underlying_price - 1.0) * 100.0
@dataclass
class DvolStats:
current: float
low_365d: float
high_365d: float
percentile_365d: float # share of days with a lower close, in percent
@property
def rank_365d(self) -> float:
span = self.high_365d - self.low_365d
return (self.current - self.low_365d) / span * 100.0 if span else 50.0
@dataclass
class LargeTrade:
time: datetime
instrument: str
direction: str # taker side: "buy" or "sell"
amount: float # contracts, in coins
notional_usd: float
premium_usd: float
iv: Optional[float]
block: bool
@dataclass
class OptionsReport:
currency: str
expiries: List[ExpirySummary]
total_call_oi: float
total_put_oi: float
dvol: Optional[DvolStats]
trades: List[LargeTrade] = field(default_factory=list)
sources: List[str] = field(default_factory=list)
failures: List[str] = field(default_factory=list)
@property
def pcr_oi(self) -> Optional[float]:
return self.total_put_oi / self.total_call_oi if self.total_call_oi else None
def parse_instrument(name: str):
"""BTC-27NOV26-80000-C -> (expiry datetime 08:00 UTC, code, strike, kind)."""
_, code, strike, kind = name.split("-")
expiry = datetime.strptime(code, "%d%b%y").replace(hour=8, tzinfo=timezone.utc)
return expiry, code, float(strike.replace("d", ".")), kind
def max_pain(rows: List[OptionRow]) -> float:
"""Strike at which the total intrinsic value owed to option holders is smallest."""
calls: Dict[float, float] = defaultdict(float)
puts: Dict[float, float] = defaultdict(float)
for r in rows:
(calls if r.kind == "C" else puts)[r.strike] += r.open_interest
strikes = sorted(set(calls) | set(puts))
def payout(settle: float) -> float:
owed_calls = sum(oi * (settle - k) for k, oi in calls.items() if settle > k)
owed_puts = sum(oi * (k - settle) for k, oi in puts.items() if settle < k)
return owed_calls + owed_puts
return min(strikes, key=payout)
def summarize_expiry(rows: List[OptionRow]) -> ExpirySummary:
underlying = rows[0].underlying_price
atm_strike = min({r.strike for r in rows}, key=lambda k: abs(k - underlying))
atm_ivs = [r.mark_iv for r in rows if r.strike == atm_strike and r.mark_iv]
return ExpirySummary(
expiry=rows[0].expiry,
expiry_code=rows[0].expiry_code,
underlying_price=underlying,
call_oi=sum(r.open_interest for r in rows if r.kind == "C"),
put_oi=sum(r.open_interest for r in rows if r.kind == "P"),
call_volume=sum(r.volume for r in rows if r.kind == "C"),
put_volume=sum(r.volume for r in rows if r.kind == "P"),
atm_strike=atm_strike,
atm_iv=sum(atm_ivs) / len(atm_ivs) if atm_ivs else None,
max_pain=max_pain(rows),
)
def fetch_rows(http: Http, currency: str) -> List[OptionRow]:
url = f"{DERIBIT}/get_book_summary_by_currency?currency={currency}&kind=option"
result = http.get_json(url).get("result") or []
rows = []
for item in result:
try:
expiry, code, strike, kind = parse_instrument(item["instrument_name"])
except (ValueError, KeyError):
continue
rows.append(
OptionRow(
expiry=expiry,
expiry_code=code,
strike=strike,
kind=kind,
open_interest=float(item.get("open_interest") or 0),
volume=float(item.get("volume") or 0),
mark_iv=item.get("mark_iv"),
underlying_price=float(item["underlying_price"]),
)
)
return rows
def fetch_dvol(http: Http, currency: str) -> DvolStats:
end = http.now()
start = end - timedelta(days=365)
url = (
f"{DERIBIT}/get_volatility_index_data?currency={currency}&resolution=1D"
f"&start_timestamp={int(start.timestamp()) // 86400 * 86400 * 1000}"
f"&end_timestamp={int(end.timestamp()) // 3600 * 3600 * 1000}"
)
data = http.get_json(url)["result"]["data"] # [ts, open, high, low, close]
if len(data) < 30:
raise FetchError("not enough DVOL history")
closes = [row[4] for row in data]
current = closes[-1]
return DvolStats(
current=current,
low_365d=min(closes),
high_365d=max(closes),
percentile_365d=sum(1 for c in closes[:-1] if c < current) / (len(closes) - 1) * 100.0,
)
def fetch_large_trades(http: Http, currency: str, min_notional_usd: float, limit: int = 10) -> List[LargeTrade]:
url = f"{DERIBIT}/get_last_trades_by_currency?currency={currency}&kind=option&count=1000"
trades = http.get_json(url)["result"]["trades"]
out = []
for t in trades:
index = float(t["index_price"])
notional = float(t["amount"]) * index
if notional < min_notional_usd:
continue
out.append(
LargeTrade(
time=datetime.fromtimestamp(t["timestamp"] / 1000, tz=timezone.utc),
instrument=t["instrument_name"],
direction=t["direction"],
amount=float(t["amount"]),
notional_usd=notional,
premium_usd=float(t["price"]) * float(t["amount"]) * index,
iv=t.get("iv"),
block="block_trade_id" in t,
)
)
out.sort(key=lambda x: x.notional_usd, reverse=True)
return out[:limit]
def build_report(
http: Http,
currency: str,
expiry_code: Optional[str] = None,
max_expiries: int = 6,
trades_min_usd: Optional[float] = None,
) -> OptionsReport:
currency = currency.upper()
if currency not in OPTION_CURRENCIES:
raise FetchError(f"Deribit lists options for {', '.join(OPTION_CURRENCIES)} only")
rows = fetch_rows(http, currency)
if not rows:
raise FetchError("Deribit returned no option instruments")
now = http.now()
by_expiry: Dict[str, List[OptionRow]] = defaultdict(list)
for r in rows:
if r.expiry > now:
by_expiry[r.expiry_code].append(r)
if expiry_code:
wanted = expiry_code.upper()
if wanted not in by_expiry:
listed = ", ".join(sorted(by_expiry, key=lambda c: by_expiry[c][0].expiry))
raise FetchError(f"expiry {wanted} not listed; listed expiries: {listed}")
codes = [wanted]
else:
codes = sorted(by_expiry, key=lambda c: by_expiry[c][0].expiry)[:max_expiries]
report = OptionsReport(
currency=currency,
expiries=[summarize_expiry(by_expiry[c]) for c in codes],
total_call_oi=sum(r.open_interest for r in rows if r.kind == "C" and r.expiry > now),
total_put_oi=sum(r.open_interest for r in rows if r.kind == "P" and r.expiry > now),
dvol=None,
sources=[f"{DERIBIT}/get_book_summary_by_currency?currency={currency}&kind=option"],
)
try:
report.dvol = fetch_dvol(http, currency)
report.sources.append(f"{DERIBIT}/get_volatility_index_data ({currency} DVOL, daily)")
except FetchError as exc:
report.failures.append(f"deribit DVOL: {exc.reason}")
if trades_min_usd is not None:
try:
report.trades = fetch_large_trades(http, currency, trades_min_usd)
report.sources.append(f"{DERIBIT}/get_last_trades_by_currency ({currency} options, last 1000)")
except FetchError as exc:
report.failures.append(f"deribit trades: {exc.reason}")
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 |