upside-python-sdk 0.1.0__tar.gz

upside_python_sdk-0.1.0/LICENSE

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

upside_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: upside-python-sdk
+Version: 0.1.0
+Summary: Python SDK for the Upside decentralized perpetuals exchange (REST + WebSocket).
+License: MIT
+License-File: LICENSE
+Keywords: upside,perpetuals,dex,trading,eip712,websocket
+Author: Upside
+Author-email: dev@upsidemax.xyz
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: eth-account (>=0.10,<0.14)
+Requires-Dist: eth-utils (>=2.3.0)
+Requires-Dist: requests (>=2.31.0)
+Requires-Dist: typing-extensions (>=4.5.0) ; python_version < "3.11"
+Requires-Dist: websocket-client (>=1.7.0,<2.0.0)
+Project-URL: Documentation, https://docs.upsidemax.xyz
+Project-URL: Homepage, https://docs.upsidemax.xyz
+Project-URL: Repository, https://github.com/upsidemax/upside-python-sdk
+Description-Content-Type: text/markdown
+
+# Upside Python SDK
+
+A Python client for the [Upside](https://docs.upsidemax.xyz) decentralized
+perpetuals exchange — REST reads (`POST /info`), signed writes (`POST /exchange`),
+and realtime WebSocket streams.
+
+- **EIP-712 request signing** (secp256k1) with the Agent and Typed paths — no API keys.
+- **Synchronous REST** over `requests`, **threaded WebSocket** over `websocket-client`.
+- Raw-dict responses, `TypedDict` inputs, full type hints (ships `py.typed`).
+- Agent (API-wallet) delegation, TP/SL, leverage/margin, and collateral actions.
+
+> The default environment is the **QA testnet** (`https://dev.upsidemax.xyz`).
+> Contract IDs, scales, and tick/step sizes are server-assigned — always read
+> them from `configs`, never hardcode.
+
+## Installation
+
+```bash
+pip install upside-python-sdk
+```
+
+Requires Python 3.9+. Runtime dependencies: `requests`, `websocket-client`,
+`eth-account`, `eth-utils`.
+
+## Quick start
+
+```python
+from upside import Info, Exchange
+from upside.utils import constants
+
+# --- reads (no signing) ---
+info = Info(base_url=constants.QA_API_URL)
+cfg = info.configs()
+contract = next(c for c in cfg["contracts"] if c["status"] == "Active")
+asset = contract["contractId"]
+print(info.market_state(asset))
+
+# --- writes (EIP-712 signed) ---
+exchange = Exchange("0x<private-key>", base_url=constants.QA_API_URL)
+
+# Register (QA requires an invite code from the Upside team). A 10,000 USDC
+# test airdrop lands within ~10s.
+exchange.register_account(invite_code="<invite-code>")
+
+# Place a resting limit buy. Prices/sizes are raw integer strings — scale them
+# with the contract's priceScale / qtyScale from configs.
+exchange.order(asset=asset, is_buy=True, size="10", price="50")
+```
+
+## Reading data — `Info`
+
+All methods return the raw parsed JSON. See
+[docs.upsidemax.xyz/info](https://docs.upsidemax.xyz/info/overview) for response shapes.
+
+```python
+info.configs()                                  # contracts, coins, scales, tiers (cache this)
+info.l2_book(asset)                             # full order book snapshot
+info.market_state(asset)                        # mark/oracle/last price, funding
+info.candle_snapshot(asset, "1m", start, end)   # historical OHLCV
+info.user_account(account_id, market_deployer_id)
+info.user_orders(account_id, market_deployer_id, contract_id=0)
+info.orders_by_ids(market_deployer_id, ["8280"])
+info.orders_by_cloids(account_id, market_deployer_id, ["1778844423064"])
+info.user_agents(account_id)
+info.user_market_deployers(account_id)
+info.share_group_state()
+```
+
+## Trading — `Exchange`
+
+```python
+from upside import Cloid
+
+exchange.order(asset=1, is_buy=True, size="10", price="50", cloid=Cloid.from_int(1001))
+exchange.market_order(asset=1, is_buy=False, size="5")
+exchange.bulk_orders([...])                     # up to 10 orders, one signature
+exchange.cancel(asset=1, oid=15)
+exchange.cancel_by_cloid(asset=1, cloid=1001)
+exchange.cancel_all(asset=1)
+exchange.modify(asset=1, oid=15, price="151", size="8")
+
+exchange.update_leverage(asset=1, leverage=20)
+exchange.update_margin_mode(asset=1, is_cross=False, is_hedge=True)
+exchange.update_isolated_margin(asset=1, ntli=5000)
+
+exchange.tp_sl(asset=1, tp_price="90000", sl_price="80000")
+exchange.cancel_tp_sl(asset=1)
+exchange.cancel_conditional(oid=123)
+
+exchange.lock_collateral(market_deployer_id=1, coin_id=1, amount="1000")
+exchange.transfer_between_deployers(1, 2, coin_id=1, amount="1000")
+```
+
+### Order placement is asynchronous
+
+A batch returns `{"status": "accepted", "response": {"type": "order", "data": {"count": n}}}`
+— **not** the resting order id. Read the resulting state from
+`Info.user_orders` / `orders_by_cloids`, or the `orderUpdates` / `userFills`
+WebSocket channels. Cancels, modifies, and margin actions respond synchronously.
+
+### HTTP 200 ≠ success
+
+Gateway failures (bad signature, reused nonce, rate limit) raise `ClientError`
+(4xx) / `ServerError` (5xx). Business rejections come back as HTTP 200 — a per-item
+`error` string in `statuses[]`, or a non-zero `errorCode` in `response.data`.
+Always inspect them.
+
+## Agent (API-wallet) delegation
+
+Keep the master key offline; authorize a hot agent key to sign trades. The
+server routes agent-signed actions to the master account.
+
+```python
+response, agent_key = master.approve_agent(agent_name="bot1")   # generates a fresh key
+agent = Exchange(agent_key, base_url=constants.QA_API_URL, account_id=master.account_id)
+agent.order(asset=1, is_buy=True, size="10", price="50")
+master.revoke_agent(agent.address)
+```
+
+## WebSocket streams
+
+```python
+info = Info(base_url=constants.QA_API_URL)          # WS starts automatically
+
+sid = info.subscribe({"type": "l2Book", "asset": "1"}, lambda m: print(m["data"]["bookVersion"]))
+info.subscribe({"type": "trades", "asset": "1"}, print)
+info.subscribe({"type": "orderUpdates", "user": "0x<address>"}, print)   # private: pass the wallet address
+info.subscribe({"type": "userFills", "user": "0x<address>"}, print)
+
+info.unsubscribe({"type": "l2Book", "asset": "1"}, sid)
+info.close()
+```
+
+Channels: `l2Book`, `bbo`, `trades`, `candle`, `config` (public) and
+`orderUpdates`, `openOrders`, `userFills` (per-address). The client pings every
+30s and auto-reconnects, replaying subscriptions. WebSocket does **not** push
+position or balance changes — poll `userAccount` for those.
+
+## Signing
+
+Every `/exchange` write is authorized by an EIP-712 signature over a fixed
+domain (`Exchange` / `1` / chainId `9767` / zero verifying contract). The SDK
+handles both paths automatically:
+
+- **Typed path** — `registerAccount`, `approveAgent`, `revokeAgent`,
+  `lockCollateral`, `unlockCollateral`, `transferBetweenDeployers`.
+- **Agent path** — every other action (canonical-JSON `actionHash`).
+
+Nonces are strictly increasing millisecond timestamps managed per `Exchange`
+instance (`NonceManager`). See
+[docs.upsidemax.xyz/guide/authentication](https://docs.upsidemax.xyz/guide/authentication).
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples). Copy `config.json.example` to
+`config.json`, set your test wallet and invite code, then:
+
+```bash
+python examples/01_register_and_airdrop.py
+python examples/03_place_and_cancel_order.py
+python examples/06_websocket_streams.py
+```
+
+## Development
+
+```bash
+make install     # poetry install
+make test        # pytest
+make lint        # black --check + ruff
+make typecheck   # mypy
+make check       # all of the above
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+

upside_python_sdk-0.1.0/README.md

@@ -0,0 +1,176 @@
+# Upside Python SDK
+
+A Python client for the [Upside](https://docs.upsidemax.xyz) decentralized
+perpetuals exchange — REST reads (`POST /info`), signed writes (`POST /exchange`),
+and realtime WebSocket streams.
+
+- **EIP-712 request signing** (secp256k1) with the Agent and Typed paths — no API keys.
+- **Synchronous REST** over `requests`, **threaded WebSocket** over `websocket-client`.
+- Raw-dict responses, `TypedDict` inputs, full type hints (ships `py.typed`).
+- Agent (API-wallet) delegation, TP/SL, leverage/margin, and collateral actions.
+
+> The default environment is the **QA testnet** (`https://dev.upsidemax.xyz`).
+> Contract IDs, scales, and tick/step sizes are server-assigned — always read
+> them from `configs`, never hardcode.
+
+## Installation
+
+```bash
+pip install upside-python-sdk
+```
+
+Requires Python 3.9+. Runtime dependencies: `requests`, `websocket-client`,
+`eth-account`, `eth-utils`.
+
+## Quick start
+
+```python
+from upside import Info, Exchange
+from upside.utils import constants
+
+# --- reads (no signing) ---
+info = Info(base_url=constants.QA_API_URL)
+cfg = info.configs()
+contract = next(c for c in cfg["contracts"] if c["status"] == "Active")
+asset = contract["contractId"]
+print(info.market_state(asset))
+
+# --- writes (EIP-712 signed) ---
+exchange = Exchange("0x<private-key>", base_url=constants.QA_API_URL)
+
+# Register (QA requires an invite code from the Upside team). A 10,000 USDC
+# test airdrop lands within ~10s.
+exchange.register_account(invite_code="<invite-code>")
+
+# Place a resting limit buy. Prices/sizes are raw integer strings — scale them
+# with the contract's priceScale / qtyScale from configs.
+exchange.order(asset=asset, is_buy=True, size="10", price="50")
+```
+
+## Reading data — `Info`
+
+All methods return the raw parsed JSON. See
+[docs.upsidemax.xyz/info](https://docs.upsidemax.xyz/info/overview) for response shapes.
+
+```python
+info.configs()                                  # contracts, coins, scales, tiers (cache this)
+info.l2_book(asset)                             # full order book snapshot
+info.market_state(asset)                        # mark/oracle/last price, funding
+info.candle_snapshot(asset, "1m", start, end)   # historical OHLCV
+info.user_account(account_id, market_deployer_id)
+info.user_orders(account_id, market_deployer_id, contract_id=0)
+info.orders_by_ids(market_deployer_id, ["8280"])
+info.orders_by_cloids(account_id, market_deployer_id, ["1778844423064"])
+info.user_agents(account_id)
+info.user_market_deployers(account_id)
+info.share_group_state()
+```
+
+## Trading — `Exchange`
+
+```python
+from upside import Cloid
+
+exchange.order(asset=1, is_buy=True, size="10", price="50", cloid=Cloid.from_int(1001))
+exchange.market_order(asset=1, is_buy=False, size="5")
+exchange.bulk_orders([...])                     # up to 10 orders, one signature
+exchange.cancel(asset=1, oid=15)
+exchange.cancel_by_cloid(asset=1, cloid=1001)
+exchange.cancel_all(asset=1)
+exchange.modify(asset=1, oid=15, price="151", size="8")
+
+exchange.update_leverage(asset=1, leverage=20)
+exchange.update_margin_mode(asset=1, is_cross=False, is_hedge=True)
+exchange.update_isolated_margin(asset=1, ntli=5000)
+
+exchange.tp_sl(asset=1, tp_price="90000", sl_price="80000")
+exchange.cancel_tp_sl(asset=1)
+exchange.cancel_conditional(oid=123)
+
+exchange.lock_collateral(market_deployer_id=1, coin_id=1, amount="1000")
+exchange.transfer_between_deployers(1, 2, coin_id=1, amount="1000")
+```
+
+### Order placement is asynchronous
+
+A batch returns `{"status": "accepted", "response": {"type": "order", "data": {"count": n}}}`
+— **not** the resting order id. Read the resulting state from
+`Info.user_orders` / `orders_by_cloids`, or the `orderUpdates` / `userFills`
+WebSocket channels. Cancels, modifies, and margin actions respond synchronously.
+
+### HTTP 200 ≠ success
+
+Gateway failures (bad signature, reused nonce, rate limit) raise `ClientError`
+(4xx) / `ServerError` (5xx). Business rejections come back as HTTP 200 — a per-item
+`error` string in `statuses[]`, or a non-zero `errorCode` in `response.data`.
+Always inspect them.
+
+## Agent (API-wallet) delegation
+
+Keep the master key offline; authorize a hot agent key to sign trades. The
+server routes agent-signed actions to the master account.
+
+```python
+response, agent_key = master.approve_agent(agent_name="bot1")   # generates a fresh key
+agent = Exchange(agent_key, base_url=constants.QA_API_URL, account_id=master.account_id)
+agent.order(asset=1, is_buy=True, size="10", price="50")
+master.revoke_agent(agent.address)
+```
+
+## WebSocket streams
+
+```python
+info = Info(base_url=constants.QA_API_URL)          # WS starts automatically
+
+sid = info.subscribe({"type": "l2Book", "asset": "1"}, lambda m: print(m["data"]["bookVersion"]))
+info.subscribe({"type": "trades", "asset": "1"}, print)
+info.subscribe({"type": "orderUpdates", "user": "0x<address>"}, print)   # private: pass the wallet address
+info.subscribe({"type": "userFills", "user": "0x<address>"}, print)
+
+info.unsubscribe({"type": "l2Book", "asset": "1"}, sid)
+info.close()
+```
+
+Channels: `l2Book`, `bbo`, `trades`, `candle`, `config` (public) and
+`orderUpdates`, `openOrders`, `userFills` (per-address). The client pings every
+30s and auto-reconnects, replaying subscriptions. WebSocket does **not** push
+position or balance changes — poll `userAccount` for those.
+
+## Signing
+
+Every `/exchange` write is authorized by an EIP-712 signature over a fixed
+domain (`Exchange` / `1` / chainId `9767` / zero verifying contract). The SDK
+handles both paths automatically:
+
+- **Typed path** — `registerAccount`, `approveAgent`, `revokeAgent`,
+  `lockCollateral`, `unlockCollateral`, `transferBetweenDeployers`.
+- **Agent path** — every other action (canonical-JSON `actionHash`).
+
+Nonces are strictly increasing millisecond timestamps managed per `Exchange`
+instance (`NonceManager`). See
+[docs.upsidemax.xyz/guide/authentication](https://docs.upsidemax.xyz/guide/authentication).
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples). Copy `config.json.example` to
+`config.json`, set your test wallet and invite code, then:
+
+```bash
+python examples/01_register_and_airdrop.py
+python examples/03_place_and_cancel_order.py
+python examples/06_websocket_streams.py
+```
+
+## Development
+
+```bash
+make install     # poetry install
+make test        # pytest
+make lint        # black --check + ruff
+make typecheck   # mypy
+make check       # all of the above
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

upside_python_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "upside-python-sdk"
+version = "0.1.0"
+description = "Python SDK for the Upside decentralized perpetuals exchange (REST + WebSocket)."
+authors = ["Upside <dev@upsidemax.xyz>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://docs.upsidemax.xyz"
+repository = "https://github.com/upsidemax/upside-python-sdk"
+documentation = "https://docs.upsidemax.xyz"
+keywords = ["upside", "perpetuals", "dex", "trading", "eip712", "websocket"]
+packages = [{ include = "upside", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.9"
+requests = ">=2.31.0"
+websocket-client = "^1.7.0"
+eth-account = ">=0.10,<0.14"
+eth-utils = ">=2.3.0"
+typing-extensions = { version = ">=4.5.0", python = "<3.11" }
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.0"
+pytest-cov = "^5.0.0"
+responses = "^0.25.0"
+black = "^24.10.0"
+ruff = "^0.7.0"
+mypy = "^1.13.0"
+types-requests = ">=2.31.0"
+pre-commit = "^3.8.0"
+
+[build-system]
+requires = ["poetry-core>=1.9.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 120
+target-version = ["py39"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+# UP (pyupgrade) is intentionally excluded: the SDK targets Python 3.9 and uses
+# typing.List/Optional style consistent with the reference SDKs.
+select = ["E", "F", "W", "I", "B"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.9"
+warn_unused_ignores = true
+warn_return_any = true
+no_implicit_optional = true
+strict_equality = true
+check_untyped_defs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers -ra"
+testpaths = ["tests"]

upside_python_sdk-0.1.0/src/upside/__init__.py

@@ -0,0 +1,42 @@
+"""Upside Python SDK — REST (`/info`, `/exchange`) and WebSocket client.
+
+Quick start::
+
+    from upside import Info, Exchange
+    from upside.utils import constants
+
+    info = Info(base_url=constants.QA_API_URL)
+    print(info.configs())
+
+    exchange = Exchange(private_key, base_url=constants.QA_API_URL)
+    exchange.order(asset=1, is_buy=True, size="10", price="50")
+
+See https://docs.upsidemax.xyz for the full API reference.
+"""
+
+from .api import API
+from .exchange import Exchange
+from .info import Info
+from .utils import constants
+from .utils.error import APIError, ClientError, ServerError, UpsideError, WebsocketError
+from .utils.signing import NonceManager
+from .utils.types import Cloid
+from .websocket_manager import WebsocketManager
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "API",
+    "Info",
+    "Exchange",
+    "WebsocketManager",
+    "NonceManager",
+    "Cloid",
+    "constants",
+    "UpsideError",
+    "APIError",
+    "ClientError",
+    "ServerError",
+    "WebsocketError",
+    "__version__",
+]

upside_python_sdk-0.1.0/src/upside/api.py

@@ -0,0 +1,61 @@
+"""Base HTTP transport shared by :class:`~upside.info.Info` and
+:class:`~upside.exchange.Exchange`.
+
+Everything is a JSON ``POST`` to ``/info`` or ``/exchange`` over one persistent
+session. Gateway-level failures (non-2xx, or a body with ``"status": "error"``)
+raise :class:`~upside.utils.error.ClientError` / ``ServerError``; business-level
+outcomes (per-order ``statuses[].error``, non-zero ``errorCode``) are returned
+verbatim for the caller to inspect.
+"""
+
+import logging
+from json import JSONDecodeError
+from typing import Any, Optional, cast
+
+import requests
+
+from .utils import constants
+from .utils.error import ClientError, ServerError
+from .utils.types import Json
+
+
+class API:
+    """Thin POST-only client with status-based exception mapping."""
+
+    def __init__(self, base_url: Optional[str] = None, timeout: Optional[float] = None) -> None:
+        self.base_url = (base_url or constants.QA_API_URL).rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"Content-Type": "application/json"})
+        self._logger = logging.getLogger("upside")
+
+    def post(self, url_path: str, payload: Optional[Any] = None) -> Json:
+        """POST ``payload`` to ``url_path`` and return the parsed JSON body."""
+        url = self.base_url + url_path
+        response = self.session.post(url, json=payload or {}, timeout=self.timeout)
+        return self._handle_response(response)
+
+    def _handle_response(self, response: requests.Response) -> Json:
+        try:
+            body = response.json()
+        except (JSONDecodeError, ValueError):
+            body = None
+
+        if response.ok and not (isinstance(body, dict) and body.get("status") == "error"):
+            if body is None:
+                raise ServerError(response.status_code, message=f"non-JSON response: {response.text[:200]}")
+            return cast(Json, body)
+
+        code = message = request_id = None
+        if isinstance(body, dict):
+            code = body.get("code")
+            message = body.get("message")
+            request_id = body.get("requestId")
+        else:
+            message = response.text[:500] or None
+
+        error_cls = ClientError if 400 <= response.status_code < 500 else ServerError
+        raise error_cls(response.status_code, code=code, message=message, request_id=request_id)
+
+    def close(self) -> None:
+        self.session.close()