kingpulse-sdk 1.0.0__tar.gz

kingpulse_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: kingpulse-sdk
+Version: 1.0.0
+Summary: Official Python client for the KingPulse Developer API
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# kingpulse-sdk
+
+Official, dependency-free Python client for the KingPulse Developer API.
+
+Install from PyPI:
+
+```bash
+python3 -m pip install kingpulse-sdk
+```
+
+```python
+import os
+from kingpulse_sdk import KingPulseClient
+
+client = KingPulseClient(api_key=os.environ["KINGPULSE_API_KEY"])
+markets = client.list_markets(q="KING", limit=10)
+created = client.create_paper_bot({
+    "name": "EMA hourly",
+    "strategy": "ema",
+    "marketAddress": "0x1111111111111111111111111111111111111111",
+    "interval": "1h",
+    "initialQuote": "10000",
+})
+print(markets, created["bot"]["id"])
+```
+
+Methods: `list_markets`, `get_market`, `list_tokens`, `list_swaps`, `list_candles`, `list_liquidity`, `get_stats`, `list_paper_bots`, `create_paper_bot`, and `delete_paper_bot`.
+
+## Safety
+
+- Keep the key in a server-side environment variable or secret manager; do not put it in a browser, public app, or source control.
+- Bot API calls create **inactive paper profiles only**. They do not execute strategies, sign transactions, or place live trades.
+- Catch `KingPulseApiError` to inspect `status`, `body`, and `rate_limit`. Network errors are raised by Python's `urllib`.
+- HTTPS is required except for localhost development. The default origin is `https://kingel3ba.com`.
+
+The public PyPI release is pending initial registry publication.

kingpulse_sdk-1.0.0/README.md

@@ -0,0 +1,36 @@
+# kingpulse-sdk
+
+Official, dependency-free Python client for the KingPulse Developer API.
+
+Install from PyPI:
+
+```bash
+python3 -m pip install kingpulse-sdk
+```
+
+```python
+import os
+from kingpulse_sdk import KingPulseClient
+
+client = KingPulseClient(api_key=os.environ["KINGPULSE_API_KEY"])
+markets = client.list_markets(q="KING", limit=10)
+created = client.create_paper_bot({
+    "name": "EMA hourly",
+    "strategy": "ema",
+    "marketAddress": "0x1111111111111111111111111111111111111111",
+    "interval": "1h",
+    "initialQuote": "10000",
+})
+print(markets, created["bot"]["id"])
+```
+
+Methods: `list_markets`, `get_market`, `list_tokens`, `list_swaps`, `list_candles`, `list_liquidity`, `get_stats`, `list_paper_bots`, `create_paper_bot`, and `delete_paper_bot`.
+
+## Safety
+
+- Keep the key in a server-side environment variable or secret manager; do not put it in a browser, public app, or source control.
+- Bot API calls create **inactive paper profiles only**. They do not execute strategies, sign transactions, or place live trades.
+- Catch `KingPulseApiError` to inspect `status`, `body`, and `rate_limit`. Network errors are raised by Python's `urllib`.
+- HTTPS is required except for localhost development. The default origin is `https://kingel3ba.com`.
+
+The public PyPI release is pending initial registry publication.

kingpulse_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kingpulse-sdk"
+version = "1.0.0"
+description = "Official Python client for the KingPulse Developer API"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+readme = "README.md"
+dependencies = []
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

kingpulse_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kingpulse_sdk-1.0.0/src/kingpulse_sdk/__init__.py

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

kingpulse_sdk-1.0.0/src/kingpulse_sdk/client.py

@@ -0,0 +1,128 @@
+import json
+import re
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode, urlsplit, urlunsplit
+from urllib.request import Request, urlopen
+
+DEFAULT_BASE_URL = "https://kingel3ba.com"
+API_KEY_PATTERN = re.compile(r"^kpl_[A-Za-z0-9_-]{43}$")
+BOT_ID_PATTERN = re.compile(r"^[a-f0-9]{24}$")
+
+
+class KingPulseApiError(Exception):
+    def __init__(self, message, *, status, body, headers):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.rate_limit = {
+            "limit": headers.get("RateLimit-Limit"),
+            "remaining": headers.get("RateLimit-Remaining"),
+            "reset": headers.get("RateLimit-Reset"),
+            "retry_after": headers.get("Retry-After"),
+        }
+
+
+class KingPulseClient:
+    """Official client for read-only market data and paper-bot profiles."""
+
+    def __init__(self, api_key, base_url=DEFAULT_BASE_URL, timeout=15):
+        if not isinstance(api_key, str) or not API_KEY_PATTERN.fullmatch(api_key):
+            raise ValueError("Provide a valid KingPulse API key.")
+        if not isinstance(timeout, (int, float)) or timeout <= 0:
+            raise ValueError("Request timeout must be greater than zero.")
+
+        parts = urlsplit(base_url)
+        local_http = parts.scheme == "http" and parts.hostname in {
+            "localhost", "127.0.0.1", "::1"
+        }
+        if parts.scheme != "https" and not local_http:
+            raise ValueError("KingPulse API base URL must use HTTPS (HTTP is allowed for localhost).")
+        if parts.username or parts.password or parts.query or parts.fragment:
+            raise ValueError("KingPulse API base URL must not contain credentials, query, or fragment.")
+
+        self._api_key = api_key
+        self._base_url = urlunsplit((
+            parts.scheme, parts.netloc, parts.path.rstrip("/") + "/", "", ""
+        ))
+        self._timeout = timeout
+
+    def request(self, path, *, method="GET", query=None, body=None):
+        if not isinstance(path, str) or not path.startswith("/api/v1/") or path.startswith("//"):
+            raise ValueError("KingPulse API paths must be relative /api/v1/ paths.")
+        query_string = urlencode(
+            [(key, item) for key, value in (query or {}).items()
+             if value is not None and value != ""
+             for item in (value if isinstance(value, (list, tuple)) else [value])]
+        )
+        url = self._base_url + path[1:] + (f"?{query_string}" if query_string else "")
+        data = None if body is None else json.dumps(body).encode("utf-8")
+        headers = {"Accept": "application/json", "X-API-Key": self._api_key}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        request = Request(url, data=data, headers=headers, method=method)
+
+        try:
+            with urlopen(request, timeout=self._timeout) as response:
+                status = response.status
+                response_headers = response.headers
+                raw = response.read()
+        except HTTPError as error:
+            status = error.code
+            response_headers = error.headers
+            raw = error.read()
+        except URLError:
+            raise
+
+        content_type = response_headers.get("Content-Type", "")
+        if "application/json" in content_type:
+            try:
+                response_body = json.loads(raw.decode("utf-8"))
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                response_body = {"error": "KingPulse API returned invalid JSON."}
+        else:
+            text = raw.decode("utf-8", errors="replace")
+            response_body = {"error": text} if text else None
+
+        if not 200 <= status < 300:
+            message = (
+                response_body.get("error")
+                if isinstance(response_body, dict)
+                else None
+            ) or f"KingPulse API request failed ({status})."
+            raise KingPulseApiError(
+                message, status=status, body=response_body, headers=response_headers
+            )
+        return response_body
+
+    def list_markets(self, **params):
+        return self.request("/api/v1/markets", query=params)
+
+    def get_market(self, pair_address):
+        from urllib.parse import quote
+        return self.request(f"/api/v1/markets/{quote(pair_address, safe='')}")
+
+    def list_tokens(self, **params):
+        return self.request("/api/v1/tokens", query=params)
+
+    def list_swaps(self, **params):
+        return self.request("/api/v1/swaps", query=params)
+
+    def list_candles(self, **params):
+        return self.request("/api/v1/candles", query=params)
+
+    def list_liquidity(self, **params):
+        return self.request("/api/v1/liquidity", query=params)
+
+    def get_stats(self, **params):
+        return self.request("/api/v1/stats", query=params)
+
+    def list_paper_bots(self):
+        return self.request("/api/v1/paper-bots")
+
+    def create_paper_bot(self, configuration):
+        return self.request("/api/v1/paper-bots", method="POST", body=configuration)
+
+    def delete_paper_bot(self, bot_id):
+        if not isinstance(bot_id, str) or not BOT_ID_PATTERN.fullmatch(bot_id):
+            raise ValueError("Paper bot ID is invalid.")
+        return self.request(f"/api/v1/paper-bots/{bot_id}", method="DELETE")

kingpulse_sdk-1.0.0/src/kingpulse_sdk.egg-info/PKG-INFO

@@ -0,0 +1,44 @@
+Metadata-Version: 2.4
+Name: kingpulse-sdk
+Version: 1.0.0
+Summary: Official Python client for the KingPulse Developer API
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# kingpulse-sdk
+
+Official, dependency-free Python client for the KingPulse Developer API.
+
+Install from PyPI:
+
+```bash
+python3 -m pip install kingpulse-sdk
+```
+
+```python
+import os
+from kingpulse_sdk import KingPulseClient
+
+client = KingPulseClient(api_key=os.environ["KINGPULSE_API_KEY"])
+markets = client.list_markets(q="KING", limit=10)
+created = client.create_paper_bot({
+    "name": "EMA hourly",
+    "strategy": "ema",
+    "marketAddress": "0x1111111111111111111111111111111111111111",
+    "interval": "1h",
+    "initialQuote": "10000",
+})
+print(markets, created["bot"]["id"])
+```
+
+Methods: `list_markets`, `get_market`, `list_tokens`, `list_swaps`, `list_candles`, `list_liquidity`, `get_stats`, `list_paper_bots`, `create_paper_bot`, and `delete_paper_bot`.
+
+## Safety
+
+- Keep the key in a server-side environment variable or secret manager; do not put it in a browser, public app, or source control.
+- Bot API calls create **inactive paper profiles only**. They do not execute strategies, sign transactions, or place live trades.
+- Catch `KingPulseApiError` to inspect `status`, `body`, and `rate_limit`. Network errors are raised by Python's `urllib`.
+- HTTPS is required except for localhost development. The default origin is `https://kingel3ba.com`.
+
+The public PyPI release is pending initial registry publication.

kingpulse_sdk-1.0.0/src/kingpulse_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/kingpulse_sdk/__init__.py
+src/kingpulse_sdk/client.py
+src/kingpulse_sdk.egg-info/PKG-INFO
+src/kingpulse_sdk.egg-info/SOURCES.txt
+src/kingpulse_sdk.egg-info/dependency_links.txt
+src/kingpulse_sdk.egg-info/top_level.txt
+tests/test_client.py

kingpulse_sdk-1.0.0/src/kingpulse_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kingpulse_sdk-1.0.0/src/kingpulse_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+kingpulse_sdk

kingpulse_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,88 @@
+import unittest
+from unittest.mock import patch
+from urllib.error import HTTPError
+from email.message import Message
+import io
+import json
+
+from kingpulse_sdk import KingPulseApiError, KingPulseClient
+
+
+API_KEY = "kpl_" + "a" * 43
+
+
+class FakeResponse:
+    status = 200
+    headers = {"Content-Type": "application/json", "RateLimit-Remaining": "29"}
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_args):
+        return False
+
+    def read(self):
+        return b'{"ok":true,"bots":[]}'
+
+
+class KingPulseClientTests(unittest.TestCase):
+    def test_sends_api_key_and_creates_paper_bot(self):
+        with patch("kingpulse_sdk.client.urlopen", return_value=FakeResponse()) as urlopen:
+            client = KingPulseClient(API_KEY)
+            response = client.create_paper_bot({
+                "name": "EMA",
+                "strategy": "ema",
+                "marketAddress": "0x1111111111111111111111111111111111111111",
+                "interval": "1h",
+            })
+
+        request = urlopen.call_args.args[0]
+        self.assertEqual(request.get_header("X-api-key"), API_KEY)
+        self.assertEqual(request.method, "POST")
+        self.assertEqual(json.loads(request.data), {
+            "name": "EMA",
+            "strategy": "ema",
+            "marketAddress": "0x1111111111111111111111111111111111111111",
+            "interval": "1h",
+        })
+        self.assertTrue(response["ok"])
+
+    def test_encodes_query_and_uses_market_data_methods(self):
+        with patch("kingpulse_sdk.client.urlopen", return_value=FakeResponse()) as urlopen:
+            KingPulseClient(API_KEY).list_markets(q="KING & MON", limit=10)
+        self.assertIn("q=KING+%26+MON", urlopen.call_args.args[0].full_url)
+        self.assertIn("limit=10", urlopen.call_args.args[0].full_url)
+
+    def test_reports_api_errors_and_rate_limits(self):
+        headers = Message()
+        headers["Content-Type"] = "application/json"
+        headers["RateLimit-Remaining"] = "0"
+        headers["Retry-After"] = "12"
+        error = HTTPError(
+            "https://kingel3ba.com/api/v1/paper-bots",
+            429,
+            "rate limited",
+            headers,
+            io.BytesIO(b'{"error":"slow down"}'),
+        )
+        with patch("kingpulse_sdk.client.urlopen", side_effect=error):
+            with self.assertRaises(KingPulseApiError) as caught:
+                KingPulseClient(API_KEY).list_paper_bots()
+        self.assertEqual(caught.exception.status, 429)
+        self.assertEqual(caught.exception.body["error"], "slow down")
+        self.assertEqual(caught.exception.rate_limit["retry_after"], "12")
+
+    def test_rejects_bad_key_url_path_and_bot_id(self):
+        with self.assertRaises(ValueError):
+            KingPulseClient("not-a-key")
+        with self.assertRaises(ValueError):
+            KingPulseClient(API_KEY, "http://example.com")
+        client = KingPulseClient(API_KEY)
+        with self.assertRaises(ValueError):
+            client.request("//attacker.invalid/api/v1/paper-bots")
+        with self.assertRaises(ValueError):
+            client.delete_paper_bot("../other")
+
+
+if __name__ == "__main__":
+    unittest.main()