chain-analysis 0.1.0__tar.gz

chain_analysis-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.env
+data/
+*.duckdb
+*.duckdb.wal

chain_analysis-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: chain-analysis
+Version: 0.1.0
+Summary: Python client for the Horatio Chain Analysis service
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: polars>=1.0

chain_analysis-0.1.0/chain_analysis/__init__.py

@@ -0,0 +1,3 @@
+from .client import ChainAnalysisClient
+
+__all__ = ["ChainAnalysisClient"]

chain_analysis-0.1.0/chain_analysis/client.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import io
+from typing import Optional
+
+import httpx
+import polars as pl
+
+
+class ChainAnalysisClient:
+    """Client for the Horatio Chain Analysis service."""
+
+    def __init__(self, url: str, user: str = "admin", password: str = "admin"):
+        self._url = url.rstrip("/")
+        self._user = user
+        self._password = password
+        self._session = httpx.AsyncClient(timeout=600)
+        self.wallets = WalletNamespace(self)
+
+    def _auth(self) -> dict[str, str]:
+        import base64
+        encoded = base64.b64encode(f"{self._user}:{self._password}".encode()).decode()
+        return {"Authorization": f"Basic {encoded}"}
+
+    async def health(self) -> bool:
+        res = await self._session.get(f"{self._url}/health", headers=self._auth())
+        res.raise_for_status()
+        return True
+
+    async def close(self) -> None:
+        await self._session.aclose()
+
+    async def __aenter__(self) -> ChainAnalysisClient:
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()
+
+
+class WalletNamespace:
+    """Wallet operations."""
+
+    def __init__(self, client: ChainAnalysisClient):
+        self._client = client
+
+    async def query(
+        self,
+        *,
+        network: Optional[str | list[str]] = None,
+        entity: Optional[str | list[str]] = None,
+        categories: Optional[list[str]] = None,
+        labels: Optional[list[str]] = None,
+    ) -> pl.DataFrame:
+        """Query wallets by filters. Returns DataFrame with 'address' column.
+
+        Args:
+            network: Filter by network type (e.g. 'EVM', 'TRON'). Single or list.
+            entity: Filter by entity name (exact, case-insensitive). Single or list.
+            categories: Wallet must have ALL listed categories.
+            labels: Wallet must have ALL listed labels.
+
+        Returns:
+            Polars DataFrame with single 'address' column.
+        """
+        body: dict = {"format": "parquet"}
+        if network is not None:
+            body["network"] = network
+        if entity is not None:
+            body["entity"] = entity
+        if categories is not None:
+            body["categories"] = categories
+        if labels is not None:
+            body["labels"] = labels
+
+        res = await self._client._session.post(
+            f"{self._client._url}/api/wallets/query",
+            json=body,
+            headers={**self._client._auth(), "Content-Type": "application/json"},
+        )
+        res.raise_for_status()
+        return pl.read_parquet(io.BytesIO(res.content))
+
+    async def get(self, address: str) -> dict:
+        """Get a single wallet's details.
+
+        Returns:
+            Dict with keys: wallet, network, entity, categories, labels.
+        """
+        res = await self._client._session.get(
+            f"{self._client._url}/api/wallets/{address}",
+            headers=self._client._auth(),
+        )
+        res.raise_for_status()
+        return res.json()
+
+    async def create(
+        self,
+        wallet: str,
+        *,
+        entity: Optional[str] = None,
+        categories: Optional[list[str]] = None,
+        labels: Optional[list[str]] = None,
+    ) -> dict:
+        """Create a new wallet entry.
+
+        Returns:
+            Dict with the created wallet details.
+        """
+        body: dict = {"wallet": wallet}
+        if entity is not None:
+            body["entity"] = entity
+        if categories is not None:
+            body["categories"] = categories
+        if labels is not None:
+            body["labels"] = labels
+        res = await self._client._session.post(
+            f"{self._client._url}/api/wallets",
+            json=body,
+            headers={**self._client._auth(), "Content-Type": "application/json"},
+        )
+        res.raise_for_status()
+        return res.json()
+
+    async def update(
+        self,
+        address: str,
+        *,
+        entity: Optional[str] = None,
+        categories: Optional[list[str]] = None,
+        labels: Optional[list[str]] = None,
+    ) -> dict:
+        """Update a wallet's entity, categories, or labels.
+
+        Returns:
+            Dict with the updated wallet details.
+        """
+        body: dict = {}
+        if entity is not None:
+            body["entity"] = entity
+        if categories is not None:
+            body["categories"] = categories
+        if labels is not None:
+            body["labels"] = labels
+        res = await self._client._session.put(
+            f"{self._client._url}/api/wallets/{address}",
+            json=body,
+            headers={**self._client._auth(), "Content-Type": "application/json"},
+        )
+        res.raise_for_status()
+        return res.json()
+
+    async def delete(self, address: str) -> dict:
+        """Delete a wallet entry."""
+        res = await self._client._session.delete(
+            f"{self._client._url}/api/wallets/{address}",
+            headers=self._client._auth(),
+        )
+        res.raise_for_status()
+        return res.json()
+
+    async def bulk_update(
+        self,
+        addresses: list[str],
+        *,
+        add_categories: Optional[list[str]] = None,
+        remove_categories: Optional[list[str]] = None,
+        add_labels: Optional[list[str]] = None,
+        remove_labels: Optional[list[str]] = None,
+        entity: Optional[str] = None,
+    ) -> dict:
+        """Bulk add/remove categories or labels for multiple wallets.
+
+        Returns:
+            Dict with 'updated' count.
+        """
+        body: dict = {"addresses": addresses}
+        if add_categories:
+            body["add_categories"] = add_categories
+        if remove_categories:
+            body["remove_categories"] = remove_categories
+        if add_labels:
+            body["add_labels"] = add_labels
+        if remove_labels:
+            body["remove_labels"] = remove_labels
+        if entity is not None:
+            body["entity"] = entity
+        res = await self._client._session.post(
+            f"{self._client._url}/api/cex/bulk-update",
+            json=body,
+            headers={**self._client._auth(), "Content-Type": "application/json"},
+        )
+        res.raise_for_status()
+        return res.json()
+
+    async def distinct(self) -> dict:
+        """Get all distinct entities, categories, and labels.
+
+        Returns:
+            Dict with keys: entities, categories, labels (each a list of str).
+        """
+        res = await self._client._session.get(
+            f"{self._client._url}/api/wallets/distinct",
+            headers=self._client._auth(),
+        )
+        res.raise_for_status()
+        return res.json()

chain_analysis-0.1.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "chain-analysis"
+version = "0.1.0"
+description = "Python client for the Horatio Chain Analysis service"
+requires-python = ">=3.10"
+dependencies = [
+    "httpx>=0.25",
+    "polars>=1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"