bitculator 1.0.0__py3-none-any.whl

bitculator/__init__.py

@@ -0,0 +1,37 @@
+"""Official Python SDK for the Bitculator Data API."""
+
+from ._http import Quota
+from ._version import __version__
+from .client import Bitculator
+from .errors import (
+    APIConnectionError,
+    APIDecodeError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    BitculatorError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .pagination import Page
+
+__all__ = [
+    "Bitculator",
+    "Page",
+    "Quota",
+    "BitculatorError",
+    "APIError",
+    "APITimeoutError",
+    "APIConnectionError",
+    "APIDecodeError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "__version__",
+]

bitculator/_http.py

@@ -0,0 +1,214 @@
+"""
+The DRY transport core. Every request in the SDK flows through
+``HttpClient._request``: URL + query building, auth headers, JSON
+(de)serialization, the response envelope, quota capture, retries with backoff,
+timeouts, and error mapping all live here — nowhere else. Uses only the standard
+library (``urllib``) so the SDK has zero runtime dependencies.
+"""
+
+from __future__ import annotations
+
+import decimal
+import http.client
+import json
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from .errors import APIConnectionError, APIDecodeError, APIError, APITimeoutError, BitculatorError
+from .pagination import Page
+
+
+@dataclass
+class Quota:
+    """Quota headers (``X-Quota-*``) from the most recent response."""
+
+    limit: Optional[int]
+    remaining: Optional[int]
+    reset: Optional[int]
+    raw: dict
+
+
+class HttpClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        user_agent: str,
+        on_quota: Callable[[Quota], None],
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        self._api_key = api_key
+        self._base_url = base_url
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._user_agent = user_agent
+        self._on_quota = on_quota
+        self._opener = opener or urllib.request.build_opener()
+
+    def get(self, path: str, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("GET", path, params=params))
+
+    def post(self, path: str, body: Any = None, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("POST", path, params=params, body=body))
+
+    def delete(self, path: str, params: Optional[dict] = None) -> Any:
+        return _unwrap(self._request("DELETE", path, params=params))
+
+    def get_page(self, path: str, params: Optional[dict] = None) -> Page:
+        envelope = self._request("GET", path, params=params)
+        return Page(self, path, params or {}, envelope)
+
+    def _request(self, method: str, path: str, params: Optional[dict] = None, body: Any = None) -> Any:
+        url = self._base_url + path + _query(params)
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+        data: Optional[bytes] = None
+        if body is not None:
+            try:
+                data = json.dumps(_snake_keys(body)).encode("utf-8")
+            except (TypeError, ValueError) as exc:
+                raise BitculatorError(f"Failed to encode request body: {exc}") from exc
+            headers["Content-Type"] = "application/json"
+
+        # Idempotency gate: GET/DELETE are safe to auto-retry; POST is NOT, so a
+        # POST the server may already have processed is never re-sent on a 5xx or
+        # a network/timeout error. A 429 means the server rejected it before
+        # processing, so it stays retryable for every method.
+        is_idempotent = method in ("GET", "DELETE")
+
+        attempt = 0
+        while True:
+            request = urllib.request.Request(url, data=data, headers=headers, method=method)
+            try:
+                with self._opener.open(request, timeout=self._timeout) as response:
+                    self._on_quota(_parse_quota(response.headers))
+                    raw = response.read()
+                    if not raw:
+                        return None
+                    try:
+                        return json.loads(raw)
+                    except (ValueError, TypeError) as exc:
+                        raise APIDecodeError(f"Failed to decode response from {path}: {exc}") from exc
+            except urllib.error.HTTPError as exc:
+                self._on_quota(_parse_quota(exc.headers))
+                raw = exc.read()
+                payload = _safe_json(raw)
+                status = exc.code
+                retryable = status == 429 or (status >= 500 and is_idempotent)
+                if retryable and attempt < self._max_retries:
+                    time.sleep(_retry_delay(exc.headers, attempt))
+                    attempt += 1
+                    continue
+                raise APIError.from_response(status, payload, exc.headers) from None
+            except (urllib.error.URLError, http.client.HTTPException, TimeoutError, OSError) as exc:
+                if is_idempotent and attempt < self._max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                reason = getattr(exc, "reason", exc)
+                if isinstance(reason, TimeoutError) or "timed out" in str(reason).lower():
+                    raise APITimeoutError(f"Request to {path} timed out after {self._timeout}s") from exc
+                raise APIConnectionError(f"Network error requesting {path}: {reason}") from exc
+
+
+# ── helpers (all pure; the single place these concerns are implemented) ──────
+
+
+def _unwrap(envelope: Any) -> Any:
+    """Unwrap the ``{"data": ...}`` envelope; pass through bodies with no data key."""
+    if isinstance(envelope, dict) and "data" in envelope:
+        return envelope["data"]
+    return envelope
+
+
+def _query(params: Optional[dict]) -> str:
+    """Serialize params: drop ``None``, lists→CSV, bools→true/false, trailing ``_`` stripped (``from_``→``from``)."""
+    if not params:
+        return ""
+    pairs = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        name = key[:-1] if key.endswith("_") else key
+        if isinstance(value, (list, tuple)):
+            if not value:
+                continue
+            pairs.append((name, ",".join(str(item) for item in value)))
+        elif isinstance(value, bool):
+            pairs.append((name, "true" if value else "false"))
+        elif isinstance(value, float):
+            # Plain-decimal form (0.0000001, not 1e-07) — keeps the wire format
+            # identical across the SDK family.
+            pairs.append((name, format(decimal.Decimal(repr(value)), "f")))
+        else:
+            pairs.append((name, str(value)))
+    return "?" + urllib.parse.urlencode(pairs) if pairs else ""
+
+
+def _snake_keys(body: Any) -> Any:
+    """Strip a trailing underscore from body keys (``from_``→``from``); leave the rest as-is."""
+    if not isinstance(body, dict):
+        return body
+    return {(key[:-1] if key.endswith("_") else key): value for key, value in body.items()}
+
+
+def _parse_quota(headers: Any) -> Quota:
+    raw = {}
+    if headers is not None:
+        for key, value in headers.items():
+            lowered = key.lower()
+            if lowered.startswith("x-quota-"):
+                raw[lowered] = value
+
+    def num(name: str) -> Optional[int]:
+        value = raw.get(name)
+        if value in (None, ""):
+            return None
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    return Quota(
+        limit=num("x-quota-limit"),
+        remaining=num("x-quota-remaining"),
+        reset=num("x-quota-reset"),
+        raw=raw,
+    )
+
+
+def _retry_delay(headers: Any, attempt: int) -> float:
+    retry_after = headers.get("retry-after") if headers is not None else None
+    try:
+        seconds = int(retry_after)
+        if seconds > 0:
+            # Cap at 60s: a misbehaving proxy must not block a synchronous call for an hour.
+            return float(min(seconds, 60))
+    except (TypeError, ValueError):
+        pass
+    return _backoff(attempt)
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff with jitter, capped at 8s."""
+    return min(8.0, 0.25 * (2 ** attempt)) + random.uniform(0.0, 0.1)
+
+
+def _safe_json(raw: bytes) -> Any:
+    if not raw:
+        return None
+    try:
+        return json.loads(raw)
+    except (ValueError, TypeError):
+        return None

bitculator/_version.py

@@ -0,0 +1,3 @@
+"""SDK version, sent in the User-Agent header. Single source of truth — pyproject.toml reads it via [tool.hatch.version]."""
+
+__version__ = "1.0.0"

bitculator/client.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import urllib.request
+from typing import Optional
+
+from ._http import HttpClient, Quota
+from ._version import __version__
+from .errors import BitculatorError
+from .resources import (
+    AlarmsResource,
+    CalculatorsResource,
+    CoinsResource,
+    ConversionResource,
+    EditorialResource,
+    ExchangesResource,
+    GlobalMarketResource,
+    IndicatorsResource,
+    LiquidationsResource,
+    MarketsResource,
+    MetaResource,
+    PricesResource,
+    SentimentResource,
+    WalletsResource,
+    WebhooksResource,
+)
+
+DEFAULT_BASE_URL = "https://bitculator.com"
+
+
+class Bitculator:
+    """The Bitculator Data API client.
+
+    >>> client = Bitculator(api_key="...")
+    >>> bitcoin = client.coins.get("bitcoin")
+
+    Each API group is an attribute on the client: ``client.coins``,
+    ``client.prices``, ``client.exchanges``, and so on.
+
+    Pass ``opener`` (a ``urllib.request.OpenerDirector``) to inject for
+    proxies/custom handlers; every request then goes through it.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        user_agent: Optional[str] = None,
+        opener: Optional[urllib.request.OpenerDirector] = None,
+    ) -> None:
+        if not api_key:
+            raise BitculatorError("A Data API key is required: Bitculator(api_key=...)")
+
+        self._quota: Optional[Quota] = None
+        http = HttpClient(
+            api_key=api_key,
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            max_retries=max_retries,
+            user_agent=user_agent or f"bitculator-python/{__version__}",
+            on_quota=self._set_quota,
+            opener=opener,
+        )
+
+        self.coins = CoinsResource(http)
+        self.prices = PricesResource(http)
+        self.markets = MarketsResource(http)
+        self.exchanges = ExchangesResource(http)
+        self.wallets = WalletsResource(http)
+        self.global_market = GlobalMarketResource(http)
+        self.sentiment = SentimentResource(http)
+        self.indicators = IndicatorsResource(http)
+        self.liquidations = LiquidationsResource(http)
+        self.conversion = ConversionResource(http)
+        self.calculators = CalculatorsResource(http)
+        self.editorial = EditorialResource(http)
+        self.alarms = AlarmsResource(http)
+        self.webhooks = WebhooksResource(http)
+        self.meta = MetaResource(http)
+
+    def _set_quota(self, quota: Quota) -> None:
+        self._quota = quota
+
+    @property
+    def quota(self) -> Optional[Quota]:
+        """Quota (``X-Quota-*``) from the most recent response, or ``None`` before the first call."""
+        return self._quota

bitculator/errors.py

@@ -0,0 +1,119 @@
+"""
+Exception hierarchy. Everything the SDK raises derives from ``BitculatorError``,
+so a single ``except BitculatorError`` covers it all. HTTP failures raise a
+status-specific ``APIError`` subclass carrying the API's
+``{"error": {"code", "message", "details"}}`` envelope.
+
+(Note: 403 is ``PermissionDeniedError`` and timeouts are ``APITimeoutError`` to
+avoid shadowing the built-in ``PermissionError`` / ``TimeoutError``.)
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BitculatorError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APITimeoutError(BitculatorError):
+    """The request exceeded the configured timeout (after retries)."""
+
+
+class APIConnectionError(BitculatorError):
+    """A network-level failure prevented the request from completing."""
+
+
+class APIDecodeError(BitculatorError):
+    """A 2xx body could not be parsed."""
+
+
+class APIError(BitculatorError):
+    """A non-2xx response. Subclasses map to specific status codes."""
+
+    def __init__(self, status: int, body: Optional[dict], request_id: Optional[str]) -> None:
+        err = body or {}
+        self.status = status
+        self.code: Optional[str] = err.get("code")
+        self.details: Any = err.get("details")
+        self.request_id = request_id
+        self.message: str = err.get("message") or f"HTTP {status}"
+        super().__init__(self.message)
+
+    @staticmethod
+    def from_response(status: int, json_body: Any, headers: Any) -> "APIError":
+        """Build the most specific error subclass for a failed response."""
+        body = _error_body(json_body)
+        request_id = headers.get("x-request-id") if headers is not None else None
+        if status == 429:
+            return RateLimitError(status, body, request_id, _to_int(_header(headers, "retry-after")))
+        cls = _STATUS_MAP.get(status)
+        if cls is not None:
+            return cls(status, body, request_id)
+        if status >= 500:
+            return ServerError(status, body, request_id)
+        return APIError(status, body, request_id)
+
+
+class AuthenticationError(APIError):
+    """401 — missing, malformed, or invalid API key."""
+
+
+class PermissionDeniedError(APIError):
+    """403 — the key's plan does not grant access to this endpoint."""
+
+
+class NotFoundError(APIError):
+    """404 — the requested resource does not exist."""
+
+
+class ValidationError(APIError):
+    """422 — invalid parameters (see ``details``)."""
+
+
+class ServerError(APIError):
+    """5xx — an error on the API side."""
+
+
+class RateLimitError(APIError):
+    """429 — quota or rate limit exceeded."""
+
+    def __init__(
+        self,
+        status: int,
+        body: Optional[dict],
+        request_id: Optional[str],
+        retry_after: Optional[int] = None,
+    ) -> None:
+        super().__init__(status, body, request_id)
+        self.retry_after = retry_after
+
+
+_STATUS_MAP = {
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    422: ValidationError,
+}
+
+
+def _error_body(json_body: Any) -> Optional[dict]:
+    if isinstance(json_body, dict):
+        err = json_body.get("error")
+        if isinstance(err, dict):
+            return err
+        if isinstance(json_body.get("message"), str):
+            return {"message": json_body["message"]}
+    return None
+
+
+def _header(headers: Any, name: str) -> Any:
+    return headers.get(name) if headers is not None else None
+
+
+def _to_int(value: Any) -> Optional[int]:
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None

bitculator/pagination.py

@@ -0,0 +1,59 @@
+"""
+A single page of a paginated list, plus lazy forward navigation.
+
+``page.data`` is the current page's rows. Iterating a ``Page`` (or calling
+``auto_paging_iter()``) transparently walks every following page.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Iterator, List, Optional
+
+if TYPE_CHECKING:
+    from ._http import HttpClient
+
+
+class Page:
+    def __init__(self, http: "HttpClient", path: str, params: dict, envelope: Any) -> None:
+        env = envelope if isinstance(envelope, dict) else {}
+        #: Rows on this page.
+        self.data: List[Any] = env.get("data", []) or []
+        #: Laravel paginator metadata (current_page, last_page, total, ...).
+        self.meta: dict = env.get("meta", {}) or {}
+        #: Page navigation links.
+        self.links: dict = env.get("links", {}) or {}
+        self._http = http
+        self._path = path
+        self._params = params
+
+    @property
+    def has_more(self) -> bool:
+        """True if at least one more page exists."""
+        if self.links.get("next"):
+            return True
+        current, last = self.meta.get("current_page"), self.meta.get("last_page")
+        return current is not None and last is not None and current < last
+
+    def next_page(self) -> Optional["Page"]:
+        """Fetch the next page, or ``None`` if this is the last one."""
+        if not self.has_more:
+            return None
+        next_number = (self.meta.get("current_page") or 1) + 1
+        return self._http.get_page(self._path, {**self._params, "page": next_number})
+
+    def auto_paging_iter(self) -> Iterator[Any]:
+        """Yield every row across this and all following pages, fetching lazily."""
+        page: Optional[Page] = self
+        while page is not None:
+            yield from page.data
+            page = page.next_page()
+
+    def __iter__(self) -> Iterator[Any]:
+        """Iterating a page walks all pages (use ``.data`` for just this page)."""
+        return self.auto_paging_iter()
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        return f"<Page rows={len(self.data)} page={self.meta.get('current_page')}/{self.meta.get('last_page')}>"

bitculator/resources/__init__.py

@@ -0,0 +1,24 @@
+from .account import AlarmsResource, MetaResource, WebhooksResource
+from .coins import CoinsResource, ConversionResource, PricesResource
+from .editorial import EditorialResource
+from .indicators import CalculatorsResource, IndicatorsResource
+from .market import GlobalMarketResource, LiquidationsResource, SentimentResource
+from .markets import ExchangesResource, MarketsResource, WalletsResource
+
+__all__ = [
+    "AlarmsResource",
+    "CalculatorsResource",
+    "CoinsResource",
+    "ConversionResource",
+    "EditorialResource",
+    "ExchangesResource",
+    "GlobalMarketResource",
+    "IndicatorsResource",
+    "LiquidationsResource",
+    "MarketsResource",
+    "MetaResource",
+    "PricesResource",
+    "SentimentResource",
+    "WalletsResource",
+    "WebhooksResource",
+]

bitculator/resources/_base.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+from .._http import HttpClient
+
+
+class Resource:
+    """Shared base for every resource group: holds the transport and encodes path segments."""
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    @staticmethod
+    def _enc(value: Any) -> str:
+        """Percent-encode a dynamic path segment (slug or id) so it is URL-safe."""
+        return urllib.parse.quote(str(value), safe="")

bitculator/resources/account.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any, List, Union
+
+from ..pagination import Page
+from ._base import Resource
+
+
+class AlarmsResource(Resource):
+    """Price alarms owned by the API key."""
+
+    def list(self, **params: Any) -> Page:
+        """List your alarms (paginated). Params: page, per_page, status, direction, notification."""
+        return self._http.get_page("/api/v1/alarms", params)
+
+    def create(
+        self,
+        *,
+        name: str,
+        coin: str,
+        metric: str,
+        direction: str,
+        target: float,
+        notification: str,
+    ) -> Any:
+        """Create an alarm."""
+        return self._http.post(
+            "/api/v1/alarms",
+            {
+                "name": name,
+                "coin": coin,
+                "metric": metric,
+                "direction": direction,
+                "target": target,
+                "notification": notification,
+            },
+        )
+
+    def delete(self, id: Union[str, int]) -> Any:
+        """Delete an alarm by id."""
+        return self._http.delete(f"/api/v1/alarms/{self._enc(id)}")
+
+
+class WebhooksResource(Resource):
+    """Webhook endpoints and their delivery log."""
+
+    def list(self) -> Any:
+        """List your webhook endpoints."""
+        return self._http.get("/api/v1/webhooks")
+
+    def create(self, *, url: str, events: List[str]) -> Any:
+        """Register a webhook endpoint for a set of events."""
+        return self._http.post("/api/v1/webhooks", {"url": url, "events": events})
+
+    def delete(self, id: Union[str, int]) -> Any:
+        """Delete a webhook endpoint by id."""
+        return self._http.delete(f"/api/v1/webhooks/{self._enc(id)}")
+
+    def test(self, id: Union[str, int]) -> Any:
+        """Send a test event to a webhook endpoint."""
+        return self._http.post(f"/api/v1/webhooks/{self._enc(id)}/test")
+
+    def deliveries(self, id: Union[str, int], **params: Any) -> Page:
+        """Delivery log for a webhook endpoint (paginated). Params: page, per_page."""
+        return self._http.get_page(f"/api/v1/webhooks/{self._enc(id)}/deliveries", params)
+
+
+class MetaResource(Resource):
+    """Service metadata: spec, health, and key usage."""
+
+    def openapi(self) -> Any:
+        """The raw OpenAPI specification for the API."""
+        return self._http.get("/api/v1/openapi.json")
+
+    def ping(self) -> Any:
+        """Health check."""
+        return self._http.get("/api/v1/ping")
+
+    def usage(self) -> Any:
+        """Current key usage and quota."""
+        return self._http.get("/api/v1/usage")

bitculator/resources/coins.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..pagination import Page
+from ._base import Resource
+
+
+class CoinsResource(Resource):
+    """Coins & tokens: listings, movers, detail, and history."""
+
+    def list(self, **params: Any) -> Page:
+        """List coins (paginated). Params: page, per_page, type, status, search,
+        min_price, max_price, min_marketcap, max_marketcap, min_volume, max_volume,
+        ids, slugs, symbols, sort, interval."""
+        return self._http.get_page("/api/v1/coins", params)
+
+    def recently_added(self, **params: Any) -> Page:
+        """Recently added coins (paginated). Same params as :meth:`list`."""
+        return self._http.get_page("/api/v1/coins/recently-added", params)
+
+    def gainers(self, **params: Any) -> Page:
+        """Top gainers (paginated). Same params as :meth:`list`."""
+        return self._http.get_page("/api/v1/coins/gainers", params)
+
+    def losers(self, **params: Any) -> Page:
+        """Top losers (paginated). Same params as :meth:`list`."""
+        return self._http.get_page("/api/v1/coins/losers", params)
+
+    def trending(self, **params: Any) -> Any:
+        """Trending coins. Params: limit."""
+        return self._http.get("/api/v1/coins/trending", params)
+
+    def get(self, slug: str, **params: Any) -> Any:
+        """Get a single coin by slug. Params: locale."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}", params)
+
+    def history(self, slug: str, **params: Any) -> Any:
+        """OHLC candle history. Params: interval, start, end, limit."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/history", params)
+
+    def marketcap_history(self, slug: str, **params: Any) -> Any:
+        """Marketcap history. Params: interval, start, end, limit."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/marketcap-history", params)
+
+    def sparkline(self, slug: str, **params: Any) -> Any:
+        """Price sparkline. Params: period."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/sparkline", params)
+
+
+class PricesResource(Resource):
+    """Lightweight price lookups."""
+
+    def list(self, **params: Any) -> Any:
+        """Get prices for many coins at once. Params: ids, slugs, symbols, convert."""
+        return self._http.get("/api/v1/prices", params)
+
+    def get(self, slug: str, **params: Any) -> Any:
+        """Get the price of a single coin. Params: convert."""
+        return self._http.get(f"/api/v1/prices/{self._enc(slug)}", params)
+
+    def historical(self, **params: Any) -> Any:
+        """Historical price of a coin on a date. Params: slug, date."""
+        return self._http.get("/api/v1/historical-price", params)
+
+
+class ConversionResource(Resource):
+    """Asset conversion and reference rates."""
+
+    def convert(self, **params: Any) -> Any:
+        """Convert an amount between two assets. Params: from_ (-> ``from``), to, amount."""
+        return self._http.get("/api/v1/convert", params)
+
+    def fiats(self) -> Any:
+        """List supported fiat currencies."""
+        return self._http.get("/api/v1/fiats")
+
+    def rates(self) -> Any:
+        """List conversion rates."""
+        return self._http.get("/api/v1/rates")

bitculator/resources/editorial.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any, Union
+
+from ..pagination import Page
+from ._base import Resource
+
+
+class EditorialResource(Resource):
+    """Editorial content: articles, videos, and insights."""
+
+    def coin_videos(self, slug: str, **params: Any) -> Page:
+        """Videos for a coin (paginated). Params: page, per_page, type, search."""
+        return self._http.get_page(f"/api/v1/coins/{self._enc(slug)}/videos", params)
+
+    def coin_insights(self, slug: str, **params: Any) -> Any:
+        """Insight timeline for a coin. Params: locale, offset, limit."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/insights", params)
+
+    def articles(self, **params: Any) -> Page:
+        """List articles (paginated). Params: page, per_page, locale, tag, coin,
+        exchange, wallet, search."""
+        return self._http.get_page("/api/v1/articles", params)
+
+    def article(self, slug: str, **params: Any) -> Any:
+        """Get a single article by slug. Params: locale."""
+        return self._http.get(f"/api/v1/articles/{self._enc(slug)}", params)
+
+    def submit_article_feedback(self, slug: str, *, helpful: bool) -> Any:
+        """Submit helpful/unhelpful feedback on an article."""
+        return self._http.post(f"/api/v1/articles/{self._enc(slug)}/feedback", {"helpful": helpful})
+
+    def video(self, id: Union[str, int]) -> Any:
+        """Get a single video by id."""
+        return self._http.get(f"/api/v1/videos/{self._enc(id)}")
+
+    def insights(self, **params: Any) -> Page:
+        """List insights (paginated). Params: page, per_page, locale, type, coin, search, sort."""
+        return self._http.get_page("/api/v1/insights", params)
+
+    def insight(self, id: Union[str, int], **params: Any) -> Any:
+        """Get a single insight by id. Params: locale."""
+        return self._http.get(f"/api/v1/insights/{self._enc(id)}", params)

bitculator/resources/indicators.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import Resource
+
+
+class IndicatorsResource(Resource):
+    """Technical indicators for a coin.
+
+    Period indicators (rsi, stoch_rsi, sma, cci, mfi, williams_r, price_volatility,
+    volume_volatility) accept: period, start, end, limit.
+    Series indicators (macd, obv, adx, vwap, cmf) accept: start, end, limit.
+    """
+
+    def _indicator(self, slug: str, name: str, params: dict) -> Any:
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/indicators/{name}", params)
+
+    def snapshot(self, slug: str) -> Any:
+        """All indicators for a coin at a glance."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/indicators")
+
+    def rsi(self, slug: str, **params: Any) -> Any:
+        """Relative Strength Index."""
+        return self._indicator(slug, "rsi", params)
+
+    def stoch_rsi(self, slug: str, **params: Any) -> Any:
+        """Stochastic RSI."""
+        return self._indicator(slug, "stoch-rsi", params)
+
+    def sma(self, slug: str, **params: Any) -> Any:
+        """Simple Moving Average."""
+        return self._indicator(slug, "sma", params)
+
+    def cci(self, slug: str, **params: Any) -> Any:
+        """Commodity Channel Index."""
+        return self._indicator(slug, "cci", params)
+
+    def mfi(self, slug: str, **params: Any) -> Any:
+        """Money Flow Index."""
+        return self._indicator(slug, "mfi", params)
+
+    def williams_r(self, slug: str, **params: Any) -> Any:
+        """Williams %R."""
+        return self._indicator(slug, "williams-r", params)
+
+    def price_volatility(self, slug: str, **params: Any) -> Any:
+        """Price volatility."""
+        return self._indicator(slug, "price-volatility", params)
+
+    def volume_volatility(self, slug: str, **params: Any) -> Any:
+        """Volume volatility."""
+        return self._indicator(slug, "volume-volatility", params)
+
+    def macd(self, slug: str, **params: Any) -> Any:
+        """Moving Average Convergence Divergence."""
+        return self._indicator(slug, "macd", params)
+
+    def obv(self, slug: str, **params: Any) -> Any:
+        """On-Balance Volume."""
+        return self._indicator(slug, "obv", params)
+
+    def adx(self, slug: str, **params: Any) -> Any:
+        """Average Directional Index."""
+        return self._indicator(slug, "adx", params)
+
+    def vwap(self, slug: str, **params: Any) -> Any:
+        """Volume-Weighted Average Price."""
+        return self._indicator(slug, "vwap", params)
+
+    def cmf(self, slug: str, **params: Any) -> Any:
+        """Chaikin Money Flow."""
+        return self._indicator(slug, "cmf", params)
+
+
+class CalculatorsResource(Resource):
+    """Financial calculators."""
+
+    def dca(self, **params: Any) -> Any:
+        """Dollar-cost-averaging calculator. Params: slug, amount, interval, start, end, series."""
+        return self._http.get("/api/v1/calculators/dca", params)
+
+    def profit_loss(self, **params: Any) -> Any:
+        """Profit / loss calculator. Params: slug, amount, buy_date, sell_date, buy_fee, sell_fee."""
+        return self._http.get("/api/v1/calculators/profit-loss", params)
+
+    def compound_interest(self, **params: Any) -> Any:
+        """Compound interest calculator. Params: principal, rate, duration, duration_unit,
+        compound_frequency, contribution, contribution_frequency."""
+        return self._http.get("/api/v1/calculators/compound-interest", params)
+
+    def loan(self, **params: Any) -> Any:
+        """Loan-vs-sell calculator. Params: slug, crypto_amount, needed_cash, term_months,
+        interest_rate, ltv, expected_growth, tax_rate."""
+        return self._http.get("/api/v1/calculators/loan", params)
+
+    def staking(self, **params: Any) -> Any:
+        """Staking rewards calculator. Params: amount, period, period_unit, apy,
+        compound_frequency, commission."""
+        return self._http.get("/api/v1/calculators/staking", params)

bitculator/resources/market.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..pagination import Page
+from ._base import Resource
+
+
+class GlobalMarketResource(Resource):
+    """Global market aggregates."""
+
+    def snapshot(self) -> Any:
+        """Global market snapshot (total marketcap, volume, dominance, ...)."""
+        return self._http.get("/api/v1/global")
+
+    def heatmap(self) -> Any:
+        """Market heatmap data."""
+        return self._http.get("/api/v1/global/heatmap")
+
+    def history(self, metric: str, **params: Any) -> Any:
+        """Global marketcap or volume history. ``metric`` is e.g. ``marketcap`` or ``volume``. Params: period."""
+        return self._http.get(f"/api/v1/global/history/{self._enc(metric)}", params)
+
+
+class SentimentResource(Resource):
+    """Community sentiment and market-wide sentiment indices."""
+
+    def votes(self, slug: str) -> Any:
+        """Community vote tallies for a coin."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/votes")
+
+    def vote(self, slug: str, *, vote: str) -> Any:
+        """Cast a sentiment vote for a coin (``bullish`` or ``bearish``)."""
+        return self._http.post(f"/api/v1/coins/{self._enc(slug)}/votes", {"vote": vote})
+
+    def fear_greed(self, **params: Any) -> Any:
+        """Fear & Greed index. Params: coin."""
+        return self._http.get("/api/v1/sentiment/fear-greed", params)
+
+    def bull_bear(self, **params: Any) -> Any:
+        """Bull / Bear index. Params: coin."""
+        return self._http.get("/api/v1/sentiment/bull-bear", params)
+
+    def altseason(self, **params: Any) -> Any:
+        """Altseason index. Params: days."""
+        return self._http.get("/api/v1/sentiment/altseason", params)
+
+    def indicators(self) -> Any:
+        """Aggregate market indicator tally."""
+        return self._http.get("/api/v1/sentiment/indicators")
+
+
+class LiquidationsResource(Resource):
+    """Liquidation feed and aggregates."""
+
+    def feed(self, **params: Any) -> Page:
+        """Live liquidation feed (paginated). Params: page, per_page, exchange,
+        instrument, position, order, symbol, min_usd."""
+        return self._http.get_page("/api/v1/liquidations", params)
+
+    def hourly(self, **params: Any) -> Any:
+        """Hourly liquidation totals. Params: hours."""
+        return self._http.get("/api/v1/liquidations/hourly", params)
+
+    def daily(self, **params: Any) -> Any:
+        """Daily liquidation totals. Params: days."""
+        return self._http.get("/api/v1/liquidations/daily", params)
+
+    def summary(self) -> Any:
+        """Today's liquidation summary."""
+        return self._http.get("/api/v1/liquidations/summary")
+
+    def netflow(self, **params: Any) -> Any:
+        """Long/short liquidation netflow. Params: days."""
+        return self._http.get("/api/v1/liquidations/netflow", params)
+
+    def coins(self, **params: Any) -> Any:
+        """Most-liquidated coins. Params: hours, limit."""
+        return self._http.get("/api/v1/liquidations/coins", params)

bitculator/resources/markets.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+from typing import Any, Union
+
+from ..pagination import Page
+from ._base import Resource
+
+
+class MarketsResource(Resource):
+    """Markets, tickers, and trading pairs."""
+
+    def coin_markets(self, slug: str, **params: Any) -> Page:
+        """Markets (tickers) for a coin (paginated). Params: page, per_page, exchange,
+        pair, instrument, search, min_volume, max_volume, min_change, max_change, sort."""
+        return self._http.get_page(f"/api/v1/coins/{self._enc(slug)}/markets", params)
+
+    def coin_symbols(self, slug: str) -> Any:
+        """Trading symbols for a coin."""
+        return self._http.get(f"/api/v1/coins/{self._enc(slug)}/symbols")
+
+    def tickers(self, **params: Any) -> Page:
+        """List tickers across the market (paginated). Same params as :meth:`coin_markets`."""
+        return self._http.get_page("/api/v1/tickers", params)
+
+    def pairs(self, **params: Any) -> Page:
+        """List trading pairs (paginated). Params: page, per_page, search, coin,
+        min_volume, max_volume, sort."""
+        return self._http.get_page("/api/v1/pairs", params)
+
+    def pair(self, id: Union[str, int]) -> Any:
+        """Get a single trading pair by id."""
+        return self._http.get(f"/api/v1/pairs/{self._enc(id)}")
+
+
+class ExchangesResource(Resource):
+    """Exchanges: listings, trust score, history, markets, and listed assets."""
+
+    def list(self, **params: Any) -> Page:
+        """List exchanges (paginated). Params: page, per_page, type, search, min_pairs,
+        max_pairs, min_assets, max_assets, min_volume, max_volume, ids, slugs, sort."""
+        return self._http.get_page("/api/v1/exchanges", params)
+
+    def get(self, slug: str) -> Any:
+        """Get a single exchange by slug."""
+        return self._http.get(f"/api/v1/exchanges/{self._enc(slug)}")
+
+    def trust_score(self, slug: str) -> Any:
+        """Get an exchange's trust score."""
+        return self._http.get(f"/api/v1/exchanges/{self._enc(slug)}/trust-score")
+
+    def history(self, slug: str, **params: Any) -> Any:
+        """Volume/history for an exchange. Params: interval, start, end, limit."""
+        return self._http.get(f"/api/v1/exchanges/{self._enc(slug)}/history", params)
+
+    def sparkline(self, slug: str, **params: Any) -> Any:
+        """Sparkline for an exchange. Params: period."""
+        return self._http.get(f"/api/v1/exchanges/{self._enc(slug)}/sparkline", params)
+
+    def tickers(self, slug: str, **params: Any) -> Page:
+        """Markets (tickers) on an exchange (paginated)."""
+        return self._http.get_page(f"/api/v1/exchanges/{self._enc(slug)}/tickers", params)
+
+    def assets(self, slug: str, **params: Any) -> Page:
+        """Coins listed on an exchange (paginated)."""
+        return self._http.get_page(f"/api/v1/exchanges/{self._enc(slug)}/assets", params)
+
+
+class WalletsResource(Resource):
+    """Wallets: listings, release timeline, comparison, and supported coins."""
+
+    def list(self, **params: Any) -> Page:
+        """List wallets (paginated). Params: page, per_page, search, min_score,
+        max_score, tags, ids, slugs, sort."""
+        return self._http.get_page("/api/v1/wallets", params)
+
+    def timeline(self, **params: Any) -> Page:
+        """Wallet release timeline (paginated). Same params as :meth:`list`."""
+        return self._http.get_page("/api/v1/wallets/timeline", params)
+
+    def compare(self, **params: Any) -> Any:
+        """Compare a set of wallets side by side. Params: slugs."""
+        return self._http.get("/api/v1/wallets/compare", params)
+
+    def get(self, slug: str) -> Any:
+        """Get a single wallet by slug."""
+        return self._http.get(f"/api/v1/wallets/{self._enc(slug)}")
+
+    def assets(self, slug: str, **params: Any) -> Page:
+        """Coins supported by a wallet (paginated)."""
+        return self._http.get_page(f"/api/v1/wallets/{self._enc(slug)}/assets", params)

bitculator-1.0.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: bitculator
+Version: 1.0.0
+Summary: Official Python SDK for the Bitculator Data API
+Project-URL: Documentation, https://bitculator.com/en/documentation/api/v1
+Project-URL: Repository, https://github.com/bitculator/bitculator-python-sdk
+Author: Bitculator
+License: MIT
+License-File: LICENSE
+Keywords: api,bitculator,crypto,cryptocurrency,market-data,sdk
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Bitculator Data API — Python SDK
+
+[bitculator.com](https://bitculator.com) · [API documentation](https://bitculator.com/en/documentation/api/v1) · [Get an API key](https://bitculator.com/user/developer/api)
+[PyPI — `bitculator`](https://pypi.org/project/bitculator/) · [GitHub](https://github.com/Bitculator/bitculator-python-sdk)
+
+The official Python SDK for the [Bitculator Data API](https://bitculator.com).
+Zero dependencies (standard-library only), typed, works on Python 3.9+.
+
+> Keep your API key server-side. It is a Bearer token with the `data-api` ability
+> and is not meant for client-side embedding.
+
+## Install
+
+```bash
+pip install bitculator
+```
+
+## Quick start
+
+```python
+import os
+from bitculator import Bitculator
+
+client = Bitculator(os.environ["BITCULATOR_API_KEY"])
+
+# Single resource — the {"data": ...} envelope is unwrapped for you.
+bitcoin = client.coins.get("bitcoin")
+print(bitcoin["price"])   # "63520.780763913" — a decimal string, never rounded
+
+# A paginated list.
+page = client.coins.list(per_page=50, sort="-marketcap")
+print(page.data, page.meta["total"])
+```
+
+## Prices are decimal strings
+
+Prices, rates, and supplies come back as **strings** (e.g. `"63520.780763913"`)
+to preserve full precision. Use `decimal.Decimal` if you need to do math — do
+**not** pass them through `float()`, which silently loses precision.
+
+## Pagination
+
+Every paginated method returns a `Page`. Read one page, or iterate to walk them all:
+
+```python
+# One page at a time.
+page = client.exchanges.list(per_page=100)
+while page is not None:
+    for exchange in page.data:
+        print(exchange["name"])
+    page = page.next_page()
+
+# Or auto-paginate across every page (iterating a Page walks all pages).
+for coin in client.coins.list(sort="-marketcap"):
+    print(coin["symbol"])
+```
+
+## Errors
+
+Every failure derives from `BitculatorError`; HTTP failures raise a status-specific
+subclass carrying the `{"error": {"code", "message", "details"}}` envelope.
+
+```python
+from bitculator import ValidationError, RateLimitError, APIError
+
+try:
+    client.coins.list(per_page=9999)  # over the plan cap -> 422
+except ValidationError as err:
+    print(err.code, err.details)
+except RateLimitError as err:
+    print("retry after", err.retry_after)
+except APIError as err:
+    print(err.status, err.message)
+```
+
+| Status | Exception |
+| ------ | --------- |
+| 401 | `AuthenticationError` |
+| 403 | `PermissionDeniedError` (plan does not include this endpoint) |
+| 404 | `NotFoundError` |
+| 422 | `ValidationError` (`.details` holds the field errors) |
+| 429 | `RateLimitError` (`.retry_after`) |
+| 5xx | `ServerError` |
+
+Timeouts raise `APITimeoutError`; network failures raise `APIConnectionError`.
+
+## Quota
+
+Every response carries `X-Quota-*` headers, surfaced on the client after each call:
+
+```python
+client.coins.list()
+print(client.quota)   # Quota(limit=..., remaining=..., reset=..., raw={...})
+```
+
+## Configuration
+
+```python
+Bitculator(
+    api_key,                          # required (positional)
+    base_url="https://bitculator.com",  # default
+    timeout=30.0,                     # seconds, default
+    max_retries=2,                    # auto-retry 429 / 5xx / network; 0 to disable
+)
+```
+
+## Passing parameters
+
+Query parameters are keyword arguments and mirror the API's names exactly
+(`per_page`, `min_price`, ...). For the reserved word `from` (in `convert`), pass
+`from_` — the SDK maps it back to `from` on the wire:
+
+```python
+client.conversion.convert(from_="btc", to="usd", amount=1)
+```
+
+## Resources
+
+`coins` · `prices` · `markets` · `exchanges` · `wallets` · `global_market` ·
+`sentiment` · `indicators` · `liquidations` · `conversion` · `calculators` ·
+`editorial` · `alarms` · `webhooks` · `meta`
+
+Full endpoint reference: <https://bitculator.com/en/documentation/api/v1>.
+
+## License
+
+MIT

bitculator-1.0.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+bitculator/__init__.py,sha256=s5kZCaC2slta55r6fZFoA1XtrW_Ur0zCU7FQghIOOtY,756
+bitculator/_http.py,sha256=su9sQwsoCsOe5Z5knJGjtFYLT2P7Jy6LZ4jzRx1NK4A,8019
+bitculator/_version.py,sha256=Z3eiQCE7mmbeS0xWQqezhPLXUAoEaeLJBVI1TPuNVRU,150
+bitculator/client.py,sha256=2cI3Cw4fdaonrSQK2upU387H_VLa1WYsxY7QSJXsEPA,2760
+bitculator/errors.py,sha256=MGD7VODalgG1EWH3jSffCvdZYHlUZF5u0kCNOOkINlw,3570
+bitculator/pagination.py,sha256=B-x-WefqgmQJE2E_ZkxeDk_C1LDZBskUVKDl94_nAr0,2200
+bitculator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bitculator/resources/__init__.py,sha256=rcJwyzPxSTo-hr7UdiAanv6bXgYPskzi7oEn09lt9xA,777
+bitculator/resources/_base.py,sha256=YzA5cqiWfWgmCQc0SPmTdNrygEnFb_BHuurdRfGW9zw,492
+bitculator/resources/account.py,sha256=V5UbbgewXb1icDXuq1U5s9U5GR4fc7gFGs6hfQFdSNY,2570
+bitculator/resources/coins.py,sha256=559KBjhgUO6BCQ1TJLsRIkW-0TZVo4PHpT43jvrUhMw,3224
+bitculator/resources/editorial.py,sha256=TZ3_3CSJcJTrcxoxj5Z84Gb0TU23-agHKA_JuF3y1A0,1902
+bitculator/resources/indicators.py,sha256=01EyAAKguU6S0or96rgY-8Isl48SpRSOyUoGIjx4OIw,3949
+bitculator/resources/market.py,sha256=e4PBKDbrO4g5DBh4d62CUCzA3XrP_KeC1x1U5QRc2EU,3003
+bitculator/resources/markets.py,sha256=xhJgkaRkLPGswA3Tl6JT07rLY1F5JS3c0aRmjIDD_wY,3932
+bitculator-1.0.0.dist-info/METADATA,sha256=3I42OhDqRufhqci2-x8pK48dHPXqe1DIa8S55Ug0IoQ,4481
+bitculator-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+bitculator-1.0.0.dist-info/licenses/LICENSE,sha256=IiTpcYvOjmCuzZyrQrcY410bxaA52Cho8PYj6S1sjJA,1067
+bitculator-1.0.0.dist-info/RECORD,,

bitculator-1.0.0.dist-info/WHEEL

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

bitculator-1.0.0.dist-info/licenses/LICENSE

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