UpsideMAX Python SDK
A Python client for the UpsideMAX perpetuals
exchange — REST reads (POST /info), signed writes (POST /exchange),
and realtime WebSocket streams. Authentication is EIP-712 wallet-signed
(secp256k1) rather than API keys.
- EIP-712 request signing (secp256k1) with the Agent and Typed paths — no API keys.
- Synchronous REST over
requests, threaded WebSocket overwebsocket-client. - Raw-dict responses,
TypedDictinputs, full type hints (shipspy.typed). - Agent (API-wallet) delegation, TP/SL, leverage/margin, and collateral actions.
The default environment is the UpsideMAX Devnet (
https://dev.upsidemax.xyz,constants.DEVNET_API_URL). Contract IDs, scales, and tick/step sizes are server-assigned — always read them fromconfigs, never hardcode.
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.DEVNET_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.DEVNET_API_URL)
# Register (Devnet requires an invite code from the UpsideMAX team). A test airdrop
# follows once this call has returned 200.
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 for response shapes.
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=0, contract_id=0) # 0 = all; check "truncated"
info.orders_by_ids(market_deployer_id, ["8280"])
info.orders_by_cloids(account_id, market_deployer_id, ["1778844423064"])
info.ticker(asset) # 24h rolling stats (omit asset = all markets)
info.user_agents(account_id)
info.user_market_deployers(account_id)
info.account_by_address("0x<address>") # master or agent address -> accountId
info.share_group_state()
# history (ascending, paginate on the last row's time; limit <= 1000)
info.user_fills(account_id, contract_id=0, start_time=None, end_time=None, limit=None)
info.order_history(account_id) # terminal orders only; active ones are in user_orders
info.user_funding_flows(account_id)
Trading — Exchange
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", price="61000") # price = execution price to cross to
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")
# conditional order: fires when the mark price crosses trigger_px
exchange.trigger_order(asset=1, is_buy=False, size="10", price="79000", trigger_px="80000", tpsl="sl")
# entry-inline TP/SL: promoted to position TP/SL once this order fills completely
exchange.order(asset=1, is_buy=True, size="10", price="100",
tp_price="120", tp_limit_price="119", tp_order_type=1, # 1 = limit, 2 = market
sl_price="90", sl_limit_price="89", sl_order_type=2)
exchange.update_leverage(asset=1, leverage=20)
exchange.update_margin_mode(asset=1, is_cross=False) # HEDGE is disabled server-side; ONE_WAY only
exchange.update_isolated_margin(asset=1, ntli=5000)
exchange.update_slippage_setting(market_deployer_id=1, market_slippage_bps=500)
exchange.tp_sl(asset=1, tp_price="90000", tp_limit_price="90000", tp_order_type=1)
exchange.cancel_tp_sl(asset=1)
exchange.cancel_conditional(oid=123)
exchange.lock_collateral(market_deployer_id=1, coin_id=1, amount="1000")
exchange.unlock_collateral(market_deployer_id=1, coin_id=1, amount="1000")
exchange.transfer_between_deployers(1, 2, coin_id=1, amount="1000")
# portfolio (shared) margin
exchange.set_margin_share_type(1) # 0 = UNIFIED, 1 = PORTFOLIO
exchange.transfer_md_to_share_group(1, group_id=3, coin_id=1, amount="1000")
exchange.transfer_share_group_to_md(3, market_deployer_id=1, coin_id=1, amount="1000")
exchange.lock_into_share_group(group_id=3, coin_id=1, amount="1000")
exchange.unlock_from_share_group(group_id=3, coin_id=1, amount="1000")
Market orders and market TP/SL legs carry an execution price you compute
yourself (mark price ± marketSlippageBps/1e4) — the server derives none. Read
your account's cap from Info.user_account's marketSlippageBps and set it
with update_slippage_setting.
Orders and cancels: pick sync
The order/cancel family (order, cancel, cancelByCloid, cancelAll,
modify) has two receipt shapes, chosen per request with sync (an unsigned
envelope flag — the signature is the same either way):
exchange = Exchange(key, sync=True) # default for this client
exchange.order(asset=1, is_buy=True, size="10", price="50")
exchange.cancel(asset=1, oid=15, sync=False) # per-call override
sync=True— HTTP 200 once the action has executed, withresponse.data.statuses[]holding one entry per submitted item in request order.order/modify(modify: exactly one) entries are{"resting": {"oid"}},{"filled": {"totalSz", "avgPx", "oid"}}or{"error": "..."};cancel/cancelByCloidentries are"success"or{"error": "..."}.cancelAllreturns{"limitCancelled": n, "conditionalCancelled": m}instead (nostatuses). A malformed request is refused with400 INVALID_PARAM(ClientError).sync=False— HTTP 202 straight away with{"status": "accepted", "response": {"type": "accepted", "data": {"count": 1}}}; the per-item outcome arrives on theorderUpdateschannel, correlated bycloid, or byn(your nonce) +si(index within the batch). A malformed request may still be answered 202 here and then produce noorderUpdatesentry, so the SDK checks every field (ids, sizes, prices, TIF, types) before signing and raisesValueError/TypeErrorinstead.- not set — the server's default (currently 202). Set it explicitly if you parse the response.
A trigger order answers (with sync=True) with the TP/SL receipt
{"type": "tpSl", "data": {"tpOrderId": n, "slOrderId": n}}. Every other action
is always synchronous and rejects sync, so the SDK only sends it on these five.
Client order ids (cloid) are positive int64 decimal strings; Cloid and every
cloid= argument enforce that before signing.
Timeouts and retries
Every request has a timeout ((5, 10) seconds connect/read by default; pass
timeout=). Failures are retried with exponential backoff (max_retries=3,
backoff=0.5 s) only where resending is safe:
/info— read-only, so a read timeout, a dropped connection, or a transient502/503/504is retried.503 NOT_READY(no order book yet) is raised at once. If every attempt fails, therequestsexception (orServerError) propagates./exchange— retried only when the request never left your machine (connection refused, DNS failure, connect timeout). After that, resending the same signed envelope reuses its nonce and is rejected withDUPLICATE_NONCEeven if the first attempt executed, so a read timeout raisesOutcomeUnknownError(carryingnonceandaction_type) instead. A504 DOWNSTREAM_TIMEOUTon async=Truerequest means the same thing. Confirm the outcome before signing a new request:user_ordersfor orders still resting andorder_history/user_fillsfor ones that already filled or were canceled (or theorderUpdatesstream).orders_by_cloidsalone is not enough — it only sees live orders. History is indexed a moment after execution, so re-check for a few seconds before concluding it did not land.
import time
from upside import OutcomeUnknownError
sent_at_ms = int(time.time() * 1000)
try:
exchange.order(asset=1, is_buy=True, size="10", price="50", cloid=cloid, sync=True)
except OutcomeUnknownError:
# Did it land? Live orders are in user_orders, finished ones in order_history.
live = info.user_orders(account_id)["orders"]
done = info.order_history(account_id, start_time=sent_at_ms)["orders"]
landed = any(o.get("clientOrderId") == str(cloid) for o in live + done)
HTTP 200 ≠ success
Gateway failures (bad signature, reused nonce, invalid parameter) raise
ClientError (4xx) / ServerError (5xx); an INVALID_PARAM rejection lists the
offending fields in .errors. 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.
response, agent_key = master.approve_agent(agent_name="bot1") # generates a fresh key
agent = Exchange(agent_key, base_url=constants.DEVNET_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
info = Info(base_url=constants.DEVNET_API_URL) # WS starts automatically
sid = info.subscribe({"type": "l2Book", "asset": "1"}, lambda m: print(m["data"]["levels"][0][:1]))
info.subscribe({"type": "l2Book", "asset": "1", "group": 1000}, print) # a price grouping from configs digitMerge
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.subscribe({"type": "userAccount", "user": "0x<address>", "marketDeployerId": 1}, print) # every 3s
info.unsubscribe({"type": "l2Book", "asset": "1"}, sid)
info.close()
Channels: l2Book, bbo, trades, candle, ticker, allMarkets, config
(public) and orderUpdates, openOrders, userFills, userAccount
(per-address; userAccount also takes marketDeployerId, since the account view
differs per deployer). l2Book optionally takes group, one of the contract's
digitMerge values; each grouping is a separate stream, and a GroupRemoved
frame (the grouping was dropped from the config) ends it. The client pings every
30s and auto-reconnects, replaying subscriptions.
Several channels open with a snapshot frame whose shape differs from the
increments that follow — openOrders (userOrders's response body),
orderUpdates / userFills (recent history rows in REST's long field names
rather than the compact wire ones), and trades (recent trades, flagged
isSnapshot). candle has no snapshot frame: fetch history with
candle_snapshot and apply the stream on top. Dispatch handles the routing;
your callback still has to read both shapes.
asset may be given as an int; it is sent as the string the server requires.
A refused subscription comes back as an error frame that does not say which
subscription it was — pass Info(ws_error_callback=...) to see those (and
failed AuthResult frames). Callbacks run on the socket's reader thread, so
keep them short.
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). Browser-extension wallets sign typed structs with
their active chain instead of 9767; pass Exchange(..., signature_chain_id=...)
to match that and the SDK sends the unsigned top-level signatureChainId the
server needs to rebuild the domain.
See docs.upsidemax.xyz/guide/authentication.
Examples
Runnable scripts live in examples/. Copy config.json.example to
config.json, set your test wallet and invite code, then:
python examples/01_register_and_airdrop.py
python examples/03_place_and_cancel_order.py
python examples/06_websocket_streams.py
Development
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.
Metadata
Release files for upside-python-sdk 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| upside_python_sdk-0.2.0.tar.gz | 41.3 kB | With provenance | Details for upside_python_sdk-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| upside_python_sdk-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for upside_python_sdk-0.2.0-py3-none-any.whl |
Total release size: 84.0 kB
Release files / upside_python_sdk-0.2.0.tar.gz
| Download URL | upside_python_sdk-0.2.0.tar.gz |
|---|---|
| Size | 41.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
252aca9c2c153e4827aa54752621dc8b5f6075d62dd08778e52e2a39c774f746
|
|
BLAKE2b-256 checksum How to use checksums |
2383a28b5ac94d0eff0b84c74a480076f5f554ee9930bc41098cf0bb7b87e90c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logRelease files / upside_python_sdk-0.2.0-py3-none-any.whl
| Download URL | upside_python_sdk-0.2.0-py3-none-any.whl |
|---|---|
| Size | 42.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8bf56ebf9015482af768e285425cafc250ab204bd34e001114d1c42aef2847ad
|
|
BLAKE2b-256 checksum How to use checksums |
1871b1e78d73cbacf15ac302a82c73540935e0efdfb12d650c60f864dcc41108
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logSecurity for upside-python-sdk 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for upside_python_sdk-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.