Python SDK

The Upside Python SDK is the official client for the Upside perpetuals exchange. It wraps the REST read API (POST /info), the signed write API (POST /exchange), and the realtime WebSocket streams behind two typed client classes. Authentication is EIP-712 wallet signing (secp256k1) — there are no API keys to manage.

upsidemax/upside-python-sdk

Source, examples, and issue tracker on GitHub. MIT licensed.

EIP-712 request signing across the Agent and Typed paths — handled for you.
Synchronous REST with a threaded WebSocket client that auto-reconnects.
Raw-dict responses, typed inputs, and full type hints (ships py.typed).
Agent (API-wallet) delegation, TP/SL, leverage / margin, and collateral actions.

Installation

pip install upside-python-sdk

Requires Python 3.9+. Runtime dependencies: requests, websocket-client, eth-account, eth-utils.

Quick start

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 alpha test invitation code from the Upside team).
# A 10,000 USDC test airdrop lands within ~10s.
exchange.register_account(invite_code="<your-code>")

# Place a resting limit buy. Prices and 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")

The two clients

Info — reads & streams

Market data, account and order queries, and realtime WebSocket subscriptions. No wallet or signing required.

Exchange — signed writes

Orders, cancels, margin and leverage, TP/SL, collateral, and agent delegation — every call signed with your wallet key.

Key behaviors

Prices and sizes are raw integer strings. The wire protocol is integer-only: convert a display price with the contract’s priceScale and a display size with its qtyScale, both read from configs — never hardcode a scale. For example, on a contract with priceScale = 2, a display price of 500.00 is sent as "50000".

Order placement is asynchronous. A batch returns {"status": "accepted", "response": {"type": "order", "data": {"count": n}}} — not the resting order id. Read the result from Info.user_orders / orders_by_cloids, or the orderUpdates / userFills WebSocket channels. Cancels, modifies, and margin actions respond synchronously.
HTTP 200 does not always mean success. Gateway-level failures (invalid signature, reused nonce, rate limiting) raise ClientError (4xx) or ServerError (5xx). Business rejections come back as HTTP 200 — a per-item error string inside statuses[], or a non-zero errorCode inside response.data. Always inspect the response.

Error handling

Every SDK error derives from UpsideError:

Exception	Raised when
`ClientError`	The gateway returns a 4xx (bad request, invalid signature, invite/nonce issue).
`ServerError`	The gateway returns a 5xx (including `DOWNSTREAM_TIMEOUT`).
`WebsocketError`	A streaming/connection error on the WebSocket client.
`APIError`	Base class for the HTTP errors above.

from upside import ClientError, ServerError

try:
    exchange.order(asset=1, is_buy=True, size="10", price="50")
except ClientError as e:
    print("rejected before processing:", e)
except ServerError as e:
    print("server error, safe to re-check state:", e)

Environments

The SDK defaults to the QA testnet, constants.QA_API_URL (https://dev.upsidemax.xyz). Pass base_url explicitly to target a different environment. For UAT or production access, contact the Upside team. Contract IDs, coin IDs, scales, and tick / step sizes are server-assigned and differ per environment — always read them from Info.configs() rather than hardcoding.

Signing

Every /exchange write is authorized by an EIP-712 signature over the fixed domain (Exchange / version 1 / chain id 9767 / zero verifying contract). The SDK selects the correct path automatically — the Typed path for registerAccount, approveAgent, revokeAgent, and the collateral actions, and the Agent path for everything else. Nonces are strictly increasing millisecond timestamps managed per Exchange instance. See Authentication for the full scheme.

Overview

Authentication

Request Format

Reference

SDKs

upsidemax/upside-python-sdk

Installation

Quick start

The two clients

Info — reads & streams

Exchange — signed writes

Key behaviors

Error handling

Environments

Signing

upsidemax/upside-python-sdk

​Installation

​Quick start

​The two clients

Info — reads & streams

Exchange — signed writes

​Key behaviors

​Error handling

​Environments

​Signing

Installation

Quick start

The two clients

Key behaviors

Error handling

Environments

Signing