echozero 0.1.0__tar.gz

echozero-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+target/
+dist/
+node_modules/
+.venv/
+.env.local
+.env.*.local

echozero-0.1.0/LICENSE

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

echozero-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.5
+Name: echozero
+Version: 0.1.0
+Summary: Official Python SDK for EchoZero REST, MCP, webhooks, and signal streams.
+Project-URL: Homepage, https://docs.echozero.app/guides/sdk
+Project-URL: Repository, https://github.com/EchoZeroApp/echozero-sdk
+Project-URL: Issues, https://github.com/EchoZeroApp/echozero-sdk/issues
+Author-email: Echo Zero <support@echozero.app>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: copy-trading,echozero,hmac,hyperliquid,solana,trading,webhooks
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Requires-Dist: websocket-client>=1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# echozero
+
+MIT-licensed Python SDK for EchoZero.
+
+## Install
+
+```bash
+pip install echozero
+```
+
+## REST Client
+
+```py
+import os
+from echozero import EchoZeroClient
+
+client = EchoZeroClient(
+    base_url="https://mcp.echozero.app",
+    api_key=os.environ["ECHOZERO_API_KEY"],
+)
+
+print(client.get("/api/v1/users/me"))
+```
+
+## Inbound Webhook Signing
+
+```py
+from echozero import sign_inbound_webhook
+
+body = {"text": "BUY SOL 500 USDC"}
+headers = sign_inbound_webhook(
+    signing_secret="ezw_secret",
+    body=body,
+)
+```

echozero-0.1.0/README.md

@@ -0,0 +1,35 @@
+# echozero
+
+MIT-licensed Python SDK for EchoZero.
+
+## Install
+
+```bash
+pip install echozero
+```
+
+## REST Client
+
+```py
+import os
+from echozero import EchoZeroClient
+
+client = EchoZeroClient(
+    base_url="https://mcp.echozero.app",
+    api_key=os.environ["ECHOZERO_API_KEY"],
+)
+
+print(client.get("/api/v1/users/me"))
+```
+
+## Inbound Webhook Signing
+
+```py
+from echozero import sign_inbound_webhook
+
+body = {"text": "BUY SOL 500 USDC"}
+headers = sign_inbound_webhook(
+    signing_secret="ezw_secret",
+    body=body,
+)
+```

echozero-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "echozero"
+version = "0.1.0"
+description = "Official Python SDK for EchoZero REST, MCP, webhooks, and signal streams."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Echo Zero", email = "support@echozero.app" }]
+keywords = ["echozero", "trading", "copy-trading", "webhooks", "hmac", "solana", "hyperliquid"]
+dependencies = ["requests>=2.31.0", "websocket-client>=1.8.0"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12"
+]
+
+[project.urls]
+Homepage = "https://docs.echozero.app/guides/sdk"
+Repository = "https://github.com/EchoZeroApp/echozero-sdk"
+Issues = "https://github.com/EchoZeroApp/echozero-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/echozero"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

echozero-0.1.0/src/echozero/__init__.py

@@ -0,0 +1,28 @@
+from .client import EchoZeroApiError, EchoZeroClient
+from .hmac import (
+    canonical_webhook_body,
+    sign_inbound_webhook,
+    sign_rest_request,
+    stable_json,
+    verify_inbound_webhook,
+    verify_outbound_webhook,
+)
+from .inbound_canonical import inbound_webhook_canonical_json, rest_request_body_text
+from .signals import AgentSignalResponse, OutboundExecutionWebhook
+from .websocket import EchoZeroSignalClient
+
+__all__ = [
+    "AgentSignalResponse",
+    "EchoZeroApiError",
+    "EchoZeroClient",
+    "EchoZeroSignalClient",
+    "OutboundExecutionWebhook",
+    "canonical_webhook_body",
+    "inbound_webhook_canonical_json",
+    "rest_request_body_text",
+    "sign_inbound_webhook",
+    "sign_rest_request",
+    "stable_json",
+    "verify_inbound_webhook",
+    "verify_outbound_webhook",
+]

echozero-0.1.0/src/echozero/client.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+import requests
+
+from .hmac import sign_inbound_webhook, sign_rest_request
+from .inbound_canonical import rest_request_body_text
+
+
+class EchoZeroApiError(RuntimeError):
+    def __init__(self, message: str, status: int, code: str | None = None, payload: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.payload = payload
+
+
+class EchoZeroClient:
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://mcp.echozero.app",
+        api_key: str | None = None,
+        bearer_token: str | None = None,
+        hmac_secret_key: str | None = None,
+        session: requests.Session | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.bearer_token = bearer_token
+        self.hmac_secret_key = hmac_secret_key
+        self.session = session or requests.Session()
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, json_body: Any | None = None, **kwargs: Any) -> Any:
+        return self.request("POST", path, json_body=json_body, **kwargs)
+
+    def patch(self, path: str, json_body: Any | None = None, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, json_body=json_body, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    def post_agent_signal(
+        self,
+        agent_id: str,
+        body: Mapping[str, Any],
+        signing_secret: str,
+    ) -> Any:
+        webhook_headers = sign_inbound_webhook(signing_secret=signing_secret, body=body)
+        return self.post(
+            f"/api/public/agent-signals/{agent_id}",
+            json_body=dict(body),
+            headers={
+                "X-EZ-Timestamp": webhook_headers["X-EZ-Timestamp"],
+                "X-EZ-Signature": webhook_headers["X-EZ-Signature"],
+            },
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        json_body: Any | None = None,
+        headers: Mapping[str, str] | None = None,
+        hmac: bool = False,
+    ) -> Any:
+        url = self._url(path, query)
+        request_headers = {"Accept": "application/json", **(headers or {})}
+        if self.bearer_token:
+            request_headers["Authorization"] = f"Bearer {self.bearer_token}"
+        elif self.api_key:
+            request_headers["x-api-key"] = self.api_key
+
+        body_bytes: bytes | None = None
+        body_text = ""
+        if json_body is not None:
+            body_text = rest_request_body_text(json_body)
+            body_bytes = body_text.encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+
+        if hmac:
+            if not self.hmac_secret_key:
+                raise ValueError("hmac_secret_key is required when hmac=True")
+            request_headers.update(
+                sign_rest_request(
+                    secret_key=self.hmac_secret_key,
+                    method=method,
+                    path=self._path_with_query(path, query),
+                    body=body_text if json_body is not None else None,
+                )
+            )
+
+        response = self.session.request(
+            method.upper(),
+            url,
+            data=body_bytes,
+            headers=request_headers,
+        )
+        payload = self._read_json(response)
+        if not response.ok:
+            error = payload.get("error", {}) if isinstance(payload, dict) else {}
+            raise EchoZeroApiError(
+                error.get("message") or response.reason,
+                response.status_code,
+                error.get("code"),
+                payload,
+            )
+        if isinstance(payload, dict) and payload.get("success") is True and "data" in payload:
+            return payload["data"]
+        return payload
+
+    def _url(self, path: str, query: Mapping[str, Any] | None = None) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            base = path
+        else:
+            base = f"{self.base_url}{path if path.startswith('/') else f'/{path}'}"
+        from urllib.parse import urlencode
+
+        query_string = urlencode({k: v for k, v in (query or {}).items() if v is not None})
+        return f"{base}?{query_string}" if query_string else base
+
+    def _path_with_query(self, path: str, query: Mapping[str, Any] | None = None) -> str:
+        if path.startswith("http://") or path.startswith("https://"):
+            from urllib.parse import urlparse
+
+            parsed = urlparse(path)
+            path = parsed.path + (f"?{parsed.query}" if parsed.query else "")
+        from urllib.parse import urlencode
+
+        query_string = urlencode({k: v for k, v in (query or {}).items() if v is not None})
+        return f"{path}?{query_string}" if query_string else path
+
+    @staticmethod
+    def _read_json(response: requests.Response) -> Any:
+        if not response.text:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            return response.text

echozero-0.1.0/src/echozero/hmac.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping
+
+from .inbound_canonical import inbound_webhook_canonical_json, rest_request_body_text
+
+
+def stable_json(value: Any) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _hmac_sha256_hex(secret: str, payload: str) -> str:
+    return hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
+
+
+def sign_rest_request(
+    *,
+    secret_key: str,
+    method: str,
+    path: str,
+    body: Any | None = None,
+    timestamp_ms: int | None = None,
+) -> dict[str, str]:
+    timestamp = str(timestamp_ms or int(time.time() * 1000))
+    body_text = rest_request_body_text(body)
+    payload = f"{timestamp}{method.upper()}{path}{body_text}"
+    return {
+        "x-timestamp": timestamp,
+        "x-signature": _hmac_sha256_hex(secret_key, payload),
+    }
+
+
+def canonical_webhook_body(body: Mapping[str, Any]) -> str:
+    return inbound_webhook_canonical_json(body)
+
+
+def sign_inbound_webhook(
+    *,
+    signing_secret: str,
+    body: Mapping[str, Any],
+    timestamp_seconds: int | None = None,
+) -> dict[str, str]:
+    timestamp = str(timestamp_seconds or int(time.time()))
+    canonical = inbound_webhook_canonical_json(body)
+    return {
+        "X-EZ-Timestamp": timestamp,
+        "X-EZ-Signature": _hmac_sha256_hex(signing_secret, f"{timestamp}.{canonical}"),
+    }
+
+
+def verify_inbound_webhook(
+    *,
+    signing_secret: str,
+    body: Mapping[str, Any],
+    timestamp_seconds: int | str,
+    signature: str,
+    max_skew_seconds: int = 300,
+) -> bool:
+    try:
+        timestamp = int(timestamp_seconds)
+    except (TypeError, ValueError):
+        return False
+    if abs(int(time.time()) - timestamp) > max_skew_seconds:
+        return False
+    expected = sign_inbound_webhook(
+        signing_secret=signing_secret,
+        body=body,
+        timestamp_seconds=timestamp,
+    )["X-EZ-Signature"]
+    return hmac.compare_digest(expected, signature.lower())
+
+
+def verify_outbound_webhook(
+    *,
+    secret_key: str,
+    raw_body: str,
+    timestamp: str,
+    signature: str,
+) -> bool:
+    expected = _hmac_sha256_hex(secret_key, f"{timestamp}.{raw_body}")
+    return hmac.compare_digest(expected, signature.lower())

echozero-0.1.0/src/echozero/inbound_canonical.py

@@ -0,0 +1,98 @@
+"""Mirrors `agentInboundWebhook.signing.ts` in mcp-main."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping
+
+STRUCTURED_SIGNING_KEYS = (
+    "action",
+    "amount",
+    "chain",
+    "changes",
+    "clientTimestamp",
+    "confidence",
+    "context",
+    "currentPnlPct",
+    "entryPrice",
+    "entryZone",
+    "eventType",
+    "exitPrice",
+    "exitReason",
+    "expiresAt",
+    "ideaId",
+    "instrument",
+    "leverageX",
+    "metadata",
+    "orderType",
+    "pnlPct",
+    "positionRef",
+    "reasoning",
+    "relatedTradeId",
+    "riskMgmt",
+    "sellSizePct",
+    "side",
+    "symbol",
+    "tokenAddress",
+    "tradeType",
+    "triggers",
+    "urgency",
+    "version",
+)
+
+
+def _canonicalize_value(value: Any) -> Any | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float)):
+        if isinstance(value, float) and (value != value or value in (float("inf"), float("-inf"))):
+            return None
+        return value
+    if isinstance(value, list):
+        return [_canonicalize_value(item) for item in value]
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        for key in sorted(value):
+            child = _canonicalize_value(value[key])
+            if child is not None or value[key] is None:
+                out[key] = child
+        return out
+    return None
+
+
+def inbound_webhook_canonical_json(body: Mapping[str, Any]) -> str:
+    sorted_body: dict[str, Any] = {}
+
+    if "text" in body and body["text"] is not None:
+        sorted_body["text"] = body["text"]
+
+    idk = body.get("idempotencyKey")
+    if isinstance(idk, str):
+        trimmed = idk.strip()
+        if trimmed:
+            sorted_body["idempotencyKey"] = trimmed
+
+    for key in STRUCTURED_SIGNING_KEYS:
+        if key not in body:
+            continue
+        value = _canonicalize_value(body[key])
+        if value is not None or body[key] is None:
+            sorted_body[key] = value
+
+    return json.dumps(
+        {key: sorted_body[key] for key in sorted(sorted_body)},
+        separators=(",", ":"),
+        ensure_ascii=False,
+    )
+
+
+def rest_request_body_text(body: Any | None) -> str:
+    if body is None:
+        return ""
+    if isinstance(body, str):
+        return body
+    return json.dumps(body, separators=(",", ":"), ensure_ascii=False)

echozero-0.1.0/src/echozero/signals.py

@@ -0,0 +1,38 @@
+"""Structured signal envelope types (#1098)."""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+StructuredSignalEventType = Literal[
+    "trade_idea",
+    "buy",
+    "scale_in",
+    "sell",
+    "partial_sell",
+    "amend",
+    "breakeven",
+    "cancel",
+    "position_update",
+    "trade_review",
+]
+
+StructuredSignalChain = Literal["solana", "hyperliquid"]
+StructuredSignalSide = Literal["long", "short"]
+StructuredSignalTradeType = Literal["spot", "perp", "virtual"]
+
+
+class AgentSignalResponse(TypedDict, total=False):
+    outcome: Literal["matched", "unmatched", "skipped", "error"]
+    signalId: str
+    status: str
+    skipReason: str
+
+
+class OutboundExecutionWebhook(TypedDict, total=False):
+    event: Literal["signal.execution", "signal.execution.failed"]
+    signalId: str
+    developerAgentId: str
+    status: str
+    executionResult: dict[str, object]
+    timestamp: str

echozero-0.1.0/src/echozero/websocket.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+from urllib.parse import urlencode
+
+from websocket import WebSocketApp
+
+
+class EchoZeroSignalClient:
+    def __init__(
+        self,
+        *,
+        url: str,
+        api_key: str | None = None,
+        bearer_token: str | None = None,
+    ):
+        params = {}
+        if api_key:
+            params["api_key"] = api_key
+        if bearer_token:
+            params["access_token"] = bearer_token
+        query = urlencode(params)
+        self.url = f"{url}?{query}" if query else url
+        self.socket: WebSocketApp | None = None
+
+    def connect(
+        self,
+        on_message: Callable[[Any], None],
+        on_error: Callable[[Exception], None] | None = None,
+    ) -> WebSocketApp:
+        def handle_message(_: WebSocketApp, message: str) -> None:
+            try:
+                on_message(json.loads(message))
+            except json.JSONDecodeError:
+                on_message(message)
+
+        self.socket = WebSocketApp(
+            self.url,
+            on_message=handle_message,
+            on_error=lambda _, err: on_error(err) if on_error else None,
+        )
+        return self.socket
+
+    def send_signal(self, signal: Any) -> None:
+        if not self.socket:
+            raise RuntimeError("Signal WebSocket is not connected")
+        self.socket.send(json.dumps({"event": "signal", "data": signal}))

echozero-0.1.0/tests/test_hmac.py

@@ -0,0 +1,131 @@
+import json
+
+import pytest
+
+from echozero.hmac import (
+    sign_inbound_webhook,
+    sign_rest_request,
+    verify_inbound_webhook,
+    verify_outbound_webhook,
+)
+from echozero.inbound_canonical import inbound_webhook_canonical_json, rest_request_body_text
+
+
+def test_sign_rest_request_matches_backend_vector():
+    headers = sign_rest_request(
+        secret_key="test_secret",
+        method="POST",
+        path="/api/api-keys",
+        body={"name": "SDK HMAC Test"},
+        timestamp_ms=1_710_000_000_000,
+    )
+    assert (
+        headers["x-signature"]
+        == "274c9ff280eadf751530e9e7fce2c2a573d8676b13b7108fe353407df7cc9e00"
+    )
+
+
+def test_rest_request_body_text_matches_signed_bytes():
+    body = {"zzz": "y", "name": "x"}
+    body_text = rest_request_body_text(body)
+    assert body_text == json.dumps(body, separators=(",", ":"), ensure_ascii=False)
+    headers_a = sign_rest_request(
+        secret_key="secret",
+        method="POST",
+        path="/api/api-keys",
+        body=body_text,
+        timestamp_ms=123,
+    )
+    headers_b = sign_rest_request(
+        secret_key="secret",
+        method="POST",
+        path="/api/api-keys",
+        body=body,
+        timestamp_ms=123,
+    )
+    assert headers_a == headers_b
+
+
+def test_inbound_canonical_strips_unknown_fields():
+    assert (
+        inbound_webhook_canonical_json({"text": "BUY SOL", "extraField": "ignored"})
+        == '{"text":"BUY SOL"}'
+    )
+
+
+def test_sign_inbound_webhook_matches_backend_vector():
+    headers = sign_inbound_webhook(
+        signing_secret="test_secret",
+        body={"text": "BUY SOL 500 USDC", "idempotencyKey": "sdk-test-1"},
+        timestamp_seconds=1_710_000_000,
+    )
+    assert (
+        headers["X-EZ-Signature"]
+        == "1d30d896fc609e62bcf9be991c1dc1177a9c63219909869ef2846bad4685de3b"
+    )
+
+
+def test_sign_inbound_webhook_ignores_unknown_fields():
+    body = {
+        "eventType": "buy",
+        "idempotencyKey": "test-1",
+        "reasoning": "test",
+        "tokenAddress": "So11111111111111111111111111111111111111112",
+        "amount": 500,
+    }
+    with_extra = {**body, "unknownField": "strip me"}
+    a = sign_inbound_webhook(
+        signing_secret="secret", body=body, timestamp_seconds=1_710_000_000
+    )
+    b = sign_inbound_webhook(
+        signing_secret="secret", body=with_extra, timestamp_seconds=1_710_000_000
+    )
+    assert a == b
+    assert (
+        a["X-EZ-Signature"]
+        == "be420f61d91e6b871481774c62f972f0aafa6f5f1a727ba1e4a32558784f77c3"
+    )
+
+
+def test_verify_inbound_webhook_accepts_valid_signature():
+    body = {"text": "BUY SOL 500 USDC", "idempotencyKey": "sdk-test-1"}
+    headers = sign_inbound_webhook(
+        signing_secret="test_secret",
+        body=body,
+        timestamp_seconds=1_710_000_000,
+    )
+    assert verify_inbound_webhook(
+        signing_secret="test_secret",
+        body=body,
+        timestamp_seconds=headers["X-EZ-Timestamp"],
+        signature=headers["X-EZ-Signature"],
+        max_skew_seconds=999_999_999,
+    )
+
+
+def test_verify_outbound_webhook():
+    raw_body = json.dumps(
+        {
+            "event": "signal.execution",
+            "signalId": "sig_1",
+            "developerAgentId": "agent_1",
+            "status": "executed",
+            "timestamp": "2026-07-06T12:00:00.000Z",
+        },
+        separators=(",", ":"),
+    )
+    timestamp = "2026-07-06T12:00:00.000Z"
+    import hashlib
+    import hmac as hmac_mod
+
+    signature = hmac_mod.new(
+        b"webhook_secret",
+        f"{timestamp}.{raw_body}".encode(),
+        hashlib.sha256,
+    ).hexdigest()
+    assert verify_outbound_webhook(
+        secret_key="webhook_secret",
+        raw_body=raw_body,
+        timestamp=timestamp,
+        signature=signature,
+    )