upside-python-sdk 0.1.0__py3-none-any.whl

upside/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility modules: constants, errors, shared types, and EIP-712 signing."""

upside/utils/constants.py

@@ -0,0 +1,49 @@
+"""Environment URLs and protocol constants for the Upside API.
+
+Contract IDs, coin IDs, price/quantity scales, and tick/step sizes are **not**
+constants — they are server-assigned and differ per environment. Always read
+them from ``Info.configs()`` rather than hardcoding.
+"""
+
+# REST + WebSocket base URLs. The base URL is the scheme + host only; the SDK
+# appends ``/info``, ``/exchange`` for REST and derives the ``/ws`` path.
+QA_API_URL = "https://dev.upsidemax.xyz"
+UAT_API_URL = "http://chaindex-chainnode-nlb-fdaf7d3d8c724a80.elb.ap-northeast-1.amazonaws.com:9093"
+# Production URL is not yet published.
+MAINNET_API_URL = QA_API_URL
+
+# EIP-712 signing domain (see https://docs.upsidemax.xyz/guide/authentication).
+CHAIN_ID = 9767
+DOMAIN_NAME = "Exchange"
+DOMAIN_VERSION = "1"
+VERIFYING_CONTRACT = "0x0000000000000000000000000000000000000000"
+# Source string folded into the Agent-path struct.
+AGENT_SOURCE = "b"
+
+# Batch limits enforced by the gateway.
+MAX_ORDERS_PER_REQUEST = 10
+MAX_CANCELS_PER_REQUEST = 10
+
+# Candle intervals accepted by ``candleSnapshot`` and the ``candle`` WS channel.
+INTERVALS = (
+    "1m",
+    "3m",
+    "5m",
+    "15m",
+    "30m",
+    "1h",
+    "2h",
+    "4h",
+    "8h",
+    "12h",
+    "1d",
+    "3d",
+    "1w",
+    "1M",
+)
+
+# Time-in-force values accepted by the ``order`` action.
+TIF_GTC = "Gtc"
+TIF_IOC = "Ioc"
+TIF_ALO = "Alo"
+TIF_FOK = "Fok"

upside/utils/error.py

@@ -0,0 +1,51 @@
+"""Exception hierarchy for the Upside SDK.
+
+Upside reports failures at two levels:
+
+* **HTTP / gateway level** — a non-2xx response (or a body with
+  ``"status": "error"``) carrying a machine ``code`` and ``message``. These
+  raise :class:`ClientError` (4xx) or :class:`ServerError` (5xx).
+* **Business level** — an HTTP 200 with ``"status": "ok"`` that still contains
+  a per-item ``error`` string inside ``statuses[]`` or a non-zero ``errorCode``
+  inside ``response.data``. These are **not** raised — inspect the returned
+  dict. See https://docs.upsidemax.xyz/guide/error-codes.
+"""
+
+from typing import Optional
+
+
+class UpsideError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIError(UpsideError):
+    """An HTTP/gateway-level rejection from ``/info`` or ``/exchange``.
+
+    Attributes mirror the error envelope
+    ``{"status": "error", "requestId", "code", "message"}``.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: Optional[str] = None,
+        message: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+        self.request_id = request_id
+        super().__init__(f"HTTP {status_code} {code or ''}: {message or ''}".rstrip())
+
+
+class ClientError(APIError):
+    """A 4xx rejection (bad request, signature invalid, nonce reused, ...)."""
+
+
+class ServerError(APIError):
+    """A 5xx error, or a gateway timeout (504) / downstream failure (503)."""
+
+
+class WebsocketError(UpsideError):
+    """Raised for WebSocket subscription/protocol problems."""

upside/utils/signing.py

@@ -0,0 +1,172 @@
+"""EIP-712 request signing for ``POST /exchange``.
+
+Every write is authorized by an ECDSA signature (secp256k1) over an EIP-712
+digest; the server recovers the signer's address — there are no API keys. Two
+signing paths, selected by ``action["type"]``:
+
+* **Typed path** — the six funds/permission actions, each with a field-level
+  struct so a wallet can render human-readable values.
+* **Agent path** — everything else. The whole canonical-JSON action is folded
+  into a single ``actionHash`` carried by ``Agent(string source, bytes32 actionHash)``.
+
+This is a direct port of the reference implementation published at
+https://docs.upsidemax.xyz/guide/authentication — the digest formula must match
+the server byte-for-byte or recovery fails with ``SIGNATURE_INVALID``.
+"""
+
+import json
+import threading
+import time
+from typing import Any, Dict, Union, cast
+
+from eth_account import Account
+from eth_account.signers.local import LocalAccount
+from eth_utils import keccak
+
+from . import constants
+
+Wallet = LocalAccount
+Signature = Dict[str, Any]
+
+
+def _u(value: Union[int, str]) -> bytes:
+    """Encode an unsigned integer as a 32-byte big-endian word."""
+    return int(value).to_bytes(32, "big")
+
+
+def _addr(value: str) -> bytes:
+    """Encode an address as 20 bytes left-padded to 32."""
+    hex_body = value[2:] if value[:2].lower() == "0x" else value
+    return b"\x00" * 12 + bytes.fromhex(hex_body)
+
+
+def _string(value: Any) -> bytes:
+    """Encode a string field as ``keccak256(utf8Bytes)``."""
+    return keccak(str(value).encode())
+
+
+# EIP-712 domain separator: Exchange / v1 / chainId 9767 / verifyingContract 0x0.
+_DOMAIN_SEPARATOR = keccak(
+    keccak(b"EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)")
+    + keccak(constants.DOMAIN_NAME.encode())
+    + keccak(constants.DOMAIN_VERSION.encode())
+    + _u(constants.CHAIN_ID)
+    + b"\x00" * 32
+)
+
+# Funds / permission actions sign a field-level typed struct. Field names match
+# the action's JSON keys, so encodings are derived straight from the type string.
+_TYPED: Dict[str, str] = {
+    "registerAccount": "RegisterAccount(address address,uint64 nonce)",
+    "approveAgent": "ApproveAgent(address agentAddress,string agentName,uint64 validUntil,uint64 nonce)",
+    "revokeAgent": "RevokeAgent(address agentAddress,uint64 nonce)",
+    "lockCollateral": "LockCollateral(uint32 marketDeployerId,uint32 coinId,string amount,uint64 nonce)",
+    "unlockCollateral": "UnlockCollateral(uint32 marketDeployerId,uint32 coinId,string amount,uint64 nonce)",
+    "transferBetweenDeployers": (
+        "TransferBetweenDeployers(uint32 fromMarketDeployerId,uint32 toMarketDeployerId,"
+        "uint32 coinId,string amount,uint64 nonce)"
+    ),
+}
+
+# Optional typed fields MUST still appear in the wire JSON — the server reads
+# them by name to recompute the digest. Inject defaults before signing so the
+# signed struct and the sent JSON match, otherwise recovery yields a different
+# address (401 SIGNATURE_INVALID).
+_TYPED_DEFAULTS: Dict[str, Dict[str, Any]] = {
+    "approveAgent": {"agentName": "", "validUntil": 0},
+}
+
+
+def _encode_field(sol_type: str, value: Any) -> bytes:
+    if sol_type == "address":
+        return _addr(value)
+    if sol_type == "string":
+        return _string(value)
+    return _u(value)  # uintN
+
+
+def _typed_struct(type_str: str, action: Dict[str, Any], nonce: int) -> bytes:
+    fields = [f.split() for f in type_str[type_str.index("(") + 1 : -1].split(",")]
+    encoded = [_encode_field(sol_type, nonce if name == "nonce" else action[name]) for sol_type, name in fields]
+    return keccak(keccak(type_str.encode()) + b"".join(encoded))
+
+
+def action_hash(action: Dict[str, Any], nonce: int) -> bytes:
+    """Agent-path ``actionHash`` = keccak(canonicalJson ‖ nonce_be8)."""
+    canonical = json.dumps(action, sort_keys=True, separators=(",", ":")).encode()
+    return keccak(canonical + int(nonce).to_bytes(8, "big"))
+
+
+def eip712_digest(action: Dict[str, Any], nonce: int) -> bytes:
+    """Compute the 32-byte EIP-712 digest for an action.
+
+    For typed actions this mutates ``action`` to fill required-but-optional
+    fields (e.g. ``agentName``) so the sent JSON matches the signed struct.
+    """
+    type_str = _TYPED.get(action["type"])
+    if type_str is not None:
+        for key, default in _TYPED_DEFAULTS.get(action["type"], {}).items():
+            action.setdefault(key, default)
+        struct = _typed_struct(type_str, action, nonce)
+    else:
+        struct = keccak(
+            keccak(b"Agent(string source,bytes32 actionHash)")
+            + keccak(constants.AGENT_SOURCE.encode())
+            + action_hash(action, nonce)
+        )
+    return keccak(b"\x19\x01" + _DOMAIN_SEPARATOR + struct)
+
+
+def _sign_digest(wallet: Wallet, digest: bytes) -> Any:
+    """Sign a 32-byte digest directly (``prehash = false``), across eth-account versions."""
+    signer = getattr(Account, "unsafe_sign_hash", None) or Account._sign_hash
+    return signer(digest, wallet.key)
+
+
+def sign_action(wallet: Wallet, action: Dict[str, Any], nonce: int) -> Signature:
+    """Return the ``{"r", "s", "v"}`` signature envelope for ``action``.
+
+    ``r``/``s`` are ``0x``-prefixed lowercase 32-byte hex; ``v`` is 27 or 28.
+    """
+    signed = _sign_digest(wallet, eip712_digest(action, nonce))
+    return {
+        "r": "0x" + int(signed.r).to_bytes(32, "big").hex(),
+        "s": "0x" + int(signed.s).to_bytes(32, "big").hex(),
+        "v": signed.v if signed.v >= 27 else signed.v + 27,
+    }
+
+
+def to_wallet(wallet_or_key: Union[Wallet, str]) -> Wallet:
+    """Coerce a private-key hex string into a :class:`LocalAccount`."""
+    if isinstance(wallet_or_key, str):
+        return cast(Wallet, Account.from_key(wallet_or_key))
+    return wallet_or_key
+
+
+class NonceManager:
+    """Thread-safe, strictly increasing millisecond nonce source.
+
+    Each signing address needs unique, monotonic nonces; the server rejects a
+    reused or regressing nonce with ``NONCE_REUSED``. Sub-millisecond bursts are
+    handled by incrementing past the last issued value.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._last = 0
+
+    def next(self) -> int:
+        with self._lock:
+            self._last = max(self._last + 1, int(time.time() * 1000))
+            return self._last
+
+
+__all__ = [
+    "Wallet",
+    "Signature",
+    "NonceManager",
+    "action_hash",
+    "eip712_digest",
+    "sign_action",
+    "to_wallet",
+]

upside/utils/types.py

@@ -0,0 +1,133 @@
+"""Shared types for the Upside SDK.
+
+The SDK keeps two vocabularies:
+
+* the **request** side (Pythonic, ``snake_case``) used by public method
+  signatures and the :class:`OrderRequest` / :class:`ModifyRequest` TypedDicts, and
+* the **wire** side (compact single-letter keys, string numbers) that goes into
+  the signed ``action`` payload.
+
+Conversion between the two happens in :mod:`upside.exchange`. Responses are
+returned as raw parsed JSON (``dict`` / ``list``) — inspect them by key.
+"""
+
+import sys
+from typing import Any, Dict, List, Literal, Optional, Union
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, TypedDict
+else:  # ``NotRequired`` was added to ``typing`` in 3.11
+    from typing_extensions import NotRequired, TypedDict
+
+# Raw JSON returned by ``/info`` and ``/exchange``.
+Json = Union[Dict[str, Any], List[Any]]
+
+# Time-in-force policies accepted by the ``order`` action.
+Tif = Literal["Gtc", "Ioc", "Alo", "Fok"]
+
+# Trigger price feeds for TP/SL: 0 = mark, 1 = index, 2 = last.
+TriggerType = Literal[0, 1, 2]
+
+# Position side for conditional orders / margin ops: 0 = ONE_WAY, 1 = LONG, 2 = SHORT.
+PositionSide = Literal[0, 1, 2]
+
+
+class OrderRequest(TypedDict):
+    """A single order in a (possibly batched) ``order`` action.
+
+    Prices and sizes are **raw integer strings** — scale them with the
+    contract's ``priceScale`` / ``qtyScale`` from ``configs``. ``price`` is
+    required for limit orders and omitted for market orders (``is_market``).
+    """
+
+    asset: int
+    is_buy: bool
+    size: str
+    price: NotRequired[str]
+    reduce_only: NotRequired[bool]
+    tif: NotRequired[Tif]
+    is_market: NotRequired[bool]
+    cloid: NotRequired[str]
+    builder_address: NotRequired[str]
+    builder_fee: NotRequired[int]
+
+
+class CancelRequest(TypedDict):
+    """A single cancel-by-order-id entry."""
+
+    asset: int
+    oid: int
+
+
+class CancelByCloidRequest(TypedDict):
+    """A single cancel-by-client-order-id entry."""
+
+    asset: int
+    cloid: str
+
+
+class Subscription(TypedDict):
+    """A WebSocket subscription object (the ``subscription`` field on the wire).
+
+    ``asset`` is a decimal string contract id; ``user`` is a lowercase wallet
+    address. Only the fields relevant to ``type`` are read.
+    """
+
+    type: str
+    asset: NotRequired[str]
+    interval: NotRequired[str]
+    user: NotRequired[str]
+
+
+class Cloid:
+    """A client order id: a positive ``int64`` sent as a decimal string.
+
+    Upside represents client order ids as ``int64`` decimal strings (unlike
+    Hyperliquid's 128-bit hex cloids). Use this wrapper to build one from an
+    int, a timestamp, or a validated string.
+    """
+
+    __slots__ = ("_value",)
+
+    _MAX = 2**63 - 1
+
+    def __init__(self, raw: str) -> None:
+        value = int(raw)
+        if value <= 0 or value > self._MAX:
+            raise ValueError(f"cloid must be a positive int64 decimal string, got {raw!r}")
+        self._value = value
+
+    @classmethod
+    def from_int(cls, value: int) -> "Cloid":
+        return cls(str(value))
+
+    def to_raw(self) -> str:
+        """The wire representation: a decimal string."""
+        return str(self._value)
+
+    def to_int(self) -> int:
+        return self._value
+
+    def __str__(self) -> str:
+        return self.to_raw()
+
+    def __repr__(self) -> str:
+        return f"Cloid({self.to_raw()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Cloid) and other._value == self._value
+
+    def __hash__(self) -> int:
+        return hash(self._value)
+
+
+def cloid_str(value: Union[str, int, Cloid]) -> str:
+    """Normalize a required cloid-like value to its wire decimal string."""
+    if isinstance(value, Cloid):
+        return value.to_raw()
+    return Cloid(str(value)).to_raw()
+
+
+def as_cloid_str(value: Optional[Union[str, int, Cloid]]) -> Optional[str]:
+    """Normalize an optional cloid-like value to its wire decimal string (or ``None``)."""
+    return None if value is None else cloid_str(value)

upside/websocket_manager.py

@@ -0,0 +1,199 @@
+"""Threaded WebSocket client for the Upside realtime API.
+
+Runs ``websocket-client``'s ``run_forever`` on a background thread with built-in
+ping and auto-reconnect. Subscriptions use the v0.14 protocol
+``{"method": "subscribe", "subscription": {...}}``; each is keyed by a stable
+*identifier* so incoming pushes can be routed to the right callback(s), and so
+active subscriptions can be replayed after a reconnect.
+
+See https://docs.upsidemax.xyz/websocket/overview.
+"""
+
+import json
+import logging
+import threading
+from collections import defaultdict
+from typing import Any, Callable, Dict, List, NamedTuple, Optional
+
+import websocket
+
+from .utils.error import WebsocketError
+from .utils.types import Json, Subscription
+
+WsCallback = Callable[[Json], None]
+
+# Control channels that carry no subscription payload.
+_CONTROL_CHANNELS = {"subscriptionResponse", "error", "pong"}
+
+# Inbound channel prefix (before the ".<addr>") -> subscription type.
+_USER_CHANNEL_TO_TYPE = {
+    "orderUpdates": "orderUpdates",
+    "openOrders": "openOrders",
+    "fills": "userFills",
+}
+
+
+def subscription_to_identifier(subscription: Subscription) -> str:
+    """Stable key for a subscription, matched against inbound messages."""
+    sub_type = subscription["type"]
+    if sub_type in ("l2Book", "bbo", "trades"):
+        return f'{sub_type}:{subscription["asset"]}'
+    if sub_type == "candle":
+        return f'candle:{subscription["asset"]},{subscription["interval"]}'
+    if sub_type in ("orderUpdates", "openOrders", "userFills"):
+        return f'{sub_type}:{str(subscription["user"]).lower()}'
+    if sub_type == "config":
+        return "config"
+    raise WebsocketError(f"unknown subscription type: {sub_type}")
+
+
+def ws_message_to_identifier(message: Dict[str, Any]) -> Optional[str]:
+    """Derive the identifier for an inbound push, or ``None`` for control frames."""
+    channel = message.get("channel")
+    if channel is None or channel in _CONTROL_CHANNELS:
+        return None
+
+    data: Any = message.get("data")
+    if channel in ("l2Book", "bbo"):
+        return f'{channel}:{data.get("asset")}'
+    if channel == "trades":
+        first = data[0] if isinstance(data, list) and data else {}
+        return f'trades:{first.get("asset")}'
+    if channel == "candle":
+        return f'candle:{data.get("s")},{data.get("i")}'
+    if channel == "config":
+        return "config"
+
+    # User channels arrive as "<base>.<address>" (e.g. "fills.0xabc").
+    base, _, addr = channel.partition(".")
+    sub_type = _USER_CHANNEL_TO_TYPE.get(base)
+    if sub_type is not None:
+        return f"{sub_type}:{addr.lower()}"
+    return None
+
+
+class _ActiveSubscription(NamedTuple):
+    callback: WsCallback
+    subscription_id: int
+    subscription: Subscription
+
+
+class WebsocketManager(threading.Thread):
+    """Background WebSocket connection with subscribe/dispatch/reconnect."""
+
+    def __init__(self, base_url: str, ping_interval: int = 30, user_agent: str = "upside-python-sdk") -> None:
+        super().__init__(daemon=True)
+        # http(s)://host  ->  ws(s)://host/ws
+        self.ws_url = "ws" + base_url.rstrip("/")[len("http") :] + "/ws"
+        self.ping_interval = ping_interval
+        # A User-Agent header is required to pass the CloudFront edge in front of QA.
+        self._headers = [f"User-Agent: {user_agent}"]
+        self._logger = logging.getLogger("upside.ws")
+
+        self._lock = threading.Lock()
+        self._id_counter = 0
+        self.ws_ready = False
+        self._auth_account_id: Optional[int] = None
+        self._active: Dict[str, List[_ActiveSubscription]] = defaultdict(list)
+
+        self.ws = websocket.WebSocketApp(
+            self.ws_url,
+            header=self._headers,
+            on_open=self._on_open,
+            on_message=self._on_message,
+            on_error=self._on_error,
+            on_close=self._on_close,
+        )
+
+    # -- thread entrypoint ------------------------------------------------
+    def run(self) -> None:
+        self.ws.run_forever(ping_interval=self.ping_interval, ping_timeout=self.ping_interval - 5, reconnect=5)
+
+    def stop(self) -> None:
+        try:
+            self.ws.close()
+        except Exception:  # pragma: no cover - best-effort teardown
+            pass
+
+    # -- public API -------------------------------------------------------
+    def authenticate(self, account_id: int) -> None:
+        """Send an ``Auth`` frame (optional today; recommended for forward compat)."""
+        self._auth_account_id = account_id
+        if self.ws_ready:
+            self._send({"msg": "Auth", "accountId": account_id})
+
+    def subscribe(self, subscription: Subscription, callback: WsCallback) -> int:
+        """Register ``callback`` for ``subscription`` and return a subscription id."""
+        identifier = subscription_to_identifier(subscription)
+        with self._lock:
+            self._id_counter += 1
+            sub_id = self._id_counter
+            first_for_identifier = not self._active[identifier]
+            self._active[identifier].append(_ActiveSubscription(callback, sub_id, subscription))
+            # If the socket isn't ready yet, _on_open replays every active
+            # subscription; only send now for the first callback of an identifier.
+            if self.ws_ready and first_for_identifier:
+                self._send({"method": "subscribe", "subscription": dict(subscription)})
+        return sub_id
+
+    def unsubscribe(self, subscription: Subscription, subscription_id: int) -> bool:
+        """Remove one callback; send ``unsubscribe`` when the last one is gone."""
+        identifier = subscription_to_identifier(subscription)
+        with self._lock:
+            entries = self._active.get(identifier, [])
+            remaining = [e for e in entries if e.subscription_id != subscription_id]
+            removed = len(remaining) != len(entries)
+            if remaining:
+                self._active[identifier] = remaining
+            else:
+                self._active.pop(identifier, None)
+                if removed and self.ws_ready:
+                    self._send({"method": "unsubscribe", "subscription": dict(subscription)})
+        return removed
+
+    # -- socket callbacks -------------------------------------------------
+    def _on_open(self, _ws: Any) -> None:
+        self._logger.debug("websocket open: %s", self.ws_url)
+        with self._lock:
+            self.ws_ready = True
+            if self._auth_account_id is not None:
+                self._send({"msg": "Auth", "accountId": self._auth_account_id})
+            # Replay every active subscription (covers both first connect and reconnect).
+            for entries in self._active.values():
+                if entries:
+                    self._send({"method": "subscribe", "subscription": dict(entries[0].subscription)})
+
+    def _on_message(self, _ws: Any, raw: str) -> None:
+        try:
+            message = json.loads(raw)
+        except json.JSONDecodeError:
+            self._logger.warning("dropping non-JSON ws frame: %s", raw[:120])
+            return
+        if not isinstance(message, dict):
+            return
+
+        if message.get("channel") == "error":
+            self._logger.warning("ws subscription error: %s", message.get("data"))
+
+        identifier = ws_message_to_identifier(message)
+        if identifier is None:
+            return
+        with self._lock:
+            callbacks = [e.callback for e in self._active.get(identifier, [])]
+        for callback in callbacks:
+            try:
+                callback(message)
+            except Exception:  # pragma: no cover - user callback error
+                self._logger.exception("error in ws callback for %s", identifier)
+
+    def _on_error(self, _ws: Any, error: Any) -> None:
+        self._logger.warning("websocket error: %s", error)
+
+    def _on_close(self, _ws: Any, status_code: Any, msg: Any) -> None:
+        self._logger.debug("websocket closed: %s %s", status_code, msg)
+        with self._lock:
+            self.ws_ready = False
+
+    # -- internals --------------------------------------------------------
+    def _send(self, payload: Dict[str, Any]) -> None:
+        self.ws.send(json.dumps(payload))