ironflow-sdk 0.1.0__py3-none-any.whl

ironflow_sdk/__init__.py

@@ -0,0 +1,340 @@
+# Ironflow Python SDK — market data for on-chain derivatives.
+#
+# Usage:
+#   from ironflow_sdk import Ironflow
+#   client = Ironflow("if_your_api_key")
+#   trades = await client.trades("BTC-PERP", limit=10)
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient, Page
+from .errors import AuthError, IronflowError, QueryWindowError, QueryTimeoutError, QueryTooExpensiveError, RateLimitError, TierError
+from .stream import StreamClient
+from .types import (
+    BookSnapshot, BookLevel, Candle, Deposit, FundingRate, Liquidation,
+    MarkPrice, OpenInterest, OrderStatus, Trade, Withdrawal,
+    VaultOperation, Trigger, CohortInfo, CohortAddressEntry, CohortAddresses,
+    NetFlow, LiquidationLevel, OrderFlow, VaultLeaderboardEntry, FundingStats,
+    StatusResponse, StreamStatus, VenueStatus,
+)
+
+__all__ = [
+    "Ironflow",
+    "IronflowError", "RateLimitError", "AuthError", "TierError",
+    "QueryWindowError", "QueryTimeoutError", "QueryTooExpensiveError",
+    "Trade", "BookLevel", "BookSnapshot", "Candle", "FundingRate",
+    "Liquidation", "OpenInterest", "MarkPrice", "Deposit", "Withdrawal", "OrderStatus",
+    "VaultOperation", "Trigger", "CohortInfo", "CohortAddressEntry", "CohortAddresses",
+    "NetFlow", "LiquidationLevel", "OrderFlow", "VaultLeaderboardEntry", "FundingStats",
+    "StatusResponse", "StreamStatus", "VenueStatus",
+]
+
+
+def _parse_trade(d: dict[str, Any]) -> Trade:
+    return Trade(**d)
+
+
+def _parse_book(d: dict[str, Any]) -> BookSnapshot:
+    return BookSnapshot(
+        source=d["source"],
+        market=d["market"],
+        timestamp=d["timestamp"],
+        bids=[BookLevel(**b) for b in d["bids"]],
+        asks=[BookLevel(**a) for a in d["asks"]],
+    )
+
+
+def _parse_candle(d: dict[str, Any]) -> Candle:
+    return Candle(**d)
+
+
+def _parse_funding(d: dict[str, Any]) -> FundingRate:
+    return FundingRate(**d)
+
+
+def _parse_liquidation(d: dict[str, Any]) -> Liquidation:
+    return Liquidation(**d)
+
+
+def _parse_open_interest(d: dict[str, Any]) -> OpenInterest:
+    return OpenInterest(**d)
+
+
+def _parse_mark_price(d: dict[str, Any]) -> MarkPrice:
+    return MarkPrice(**d)
+
+
+def _parse_deposit(d: dict[str, Any]) -> Deposit:
+    return Deposit(**d)
+
+
+def _parse_withdrawal(d: dict[str, Any]) -> Withdrawal:
+    return Withdrawal(**d)
+
+
+def _parse_order_status(d: dict[str, Any]) -> OrderStatus:
+    return OrderStatus(**d)
+
+
+def _parse_vault_operation(d: dict[str, Any]) -> VaultOperation:
+    return VaultOperation(**d)
+
+
+def _parse_trigger(d: dict[str, Any]) -> Trigger:
+    return Trigger(**{k: v for k, v in d.items() if k in Trigger.__dataclass_fields__})
+
+
+def _parse_cohort_info(d: dict[str, Any]) -> CohortInfo:
+    return CohortInfo(**d)
+
+
+def _parse_net_flow(d: dict[str, Any]) -> NetFlow:
+    return NetFlow(**d)
+
+
+def _parse_liquidation_level(d: dict[str, Any]) -> LiquidationLevel:
+    return LiquidationLevel(**d)
+
+
+def _parse_order_flow(d: dict[str, Any]) -> OrderFlow:
+    return OrderFlow(**d)
+
+
+def _parse_vault_leaderboard(d: dict[str, Any]) -> VaultLeaderboardEntry:
+    return VaultLeaderboardEntry(**d)
+
+
+def _parse_funding_stats(d: dict[str, Any]) -> FundingStats:
+    return FundingStats(**d)
+
+
+class Ironflow:
+    """Ironflow API client."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.ironflow.sh",
+        source: str = "hyperliquid",
+        timeout: float = 30.0,
+    ) -> None:
+        self._http = HttpClient(api_key, base_url=base_url, source=source, timeout=timeout)
+        self.stream = StreamClient(self._http.ws_url)
+
+    # ─── Market Data ────────────────────────────────────────────────────
+
+    async def trades(self, market: str, **options: Any) -> Page[Trade]:
+        """Get recent trades for a market."""
+        return await self._paginated("/v1/trades", {"market": market, **options}, _parse_trade)
+
+    async def fills(self, address: str, **options: Any) -> Page[Trade]:
+        """Get fills for an address."""
+        return await self._paginated("/v1/fills", {"address": address, **options}, _parse_trade)
+
+    async def book(self, market: str, **options: Any) -> BookSnapshot:
+        """Get the current order book snapshot."""
+        raw = await self._http.get("/v1/book", {"market": market, **options})
+        return _parse_book(raw)
+
+    async def candles(self, market: str, interval: str | None = None, **options: Any) -> Page[Candle]:
+        """Get OHLCV candlestick data."""
+        params: dict[str, Any] = {"market": market, **options}
+        if interval is not None:
+            params["interval"] = interval
+        return await self._paginated("/v1/candles", params, _parse_candle)
+
+    async def liquidations(self, market: str | None = None, **options: Any) -> Page[Liquidation]:
+        """Get liquidation events."""
+        params: dict[str, Any] = {**options}
+        if market is not None:
+            params["market"] = market
+        return await self._paginated("/v1/liquidations", params, _parse_liquidation)
+
+    async def funding(self, market: str, **options: Any) -> Page[FundingRate]:
+        """Get funding rate history."""
+        return await self._paginated("/v1/funding", {"market": market, **options}, _parse_funding)
+
+    async def open_interest(self, market: str, **options: Any) -> Page[OpenInterest]:
+        """Get open interest snapshots."""
+        return await self._paginated("/v1/open-interest", {"market": market, **options}, _parse_open_interest)
+
+    async def mark_prices(self, market: str, **options: Any) -> Page[MarkPrice]:
+        """Get mark and oracle prices."""
+        return await self._paginated("/v1/mark-prices", {"market": market, **options}, _parse_mark_price)
+
+    async def deposits(self, **options: Any) -> Page[Deposit]:
+        """Get deposit events."""
+        return await self._paginated("/v1/deposits", options, _parse_deposit)
+
+    async def withdrawals(self, **options: Any) -> Page[Withdrawal]:
+        """Get withdrawal events."""
+        return await self._paginated("/v1/withdrawals", options, _parse_withdrawal)
+
+    async def order_statuses(self, **options: Any) -> Page[OrderStatus]:
+        """Get order status events."""
+        return await self._paginated("/v1/order-statuses", options, _parse_order_status)
+
+    # ─── Vault Operations ────────────────────────────────────────────────
+
+    async def vault_operations(self, **options: Any) -> Page[VaultOperation]:
+        """Get vault deposit/withdraw events."""
+        return await self._paginated("/v1/vault-operations", options, _parse_vault_operation)
+
+    # ─── Triggers ───────────────────────────────────────────────────────
+
+    async def create_trigger(
+        self, name: str, channel: str, rule: dict[str, Any], webhook_url: str,
+    ) -> Trigger:
+        """Create a rule-based webhook trigger."""
+        raw = await self._http.post("/v1/triggers", {
+            "name": name, "channel": channel, "rule": rule, "webhook_url": webhook_url,
+        })
+        return _parse_trigger(raw)
+
+    async def list_triggers(self) -> list[Trigger]:
+        """List all triggers for the authenticated user."""
+        raw = await self._http.get("/v1/triggers")
+        return [_parse_trigger(t) for t in raw["data"]]
+
+    async def toggle_trigger(self, trigger_id: int, *, is_active: bool) -> Trigger:
+        """Toggle a trigger on or off."""
+        raw = await self._http.patch(f"/v1/triggers/{trigger_id}", {"is_active": is_active})
+        return _parse_trigger(raw)
+
+    async def delete_trigger(self, trigger_id: int) -> None:
+        """Delete a trigger."""
+        await self._http.delete(f"/v1/triggers/{trigger_id}")
+
+    async def test_trigger(self, rule: dict[str, Any], event: dict[str, Any]) -> bool:
+        """Test a trigger rule against a sample event. Returns whether it matched."""
+        raw = await self._http.post("/v1/triggers/test", {"rule": rule, "event": event})
+        return raw["matched"]
+
+    # ─── Cohorts ────────────────────────────────────────────────────────
+
+    async def list_cohorts(self) -> list[CohortInfo]:
+        """List predefined and custom cohorts."""
+        raw = await self._http.get("/v1/cohorts")
+        return [_parse_cohort_info(c) for c in raw["data"]]
+
+    async def create_cohort(self, name: str, addresses: list[str]) -> CohortInfo:
+        """Create a custom address cohort."""
+        raw = await self._http.post("/v1/cohorts", {"name": name, "addresses": addresses})
+        return _parse_cohort_info(raw)
+
+    async def cohort_addresses(self, name: str) -> CohortAddresses:
+        """Get addresses in a cohort."""
+        raw = await self._http.get(f"/v1/cohorts/{name}")
+        return CohortAddresses(
+            addresses=[CohortAddressEntry(**a) for a in raw["addresses"]],
+            fetched_at=raw["fetched_at"],
+        )
+
+    async def delete_cohort(self, name: str) -> None:
+        """Delete a custom cohort."""
+        await self._http.delete(f"/v1/cohorts/{name}")
+
+    # ─── Analytics (Builder+ only) ─────────────────────────────────────
+
+    async def net_flows(self, **options: Any) -> list[NetFlow]:
+        """Get net deposit/withdrawal flows over time."""
+        raw = await self._http.get("/v1/analytics/net-flows", options)
+        return [_parse_net_flow(f) for f in raw["data"]]
+
+    async def liquidation_levels(self, market: str, **options: Any) -> list[LiquidationLevel]:
+        """Get liquidations bucketed by price level (heatmap data)."""
+        raw = await self._http.get("/v1/analytics/liquidation-levels", {"market": market, **options})
+        return [_parse_liquidation_level(l) for l in raw["data"]]
+
+    async def order_flow(self, **options: Any) -> list[OrderFlow]:
+        """Get fill and cancel rates per market."""
+        raw = await self._http.get("/v1/analytics/order-flow", options)
+        return [_parse_order_flow(f) for f in raw["data"]]
+
+    async def vault_leaderboard(self, **options: Any) -> list[VaultLeaderboardEntry]:
+        """Get vaults ranked by net deposits."""
+        raw = await self._http.get("/v1/analytics/vault-leaderboard", options)
+        return [_parse_vault_leaderboard(v) for v in raw["data"]]
+
+    async def funding_stats(self, market: str, **options: Any) -> list[FundingStats]:
+        """Get funding rate statistics over time."""
+        raw = await self._http.get("/v1/analytics/funding-stats", {"market": market, **options})
+        return [_parse_funding_stats(f) for f in raw["data"]]
+
+    # ─── Status ────────────────────────────────────────────────────────
+
+    async def status(self) -> StatusResponse:
+        """Get system status and data freshness (unauthenticated)."""
+        raw = await self._http.get("/v1/status")
+        venues: dict[str, VenueStatus] = {}
+        for vname, vdata in raw.get("venues", {}).items():
+            streams = {
+                sname: StreamStatus(**sdata)
+                for sname, sdata in vdata.get("streams", {}).items()
+            }
+            venues[vname] = VenueStatus(streams=streams)
+        return StatusResponse(status=raw["status"], venues=venues)
+
+    # ─── Info API ───────────────────────────────────────────────────────
+
+    async def info(self, request: dict[str, Any]) -> Any:
+        """Proxy request to the Hyperliquid Info API."""
+        return await self._http.post("/v1/info", request)
+
+    # ─── Export ─────────────────────────────────────────────────────────
+
+    async def export_data(
+        self,
+        event_type: str,
+        *,
+        market: str | None = None,
+        from_ts: int | None = None,
+        to_ts: int | None = None,
+        format: str = "csv",
+    ) -> bytes:
+        """Export data as CSV or Parquet (Builder+ only). Returns raw bytes."""
+        params: dict[str, Any] = {"event_type": event_type, "format": format}
+        if market is not None:
+            params["market"] = market
+        if from_ts is not None:
+            params["from"] = from_ts
+        if to_ts is not None:
+            params["to"] = to_ts
+        return await self._http.get_raw("/v1/export", params)
+
+    # ─── Lifecycle ──────────────────────────────────────────────────────
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "Ironflow":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.close()
+
+    # ─── Helpers ────────────────────────────────────────────────────────
+
+    async def _paginated(
+        self,
+        path: str,
+        params: dict[str, Any],
+        parser: Any,
+    ) -> Page[Any]:
+        raw = await self._http.get(path, params)
+        data = [parser(item) for item in raw["data"]]
+        pagination = raw["pagination"]
+
+        async def fetch_next(cursor: str) -> Page[Any]:
+            return await self._paginated(path, {**params, "cursor": cursor}, parser)
+
+        return Page(
+            data=data,
+            has_more=pagination["has_more"],
+            next_cursor=pagination.get("next_cursor"),
+            next_fn=fetch_next,
+        )

ironflow_sdk/client.py

@@ -0,0 +1,134 @@
+# HTTP client for the Ironflow REST API. Uses httpx.
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Generic, Never, TypeVar
+
+import httpx
+
+from .errors import AuthError, IronflowError, QueryWindowError, QueryTimeoutError, QueryTooExpensiveError, RateLimitError, TierError
+
+DEFAULT_BASE_URL = "https://api.ironflow.sh"
+DEFAULT_SOURCE = "hyperliquid"
+SDK_VERSION = "0.1.0"
+
+T = TypeVar("T")
+
+
+class HttpClient:
+    """Thin httpx wrapper that handles auth, error mapping, and source injection."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        source: str = DEFAULT_SOURCE,
+        timeout: float = 30.0,
+    ) -> None:
+        self._api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.source = source
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": f"ironflow-sdk/{SDK_VERSION}",
+            },
+            timeout=timeout,
+        )
+
+    @property
+    def ws_url(self) -> str:
+        url = self.base_url.replace("https://", "wss://").replace("http://", "ws://")
+        return f"{url}/ws?api_key={self._api_key}"
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        """Send a GET request; inject source if absent."""
+        p = dict(params or {})
+        p.setdefault("source", self.source)
+        # Remove None values.
+        p = {k: v for k, v in p.items() if v is not None}
+        res = await self._client.get(path, params=p)
+        return self._handle(res)
+
+    async def post(self, path: str, body: Any) -> Any:
+        """Send a POST request with a JSON body."""
+        res = await self._client.post(path, json=body)
+        return self._handle(res)
+
+    async def patch(self, path: str, body: Any) -> Any:
+        """Send a PATCH request with a JSON body."""
+        res = await self._client.patch(path, json=body)
+        return self._handle(res)
+
+    async def delete(self, path: str) -> None:
+        """Send a DELETE request."""
+        res = await self._client.request("DELETE", path)
+        if not res.is_success:
+            self._raise_from(res)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def get_raw(self, path: str, params: dict[str, Any] | None = None) -> bytes:
+        """Send a GET request and return raw bytes (for binary exports)."""
+        p = dict(params or {})
+        p.setdefault("source", self.source)
+        p = {k: v for k, v in p.items() if v is not None}
+        res = await self._client.get(path, params=p)
+        if not res.is_success:
+            self._raise_from(res)
+        return res.content
+
+    def _handle(self, res: httpx.Response) -> Any:
+        if res.is_success:
+            return res.json()
+        self._raise_from(res)
+
+    def _raise_from(self, res: httpx.Response) -> "Never":
+        """Parse an error response and raise the appropriate typed exception."""
+        try:
+            err = res.json()
+            code = err.get("error", {}).get("code", "UNKNOWN")
+            message = err.get("error", {}).get("message", res.text)
+        except Exception:
+            code = "UNKNOWN"
+            message = res.text
+
+        if res.status_code == 400:
+            if code == "QUERY_WINDOW_EXCEEDED":
+                raise QueryWindowError(message)
+            if code == "QUERY_TOO_EXPENSIVE":
+                raise QueryTooExpensiveError(message)
+        if res.status_code == 401:
+            raise AuthError(message)
+        if res.status_code == 403:
+            raise TierError(message, code)
+        if res.status_code == 429:
+            retry_after = int(res.headers.get("Retry-After", "60"))
+            raise RateLimitError(message, retry_after * 1000)
+        if res.status_code == 504:
+            raise QueryTimeoutError(message)
+        raise IronflowError(message, code, res.status_code)
+
+
+class Page(Generic[T]):
+    """Paginated result with async next() support."""
+
+    def __init__(
+        self,
+        data: list[T],
+        has_more: bool,
+        next_cursor: str | None,
+        next_fn: Callable[[str], "Page[T]"] | None,
+    ) -> None:
+        self.data = data
+        self.has_more = has_more
+        self._next_cursor = next_cursor
+        self._next_fn = next_fn if has_more and next_cursor else None
+
+    async def next(self) -> "Page[T]":
+        """Fetch the next page. Raises if there are no more pages."""
+        if not self._next_fn or not self._next_cursor:
+            raise StopAsyncIteration("No more pages")
+        return await self._next_fn(self._next_cursor)

ironflow_sdk/errors.py

@@ -0,0 +1,53 @@
+# Typed exceptions for the Ironflow API.
+
+
+class IronflowError(Exception):
+    """Base class for all Ironflow API errors."""
+
+    def __init__(self, message: str, code: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+
+
+class RateLimitError(IronflowError):
+    """Raised when the API returns 429 Too Many Requests."""
+
+    def __init__(self, message: str, retry_after_ms: int) -> None:
+        super().__init__(message, "RATE_LIMIT_EXCEEDED", 429)
+        self.retry_after_ms = retry_after_ms
+
+
+class AuthError(IronflowError):
+    """Raised when the API returns 401 Unauthorized."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "UNAUTHORIZED", 401)
+
+
+class TierError(IronflowError):
+    """Raised when the API returns 403 Forbidden (tier insufficient)."""
+
+    def __init__(self, message: str, code: str = "TIER_FORBIDDEN") -> None:
+        super().__init__(message, code, 403)
+
+
+class QueryWindowError(IronflowError):
+    """Raised when the query time range exceeds the per-request maximum."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "QUERY_WINDOW_EXCEEDED", 400)
+
+
+class QueryTimeoutError(IronflowError):
+    """Raised when a query exceeds the server execution time limit (15s)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "QUERY_TIMEOUT", 504)
+
+
+class QueryTooExpensiveError(IronflowError):
+    """Raised when a query exceeds server resource limits (row/byte scan caps)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message, "QUERY_TOO_EXPENSIVE", 400)

ironflow_sdk/stream.py

@@ -0,0 +1,104 @@
+# WebSocket streaming for the Ironflow API.
+# Returns async generators for each channel.
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncGenerator
+from typing import Any, Callable, TypeVar
+
+from websockets.asyncio.client import connect
+
+T = TypeVar("T")
+
+from .types import (
+    BookLevel, BookSnapshot, Deposit, FundingRate, Liquidation,
+    OrderStatus, Trade, VaultOperation, Withdrawal,
+)
+
+
+def _parse_trade(d: dict[str, Any]) -> Trade:
+    return Trade(**d)
+
+
+def _parse_book(d: dict[str, Any]) -> BookSnapshot:
+    return BookSnapshot(
+        source=d["source"],
+        market=d["market"],
+        timestamp=d["timestamp"],
+        bids=[BookLevel(**b) for b in d["bids"]],
+        asks=[BookLevel(**a) for a in d["asks"]],
+    )
+
+
+class StreamClient:
+    """WebSocket streaming client. Each method returns an AsyncGenerator."""
+
+    def __init__(self, ws_url: str) -> None:
+        self._ws_url = ws_url
+
+    def trades(self, market: str, *, min_size: str | None = None) -> AsyncGenerator[Trade, None]:
+        opts: dict[str, Any] = {"channel": "trades", "market": market}
+        if min_size is not None:
+            opts["min_size"] = min_size
+        return self._subscribe(opts, _parse_trade)
+
+    def fills(self, address: str, *, market: str | None = None) -> AsyncGenerator[Trade, None]:
+        opts: dict[str, Any] = {"channel": "fills", "address": address}
+        if market is not None:
+            opts["market"] = market
+        return self._subscribe(opts, _parse_trade)
+
+    def book(self, market: str) -> AsyncGenerator[BookSnapshot, None]:
+        return self._subscribe({"channel": "book", "market": market}, _parse_book)
+
+    def book_l4(self, market: str, *, depth: int | None = None) -> AsyncGenerator[BookSnapshot, None]:
+        opts: dict[str, Any] = {"channel": "book_l4", "market": market}
+        if depth is not None:
+            opts["depth"] = depth
+        return self._subscribe(opts, _parse_book)
+
+    def orders(self, address: str) -> AsyncGenerator[OrderStatus, None]:
+        return self._subscribe({"channel": "orders", "address": address}, lambda d: OrderStatus(**d))
+
+    def liquidations(self, market: str) -> AsyncGenerator[Liquidation, None]:
+        return self._subscribe({"channel": "liquidations", "market": market}, lambda d: Liquidation(**d))
+
+    def funding_rates(self, market: str) -> AsyncGenerator[FundingRate, None]:
+        return self._subscribe({"channel": "funding_rate", "market": market}, lambda d: FundingRate(**d))
+
+    def deposits(self, *, address: str | None = None) -> AsyncGenerator[Deposit, None]:
+        opts: dict[str, Any] = {"channel": "deposits"}
+        if address is not None:
+            opts["address"] = address
+        return self._subscribe(opts, lambda d: Deposit(**d))
+
+    def withdrawals(self, *, address: str | None = None) -> AsyncGenerator[Withdrawal, None]:
+        opts: dict[str, Any] = {"channel": "withdrawals"}
+        if address is not None:
+            opts["address"] = address
+        return self._subscribe(opts, lambda d: Withdrawal(**d))
+
+    def vault_operations(self, *, address: str | None = None, vault: str | None = None) -> AsyncGenerator[VaultOperation, None]:
+        opts: dict[str, Any] = {"channel": "vault_operations"}
+        if address is not None:
+            opts["address"] = address
+        if vault is not None:
+            opts["vault"] = vault
+        return self._subscribe(opts, lambda d: VaultOperation(**d))
+
+    async def _subscribe(self, options: dict[str, Any], parser: Callable[[dict[str, Any]], Any]) -> AsyncGenerator[Any, None]:
+        sub_msg = {"op": "subscribe", **options}
+        async with connect(self._ws_url) as ws:
+            await ws.send(json.dumps(sub_msg))
+            async for raw in ws:
+                try:
+                    msg = json.loads(raw)
+                    if msg.get("op") == "ping":
+                        await ws.send(json.dumps({"op": "pong"}))
+                        continue
+                    if msg.get("op") != "data":
+                        continue
+                    yield parser(msg["data"])
+                except (json.JSONDecodeError, KeyError):
+                    continue

ironflow_sdk/types.py

@@ -0,0 +1,247 @@
+# Response dataclasses for the Ironflow API.
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class Trade:
+    source: str
+    market: str
+    market_type: str
+    timestamp: int
+    block_number: int
+    sequence: int
+    price: str
+    size: str
+    side: str
+    address: str
+    fee: str
+    realized_pnl: str
+    hash: str
+
+
+@dataclass
+class BookLevel:
+    price: str
+    size: str
+
+
+@dataclass
+class BookSnapshot:
+    source: str
+    market: str
+    timestamp: int
+    bids: list[BookLevel]
+    asks: list[BookLevel]
+
+
+@dataclass
+class Candle:
+    source: str
+    market: str
+    interval: str
+    timestamp: int
+    open: str
+    high: str
+    low: str
+    close: str
+    volume: str
+    trade_count: int
+
+
+@dataclass
+class FundingRate:
+    source: str
+    market: str
+    timestamp: int
+    block_number: int
+    rate: str
+
+
+@dataclass
+class Liquidation:
+    source: str
+    market: str
+    timestamp: int
+    block_number: int
+    address: str
+    size: str
+    price: str
+    side: str
+
+
+@dataclass
+class OpenInterest:
+    source: str
+    market: str
+    timestamp: int
+    open_interest: str
+    volume_24h: str
+
+
+@dataclass
+class MarkPrice:
+    source: str
+    market: str
+    timestamp: int
+    mark_price: str
+    oracle_price: str
+    funding_rate: str
+
+
+@dataclass
+class Deposit:
+    source: str
+    timestamp: int
+    block_number: int
+    address: str
+    token: str
+    amount: str
+
+
+@dataclass
+class Withdrawal:
+    source: str
+    timestamp: int
+    block_number: int
+    address: str
+    token: str
+    amount: str
+
+
+@dataclass
+class OrderStatus:
+    source: str
+    market: str
+    timestamp: int
+    address: str
+    order_id: str
+    status: str
+    side: str
+    price: str
+    size: str
+
+
+# ─── Vault Operations ─────────────────────────────────────────────────
+
+
+@dataclass
+class VaultOperation:
+    source: str
+    timestamp: int
+    block_number: int
+    vault: str
+    address: str
+    operation: str
+    amount: str
+
+
+# ─── Triggers ─────────────────────────────────────────────────────────
+
+
+@dataclass
+class Trigger:
+    id: int
+    user_id: int
+    name: str
+    channel: str
+    rule: dict[str, Any]
+    webhook_url: str
+    is_active: bool
+    created_at: str = ""
+
+
+# ─── Cohorts ──────────────────────────────────────────────────────────
+
+
+@dataclass
+class CohortInfo:
+    name: str
+    type: str
+    address_count: int
+
+
+@dataclass
+class CohortAddressEntry:
+    address: str
+    label: str | None = None
+
+
+@dataclass
+class CohortAddresses:
+    addresses: list[CohortAddressEntry]
+    fetched_at: int
+
+
+# ─── Analytics ────────────────────────────────────────────────────────
+
+
+@dataclass
+class NetFlow:
+    source: str
+    address: str
+    bucket: int
+    deposits: str
+    withdrawals: str
+    net_flow: str
+
+
+@dataclass
+class LiquidationLevel:
+    source: str
+    market: str
+    price_bucket: str
+    side: str
+    count: int
+    total_size: str
+
+
+@dataclass
+class OrderFlow:
+    source: str
+    market: str
+    total_orders: int
+    filled_orders: int
+    cancelled: int
+    fill_rate: str
+
+
+@dataclass
+class VaultLeaderboardEntry:
+    source: str
+    vault: str
+    total_deposits: str
+    total_withdrawals: str
+    net_flow: str
+    unique_users: int
+
+
+@dataclass
+class FundingStats:
+    source: str
+    market: str
+    bucket: int
+    avg_rate: str
+    min_rate: str
+    max_rate: str
+    cumulative_rate: str
+
+
+@dataclass
+class StreamStatus:
+    latest_timestamp: int
+    age_seconds: float
+
+
+@dataclass
+class VenueStatus:
+    streams: dict[str, StreamStatus]
+
+
+@dataclass
+class StatusResponse:
+    status: str
+    venues: dict[str, VenueStatus]

ironflow_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: ironflow-sdk
+Version: 0.1.0
+Summary: Python SDK for Ironflow market data API — on-chain derivatives data
+Project-URL: Homepage, https://ironflow.sh
+Project-URL: Documentation, https://docs.ironflow.sh
+Project-URL: Support, https://docs.ironflow.sh
+Author-email: Ironflow <hello@ironflow.sh>
+License: MIT
+License-File: LICENSE
+Keywords: crypto,defi,hyperliquid,ironflow,market-data,perpetuals,sdk,trading,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ironflow
+
+Python SDK for the [Ironflow](https://ironflow.sh) market data API — on-chain derivatives data.
+
+- Async-first with `httpx` and `websockets`
+- Typed dataclass responses for all endpoints
+- Automatic pagination with `await page.next()`
+- Typed WebSocket streams with async generators
+- Full type annotations (`py.typed`)
+
+## Install
+
+```bash
+pip install ironflow-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from ironflow_sdk import Ironflow
+
+async with Ironflow("if_your_api_key") as client:
+    # Get recent trades
+    page = await client.trades("BTC-PERP", limit=10)
+    for trade in page.data:
+        print(trade.price, trade.size, trade.side)
+
+    # Paginate
+    if page.has_more:
+        next_page = await page.next()
+```
+
+## Configuration
+
+```python
+client = Ironflow(
+    "if_your_api_key",
+    base_url="https://api.ironflow.sh",  # default
+    source="hyperliquid",                # default
+    timeout=30.0,                        # request timeout in seconds (default: 30)
+)
+```
+
+## REST Endpoints
+
+### Market Data
+
+```python
+async with Ironflow("if_your_api_key") as client:
+    # Trades
+    trades = await client.trades("BTC-PERP", limit=100)
+
+    # Fills (requires address)
+    fills = await client.fills("0xabc...", market="ETH-PERP")
+
+    # Order book snapshot
+    book = await client.book("BTC-PERP")
+    # book.bids[0].price, book.bids[0].size
+
+    # OHLCV candles
+    candles = await client.candles("BTC-PERP", "1h", limit=24)
+
+    # Liquidations
+    liqs = await client.liquidations("BTC-PERP")
+
+    # Funding rates
+    rates = await client.funding("BTC-PERP")
+
+    # Open interest
+    oi = await client.open_interest("BTC-PERP")
+
+    # Mark prices
+    prices = await client.mark_prices("BTC-PERP")
+
+    # Deposits & withdrawals
+    deps = await client.deposits(address="0xabc...")
+    wds = await client.withdrawals(address="0xabc...")
+
+    # Order statuses
+    orders = await client.order_statuses(address="0xabc...")
+
+    # Vault operations
+    vaults = await client.vault_operations(vault="HLP")
+```
+
+### Analytics (Builder+)
+
+```python
+flows = await client.net_flows(interval="1d", limit=7)
+# flows[0].deposits, flows[0].withdrawals, flows[0].net_flow
+
+levels = await client.liquidation_levels("BTC-PERP", bucket_size=100)
+# levels[0].price_bucket, levels[0].count, levels[0].total_size
+
+order_flow = await client.order_flow()
+# order_flow[0].total_orders, order_flow[0].filled_orders, order_flow[0].fill_rate
+
+leaderboard = await client.vault_leaderboard()
+# leaderboard[0].vault, leaderboard[0].total_deposits, leaderboard[0].net_flow
+
+funding = await client.funding_stats("BTC-PERP", interval="8h")
+# funding[0].avg_rate, funding[0].min_rate, funding[0].max_rate
+```
+
+### Triggers
+
+```python
+# Create a webhook trigger
+trigger = await client.create_trigger(
+    name="whale-alert",
+    channel="trades",
+    webhook_url="https://your-server.com/hook",
+    rule={"condition": {"field": "data.size", "op": "gt", "value": "100"}},
+)
+
+# List, toggle, delete
+triggers = await client.list_triggers()
+await client.toggle_trigger(trigger.id, is_active=False)
+await client.delete_trigger(trigger.id)
+
+# Test a rule without creating
+matched = await client.test_trigger(
+    rule={"condition": {"field": "data.size", "op": "gt", "value": "10"}},
+    event={"data": {"size": "50", "market": "BTC-PERP"}},
+)
+print(matched)  # True
+```
+
+### Cohorts (Enterprise)
+
+```python
+cohorts = await client.list_cohorts()
+addrs = await client.cohort_addresses("top_pnl_30d")
+await client.create_cohort("my_whales", ["0xabc...", "0xdef..."])
+await client.delete_cohort("my_whales")
+```
+
+### Export (Builder+)
+
+```python
+data = await client.export_data(
+    "fills",
+    market="BTC-PERP",
+    format="csv",
+)
+# data is bytes — write to file or parse with pandas
+import pandas as pd
+df = pd.read_csv(io.BytesIO(data))
+```
+
+### Status
+
+```python
+status = await client.status()
+print(status.status)  # "ok"
+print(status.venues["hyperliquid"].streams["fills"].age_seconds)
+```
+
+### Info API Proxy
+
+```python
+meta = await client.info({"type": "metaAndAssetCtxs"})
+```
+
+## WebSocket Streaming
+
+All stream methods return typed async generators:
+
+```python
+# Real-time trades
+async for trade in client.stream.trades("BTC-PERP"):
+    print(trade.price, trade.size, trade.side)
+
+# Wallet fills (copy trading)
+async for fill in client.stream.fills("0xleader"):
+    print(fill.side, fill.size, fill.market)
+
+# Order book updates
+async for snap in client.stream.book("ETH-PERP"):
+    print(snap.bids[0].price, snap.asks[0].price)
+
+# Filter by minimum size
+async for trade in client.stream.trades("BTC-PERP", min_size="10"):
+    pass  # Only trades >= 10 BTC
+```
+
+Available streams: `trades`, `fills`, `book`, `book_l4`, `orders`, `liquidations`, `funding_rates`, `deposits`, `withdrawals`, `vault_operations`.
+
+## Error Handling
+
+```python
+from ironflow_sdk import Ironflow, RateLimitError, AuthError, TierError, QueryWindowError
+
+try:
+    trades = await client.trades("BTC-PERP")
+except RateLimitError as e:
+    print(f"Rate limited, retry in {e.retry_after_ms}ms")
+except AuthError:
+    print("Invalid API key")
+except TierError:
+    print("Upgrade your plan for this endpoint")
+except QueryWindowError:
+    print("Time range too wide for your tier")
+```
+
+## Pagination
+
+All list endpoints return a `Page[T]` with async pagination:
+
+```python
+page = await client.trades("BTC-PERP", limit=1000)
+all_trades = list(page.data)
+
+while page.has_more:
+    page = await page.next()
+    all_trades.extend(page.data)
+```
+
+## License
+
+MIT

ironflow_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+ironflow_sdk/__init__.py,sha256=PHptmK6i0cHiL6BdssUw_mIA8q8MU0eMdRHXr1NYXOs,14184
+ironflow_sdk/client.py,sha256=KC9c4pWKVKzjIHXVpLkSKYW7SerHFqAmZlp_vqsZH8I,4704
+ironflow_sdk/errors.py,sha256=2PftqamRBmYG3-Q9W3wuIDRB2RHl5rp1JmtiJhbAXR4,1669
+ironflow_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ironflow_sdk/stream.py,sha256=y8FYdZ2MplwZIRqZs7MAKKllpxCNpgWJMbDHvAZ1UuU,4206
+ironflow_sdk/types.py,sha256=UUtyySCDuSO3OKfXbkDh1mWpKzldwwlJD2zZaT4-qKE,4117
+ironflow_sdk-0.1.0.dist-info/METADATA,sha256=y2wkQBaI9GuYAcXMP_dOAhW5aTvxEPqMS6UZnr1su1c,6778
+ironflow_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+ironflow_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=KpKyQ8NIAi5ndZ8RVkSkdOUrs6UnEehu7fOvF3_MhPE,1065
+ironflow_sdk-0.1.0.dist-info/RECORD,,

ironflow_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ironflow_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ironflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.