kricket-client 0.1.0__tar.gz

kricket_client-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Rust
+/core/target/
+**/*.rs.bk
+
+# Go
+/services/*/vendor/
+# Build artifacts — each service builds a binary matching its directory name
+/services/gateway/gateway
+/services/pulse-api/pulse-api
+/services/mantis-api/mantis-api
+/services/firefly-api/firefly-api
+/services/chirps/chirps
+/services/status/status
+/services/hub-sidecar/cricket-hub-sidecar
+# One-off CLI binaries — rebuild via `go build -o services/mint-backfill ./services/gateway/cmd/mint-backfill`
+/services/mint-backfill
+
+# TypeScript / Node
+node_modules/
+dist/
+*.tsbuildinfo
+
+# Environment
+.env
+.env.local
+.env.production
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Playwright MCP artifacts
+.playwright-mcp/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+docker-compose.override.yml
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+
+# Secrets
+*.pem
+*.key
+cricket-admin/.env

kricket_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VYLTH
+
+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.

kricket_client-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: kricket-client
+Version: 0.1.0
+Summary: Python client for Kricket Protocol: DeFi intelligence and execution suite
+Project-URL: Homepage, https://github.com/VYLTH/kricket
+Project-URL: Repository, https://github.com/VYLTH/kricket
+Author: VYLTH
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,defi,kricket,solana,web3
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# kricket-client
+
+Async Python client for the [Kricket Protocol](https://cricket.vylth.com) — DeFi intelligence APIs for rug detection, wallet profiling, price feeds, smart contract analysis, and notifications.
+
+Requires Python 3.10+. All methods are async.
+
+## Installation
+
+```bash
+pip install kricket-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from kricket_client import KricketClient
+
+async def main():
+    async with KricketClient(api_key="your-api-key") as kricket:
+        # Scan a token for rug-pull risk
+        result = await kricket.mantis.scan("TOKEN_ADDRESS")
+        print(result.risk_score.rating)  # 'low' | 'moderate' | 'high' | 'critical'
+        print(result.risk_score.score)   # 0–100
+
+        # Get a wallet intelligence profile
+        wallet = await kricket.firefly.get_wallet("WALLET_ADDRESS")
+        print(wallet.score, wallet.style, wallet.win_rate)
+
+asyncio.run(main())
+```
+
+## Clients
+
+| Client | Description | Key Methods |
+|--------|-------------|-------------|
+| `kricket.mantis` | Rug-pull detection & token risk scoring | `scan(token)`, `get_score(token)`, `add_to_watchlist(tokens)`, `get_watchlist()` |
+| `kricket.firefly` | Wallet intelligence & smart money signals | `get_wallet(address)`, `get_signals()`, `get_leaderboard()`, `track(address)` |
+| `kricket.pulse` | Unified price feeds (CEX + DEX) | `get_price(symbol)`, `get_spread(symbol)` |
+| `kricket.chirps` | Notification channel management | `list_channels()`, `create_channel(config)`, `delete_channel(id)` |
+| `kricket.debugger` | Smart contract vulnerability analysis | `analyze(source, language)` |
+
+## Configuration
+
+```python
+from kricket_client import KricketClient, KricketConfig
+
+config = KricketConfig(
+    api_key="your-api-key",
+    base_url="https://api-cricket.vylth.com/api/kricket",  # optional override
+    timeout=30.0,  # seconds, default 30
+)
+kricket = KricketClient(config)
+```
+
+## Error Handling
+
+```python
+from kricket_client import KricketError
+
+try:
+    result = await kricket.mantis.scan(token)
+except KricketError as e:
+    print(e.code, e.message, e.status)
+```
+
+## Full Docs
+
+[cricket.vylth.com/docs](https://cricket.vylth.com/docs)

kricket_client-0.1.0/README.md

@@ -0,0 +1,69 @@
+# kricket-client
+
+Async Python client for the [Kricket Protocol](https://cricket.vylth.com) — DeFi intelligence APIs for rug detection, wallet profiling, price feeds, smart contract analysis, and notifications.
+
+Requires Python 3.10+. All methods are async.
+
+## Installation
+
+```bash
+pip install kricket-client
+```
+
+## Quick Start
+
+```python
+import asyncio
+from kricket_client import KricketClient
+
+async def main():
+    async with KricketClient(api_key="your-api-key") as kricket:
+        # Scan a token for rug-pull risk
+        result = await kricket.mantis.scan("TOKEN_ADDRESS")
+        print(result.risk_score.rating)  # 'low' | 'moderate' | 'high' | 'critical'
+        print(result.risk_score.score)   # 0–100
+
+        # Get a wallet intelligence profile
+        wallet = await kricket.firefly.get_wallet("WALLET_ADDRESS")
+        print(wallet.score, wallet.style, wallet.win_rate)
+
+asyncio.run(main())
+```
+
+## Clients
+
+| Client | Description | Key Methods |
+|--------|-------------|-------------|
+| `kricket.mantis` | Rug-pull detection & token risk scoring | `scan(token)`, `get_score(token)`, `add_to_watchlist(tokens)`, `get_watchlist()` |
+| `kricket.firefly` | Wallet intelligence & smart money signals | `get_wallet(address)`, `get_signals()`, `get_leaderboard()`, `track(address)` |
+| `kricket.pulse` | Unified price feeds (CEX + DEX) | `get_price(symbol)`, `get_spread(symbol)` |
+| `kricket.chirps` | Notification channel management | `list_channels()`, `create_channel(config)`, `delete_channel(id)` |
+| `kricket.debugger` | Smart contract vulnerability analysis | `analyze(source, language)` |
+
+## Configuration
+
+```python
+from kricket_client import KricketClient, KricketConfig
+
+config = KricketConfig(
+    api_key="your-api-key",
+    base_url="https://api-cricket.vylth.com/api/kricket",  # optional override
+    timeout=30.0,  # seconds, default 30
+)
+kricket = KricketClient(config)
+```
+
+## Error Handling
+
+```python
+from kricket_client import KricketError
+
+try:
+    result = await kricket.mantis.scan(token)
+except KricketError as e:
+    print(e.code, e.message, e.status)
+```
+
+## Full Docs
+
+[cricket.vylth.com/docs](https://cricket.vylth.com/docs)

kricket_client-0.1.0/kricket_client/__init__.py

@@ -0,0 +1,8 @@
+"""Kricket Protocol Python Client: DeFi intelligence and execution suite."""
+
+from kricket_client.client import KricketClient, KricketConfig
+from kricket_client.types import *  # noqa: F401,F403
+from kricket_client.exceptions import KricketError
+
+__all__ = ["KricketClient", "KricketConfig", "KricketError"]
+__version__ = "0.1.0"

kricket_client-0.1.0/kricket_client/chirps.py

@@ -0,0 +1,36 @@
+"""Chirps API client: notification channel management."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from kricket_client.http import HttpClient
+from kricket_client.types import ChirpChannel, ChirpRecord
+
+
+class ChirpsClient:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def create_channel(self, channel: dict) -> ChirpChannel:
+        """Create a notification channel."""
+        data = await self._http.post("/chirps/channels", json=channel)
+        return ChirpChannel(**data)
+
+    async def list_channels(self) -> list[ChirpChannel]:
+        """List all notification channels."""
+        data = await self._http.get("/chirps/channels")
+        return [ChirpChannel(**c) for c in data]
+
+    async def delete_channel(self, channel_id: str) -> None:
+        """Delete a notification channel."""
+        await self._http.delete(f"/chirps/channels/{quote(channel_id)}")
+
+    async def test_channel(self, channel_id: str) -> dict:
+        """Send a test chirp to verify channel configuration."""
+        return await self._http.post(f"/chirps/test/{quote(channel_id)}")
+
+    async def get_history(self) -> list[ChirpRecord]:
+        """Get notification delivery history."""
+        data = await self._http.get("/chirps/history")
+        return [ChirpRecord(**r) for r in data]

kricket_client-0.1.0/kricket_client/client.py

@@ -0,0 +1,164 @@
+"""Main Kricket client: unified entry point for all API modules."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import AsyncIterator, Optional
+from urllib.parse import quote
+
+import httpx
+
+from kricket_client.exceptions import KricketError
+from kricket_client.http import HttpClient
+from kricket_client.types import CheckResponse, WatchEvent
+from kricket_client.pulse import PulseClient
+from kricket_client.mantis import MantisClient
+from kricket_client.firefly import FireflyClient
+from kricket_client.chirps import ChirpsClient
+from kricket_client.debugger import DebuggerClient
+
+
+@dataclass
+class KricketConfig:
+    """Configuration for the Kricket client."""
+
+    base_url: str = "https://api-cricket.vylth.com/api/cricket"
+    api_key: str = ""
+    timeout: float = 30.0
+    # Intel REST base for the one-call check()/guard()/watch() surface.
+    intel_url: str = "https://api-cricket.vylth.com"
+
+
+class KricketClient:
+    """Unified client for Kricket Protocol APIs."""
+
+    def __init__(self, config: KricketConfig | None = None, **kwargs):
+        cfg = config or KricketConfig(**kwargs)
+        self._http = HttpClient(cfg.base_url, cfg.api_key, cfg.timeout)
+        self._intel_url = cfg.intel_url.rstrip("/")
+        self._api_key = cfg.api_key
+        self._timeout = cfg.timeout
+        self._intel: httpx.AsyncClient | None = None
+        self._pulse: PulseClient | None = None
+        self._mantis: MantisClient | None = None
+        self._firefly: FireflyClient | None = None
+        self._chirps: ChirpsClient | None = None
+        self._debugger: DebuggerClient | None = None
+
+    def _intel_client(self) -> httpx.AsyncClient:
+        if self._intel is None:
+            self._intel = httpx.AsyncClient(
+                base_url=self._intel_url,
+                headers={"X-API-Key": self._api_key},
+                timeout=self._timeout,
+            )
+        return self._intel
+
+    async def check(self, chain: str, address: str) -> CheckResponse:
+        """One-call safety check for an address. The drop-in: is it safe to touch?
+
+        Returns the raw verdict; raises :class:`KricketError` with the server
+        reason on a non-ok response.
+        """
+        resp = await self._intel_client().get(
+            f"/v1/check/{quote(chain, safe='')}/{quote(address, safe='')}"
+        )
+        if resp.status_code != 200:
+            reason = f"HTTP {resp.status_code}"
+            try:
+                body = resp.json()
+                if isinstance(body, dict) and body.get("reason"):
+                    reason = body["reason"]
+            except Exception:
+                pass  # non-JSON error body
+            raise KricketError("CHECK_FAILED", reason, resp.status_code)
+        return CheckResponse(**resp.json())
+
+    async def guard(
+        self, chain: str, address: str, fail_open: bool = False
+    ) -> Optional[CheckResponse]:
+        """Pre-sign guard — one line in a signing hook.
+
+        Returns the verdict when cleared; **raises** ``KricketError('BLOCKED')``
+        when not, so the transaction is never signed. Fail-closed by default: if
+        the engine is unreachable the error propagates (caller does not sign).
+        Pass ``fail_open=True`` to instead return ``None`` on an engine error —
+        an explicit danger verdict still raises.
+        """
+        try:
+            verdict = await self.check(chain, address)
+        except KricketError:
+            if fail_open:
+                return None  # engine unreachable — caller chose to allow
+            raise  # fail closed: cannot verify -> do not sign
+        if not verdict.cleared:
+            raise KricketError("BLOCKED", verdict.reason, 403)  # explicit danger always blocks
+        return verdict
+
+    async def watch(
+        self, addresses: Optional[list[str]] = None
+    ) -> AsyncIterator[WatchEvent]:
+        """Subscribe to live revocations — yields a :class:`WatchEvent` the instant
+        a watched address turns dangerous. Pass ``None`` to watch everything; break
+        out of the loop to unsubscribe.
+        """
+        params = {"addresses": ",".join(addresses)} if addresses else None
+        async with self._intel_client().stream(
+            "GET", "/v1/watch", params=params, headers={"Accept": "text/event-stream"}
+        ) as resp:
+            if resp.status_code != 200:
+                raise KricketError("WATCH_FAILED", f"HTTP {resp.status_code}", resp.status_code)
+            buf = ""
+            async for chunk in resp.aiter_text():
+                buf += chunk
+                while "\n\n" in buf:
+                    block, buf = buf.split("\n\n", 1)
+                    for line in block.split("\n"):
+                        if line.startswith("data:"):
+                            try:
+                                yield WatchEvent(**json.loads(line[5:].strip()))
+                            except Exception:
+                                pass  # skip malformed event
+
+    @property
+    def pulse(self) -> PulseClient:
+        if self._pulse is None:
+            self._pulse = PulseClient(self._http)
+        return self._pulse
+
+    @property
+    def mantis(self) -> MantisClient:
+        if self._mantis is None:
+            self._mantis = MantisClient(self._http)
+        return self._mantis
+
+    @property
+    def firefly(self) -> FireflyClient:
+        if self._firefly is None:
+            self._firefly = FireflyClient(self._http)
+        return self._firefly
+
+    @property
+    def chirps(self) -> ChirpsClient:
+        if self._chirps is None:
+            self._chirps = ChirpsClient(self._http)
+        return self._chirps
+
+    @property
+    def debugger(self) -> DebuggerClient:
+        if self._debugger is None:
+            self._debugger = DebuggerClient(self._http)
+        return self._debugger
+
+    async def close(self) -> None:
+        """Close the underlying HTTP clients."""
+        await self._http.close()
+        if self._intel is not None:
+            await self._intel.aclose()
+
+    async def __aenter__(self) -> KricketClient:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

kricket_client-0.1.0/kricket_client/debugger.py

@@ -0,0 +1,19 @@
+"""Debugger API client: smart contract vulnerability scanning."""
+
+from __future__ import annotations
+
+from kricket_client.http import HttpClient
+from kricket_client.types import AnalysisResult, Language
+
+
+class DebuggerClient:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def analyze(self, source: str, language: Language | str) -> AnalysisResult:
+        """Analyze source code for vulnerabilities and gas optimizations."""
+        data = await self._http.post(
+            "/debugger/analyze",
+            json={"source": source, "language": language.value if hasattr(language, "value") else str(language)},
+        )
+        return AnalysisResult(**data)

kricket_client-0.1.0/kricket_client/exceptions.py

@@ -0,0 +1,11 @@
+"""Kricket API exceptions."""
+
+
+class KricketError(Exception):
+    """Raised when the Kricket API returns an error."""
+
+    def __init__(self, code: str, message: str, status: int):
+        self.code = code
+        self.message = message
+        self.status = status
+        super().__init__(f"[{code}] {message} (HTTP {status})")

kricket_client-0.1.0/kricket_client/firefly.py

@@ -0,0 +1,32 @@
+"""Firefly API client: wallet intelligence and smart money signals."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from kricket_client.http import HttpClient
+from kricket_client.types import WalletProfile, Signal
+
+
+class FireflyClient:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def get_wallet(self, address: str) -> WalletProfile:
+        """Get a wallet's intelligence profile."""
+        data = await self._http.get(f"/firefly/wallet/{quote(address)}")
+        return WalletProfile(**data)
+
+    async def get_signals(self) -> list[Signal]:
+        """Get active smart money signals."""
+        data = await self._http.get("/firefly/signals")
+        return [Signal(**s) for s in data]
+
+    async def get_leaderboard(self) -> list[WalletProfile]:
+        """Get the top wallets leaderboard."""
+        data = await self._http.get("/firefly/leaderboard")
+        return [WalletProfile(**w) for w in data]
+
+    async def track(self, address: str) -> dict:
+        """Start tracking a wallet."""
+        return await self._http.post("/firefly/track", json={"address": address})

kricket_client-0.1.0/kricket_client/http.py

@@ -0,0 +1,53 @@
+"""Base HTTP client for Kricket API."""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import httpx
+
+from kricket_client.exceptions import KricketError
+
+T = TypeVar("T")
+
+
+class HttpClient:
+    """Async HTTP client with API key auth and error handling."""
+
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0):
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers={
+                "Content-Type": "application/json",
+                "X-API-Key": api_key,
+            },
+            timeout=timeout,
+        )
+
+    async def get(self, path: str) -> Any:
+        return await self._request("GET", path)
+
+    async def post(self, path: str, json: Any = None) -> Any:
+        return await self._request("POST", path, json=json)
+
+    async def delete(self, path: str) -> None:
+        resp = await self._client.delete(path)
+        if resp.status_code not in (200, 204):
+            raise KricketError("REQUEST_FAILED", f"HTTP {resp.status_code}", resp.status_code)
+
+    async def _request(self, method: str, path: str, json: Any = None) -> Any:
+        resp = await self._client.request(method, path, json=json)
+        data = resp.json()
+
+        if not data.get("success") or data.get("error"):
+            err = data.get("error", {})
+            raise KricketError(
+                code=err.get("code", "UNKNOWN_ERROR"),
+                message=err.get("message", "Unknown error"),
+                status=resp.status_code,
+            )
+
+        return data.get("data")
+
+    async def close(self) -> None:
+        await self._client.aclose()

kricket_client-0.1.0/kricket_client/mantis.py

@@ -0,0 +1,32 @@
+"""Mantis API client: rug-pull detection and token risk scoring."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from kricket_client.http import HttpClient
+from kricket_client.types import ScanResponse, RiskScore, WatchlistEntry
+
+
+class MantisClient:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def scan(self, token: str) -> ScanResponse:
+        """Run a full security scan on a token."""
+        data = await self._http.get(f"/mantis/scan/{quote(token)}")
+        return ScanResponse(**data)
+
+    async def get_score(self, token: str) -> RiskScore:
+        """Get only the risk score for a token."""
+        data = await self._http.get(f"/mantis/score/{quote(token)}")
+        return RiskScore(**data)
+
+    async def add_to_watchlist(self, tokens: list[str]) -> dict:
+        """Add tokens to the watchlist."""
+        return await self._http.post("/mantis/watchlist", json={"tokens": tokens})
+
+    async def get_watchlist(self) -> list[WatchlistEntry]:
+        """Get all watched tokens."""
+        data = await self._http.get("/mantis/watchlist")
+        return [WatchlistEntry(**e) for e in data]

kricket_client-0.1.0/kricket_client/pulse.py

@@ -0,0 +1,28 @@
+"""Pulse API client: unified price feeds across CEX and DEX venues."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from kricket_client.http import HttpClient
+from kricket_client.types import PriceQuote, SpreadAnalysis, Venue
+
+
+class PulseClient:
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    async def get_price(self, token: str) -> list[PriceQuote]:
+        """Get price quotes for a token across all venues."""
+        data = await self._http.get(f"/pulse/price/{quote(token)}")
+        return [PriceQuote(**q) for q in data]
+
+    async def get_spread(self, token: str) -> SpreadAnalysis:
+        """Get cross-venue spread analysis for a token."""
+        data = await self._http.get(f"/pulse/spread/{quote(token)}")
+        return SpreadAnalysis(**data)
+
+    async def get_venues(self) -> list[Venue]:
+        """List all supported venues."""
+        data = await self._http.get("/pulse/venues")
+        return [Venue(**v) for v in data]