Python SDK

The UpsideMAX Python SDK is the official client for the UpsideMAX 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 timeouts and safe retries, plus a threaded WebSocket client that auto-reconnects.
Checked inputs: every field is validated before signing, so a malformed request fails locally instead of being silently dropped.
Raw-dict responses, typed inputs, and full type hints (ships py.typed).
Agent (API-wallet) delegation, TP/SL, leverage / margin, collateral, and portfolio-margin actions.

Installation

pip install "upside-python-sdk>=0.3.0"

Requires Python 3.9+. Runtime dependencies: requests, websocket-client, eth-account, eth-utils. This documentation describes version 0.3.0.

Quick start

from upside import Info, Exchange
from upside.utils import constants

# --- reads (no signing) ---
info = Info(base_url=constants.MAINNET_API_URL, skip_ws=True)
cfg = info.configs()
contract = next(c for c in cfg["contracts"] if c["status"] == "Active")
asset = contract["contractId"]

# --- writes (EIP-712 signed) ---
exchange = Exchange("0x<private-key>", base_url=constants.MAINNET_API_URL, sync=True)   # chain ID 9788

# Register with an invitation code from the UpsideMAX team. The new account has no
# balance: deposit funds before placing the order below.
exchange.register_account(invite_code="<your-code>")

# Price off the live mark price, in raw integers: 20% below mark rests without filling.
# A price far from mark is rejected by the contract's price band.
mark = int(info.market_state(asset)["markPx"])
tick = int(contract["tickSize"])
price = (mark * 80 // 100) // tick * tick

# Size: the smallest whole step whose notional reaches the minimum order value.
# notional = price x size x notionalScaleMultiplier, all raw integers.
mult, step = int(contract["notionalScaleMultiplier"]), int(contract["stepSize"])
need = -(-int(cfg["minNotionalValue"]) // (price * mult)) or 1
size = -(-need // step) * step

receipt = exchange.order(asset=asset, is_buy=True, size=str(size), price=str(price))
print(receipt["response"]["data"]["statuses"][0])   # {"resting": {"oid": ...}} or {"error": ...}

An order on an account without usable margin is rejected — check marginAvailableForOrder in user_account first. The Quickstart walks through the same flow with the checks built in.

The two clients

Info — reads & streams

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

Exchange — signed writes

Orders, cancels, margin and leverage, TP/SL, collateral, portfolio margin, 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. Scales differ per contract and are often 0.

Orders and cancels have two receipt shapes. order, cancel, cancel_by_cloid, cancel_all, and modify take a sync flag. With sync=True the call returns once the action has executed, with one statuses[] entry per submitted item. Without it the server answers 202 with {"status": "accepted", "response": {"type": "accepted", "data": {"count": n}}} and the per-order outcome — including any rejection — arrives only on the orderUpdates WebSocket channel. See Receipts.
Every other action is synchronous. Margin, leverage, TP/SL, collateral, and agent actions always return their result in the HTTP response.
HTTP 200 does not always mean success. Business rejections come back as HTTP 200 — a per-item error inside statuses[], or a non-zero errorCode inside response.data. Always inspect the response.

Timeouts and retries

Every request has a timeout — 5 seconds to connect and 10 seconds to read by default; pass timeout= (seconds, or a (connect, read) tuple) to either client. Failed requests are retried with exponential backoff (max_retries=3, backoff=0.5 seconds; max_retries=0 disables retrying) only where resending is safe:

Endpoint	Retried on	Not retried
`/info`	Read timeout, dropped connection, `502` / `503` / `504`	`503 NOT_READY` — the contract has no order book yet; raised at once
`/exchange`	Only failures before the request left your machine: connection refused, DNS failure, connect timeout	Anything after that — raises `OutcomeUnknownError`

A signed write cannot be resent once it may have reached the server: the resend carries the same nonce and is rejected as a duplicate even if the first attempt executed. So instead of guessing, the SDK raises OutcomeUnknownError.

Error handling

Every SDK error derives from UpsideError:

Exception	Raised when
`ClientError`	The gateway returns a 4xx (invalid parameter, invalid signature, reused nonce). For `INVALID_PARAM`, `.errors` lists the offending fields.
`ServerError`	The gateway returns a 5xx. A `504 DOWNSTREAM_TIMEOUT` on a `sync=True` write means the outcome is unknown, as below.
`OutcomeUnknownError`	An `/exchange` request may have executed but no response arrived (read timeout, connection dropped mid-response). Carries `nonce` and `action_type`.
`WebsocketError`	A subscription request is malformed.
`APIError`	Base class of `ClientError` and `ServerError`; carries `status_code`, `code`, `message`, and `request_id`.

Arguments are checked before anything is signed: a malformed id, size, price, time-in-force, or type raises Python’s own ValueError / TypeError, and nothing is sent.

from upside import ClientError, OutcomeUnknownError, ServerError

try:
    exchange.order(asset=asset, is_buy=True, size=str(size), price=str(price), cloid=cloid)
except OutcomeUnknownError:
    # Do NOT re-sign the same order yet: it may have executed. Reconcile first.
    ...
except ClientError as e:
    print("rejected before processing:", e.code, e.errors)
except ServerError as e:
    print("server error:", e.code)

Reconciling an unknown outcome. Look the order up by its client order id in both places an order can be: user_orders for orders still resting and order_history / user_fills for orders that already filled or were canceled — or watch the orderUpdates channel. orders_by_cloids alone is not enough: it only sees live orders, so an order that filled immediately looks missing. History is indexed shortly after execution; re-check for a few seconds before concluding the order did not land.

import time

sent_at_ms = int(time.time() * 1000)
try:
    exchange.order(asset=asset, is_buy=True, size=str(size), price=str(price), cloid=cloid, sync=True)
except OutcomeUnknownError:
    live = info.user_orders(exchange.account_id)["orders"]
    done = info.order_history(exchange.account_id, start_time=sent_at_ms)["orders"]
    landed = any(o.get("clientOrderId") == str(cloid) for o in live + done)

Environments

Without a base_url the SDK uses Mainnet; pass constants.DEVNET_API_URL for Devnet:

Environment	Constant	Base URL	Chain ID
Mainnet	`constants.MAINNET_API_URL`	`https://upsidemax.xyz`	`9788`
Devnet	`constants.DEVNET_API_URL`	`https://dev.upsidemax.xyz`	`9767`

info = Info(base_url=constants.MAINNET_API_URL)
exchange = Exchange("0x<private-key>", base_url=constants.MAINNET_API_URL)

Exchange signs with the chain ID of the environment its base_url points at. If you reach Mainnet through a different address, pass chain_id=9788 explicitly — a signature over the wrong chain ID is rejected with 401 SIGNATURE_INVALID. 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 / the environment’s chain ID / zero verifying contract). The SDK selects the correct path automatically — the Typed path for registerAccount, approveAgent, revokeAgent, lockCollateral, unlockCollateral, and transferBetweenDeployers, and the Agent path for everything else. Nonces are strictly increasing millisecond timestamps managed per Exchange instance; share one NonceManager between clients that sign with the same key. Browser-extension wallets sign typed structs with their active chain id rather than the environment’s. To match such a signature, pass Exchange(..., signature_chain_id=...); with a raw private key, leave it unset. 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

Timeouts and retries

Error handling

Environments

Signing

upsidemax/upside-python-sdk

​Installation

​Quick start

​The two clients

Info — reads & streams

Exchange — signed writes

​Key behaviors

​Timeouts and retries

​Error handling

​Environments

​Signing

Installation

Quick start

The two clients

Key behaviors

Timeouts and retries

Error handling

Environments

Signing