Reading data with Info

from upside import Info
from upside.utils import constants

info = Info(base_url=constants.MAINNET_API_URL)   # WebSocket starts automatically

​

Market data

info.configs()                                   # contracts, coins, scales, tiers — cache this
info.l2_book(asset)                              # full order-book snapshot
info.l2_book(asset, group=group)                 # a price grouping: one of the contract's digitMerge values
info.market_state(asset)                         # mark / oracle / last price, funding
info.ticker(asset)                               # 24h rolling stats; omit asset for every contract
info.candle_snapshot(asset, "1m", start_ms, end_ms)   # historical OHLCV, ascending

• l2_book raises ServerError with code NOT_READY when the contract has no book yet. A group the contract does not offer is rejected with 400.
• candle_snapshot takes start and end times in Unix milliseconds; always pass a window. The interval must be one of 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 3d, 1w, 1M.
• ticker’s window slides over the last 24 hours; it is not a calendar day.

​

Account and orders

info.account_by_address("0x<address>")                    # master or agent address -> accountId ("0" = not registered)
info.user_account(account_id, market_deployer_id)         # balances + positions
info.user_market_deployers(account_id)                    # market deployers the account is enrolled in
info.user_agents(account_id)                              # authorized API wallets
info.user_orders(account_id)                              # live orders, every deployer and contract
info.user_orders(account_id, market_deployer_id, contract_id)
info.orders_by_ids(market_deployer_id, ["8280"])          # look up by exchange order id
info.orders_by_cloids(account_id, market_deployer_id, ["1778844423064"])  # by client order id
info.share_group_state()                                  # portfolio-margin share groups

• user_orders returns live orders only — resting and partially filled orders, plus conditional orders not yet triggered. Finished orders are in order_history. market_deployer_id=0 and contract_id=0 (the defaults) mean all. The answer is capped: when truncated is true the list is incomplete, so narrow the query by deployer or contract rather than treating a missing order as gone.
• orders_by_ids / orders_by_cloids only see live orders too. Filled, canceled, and not-yet-triggered conditional orders are omitted, as are ids from another deployer. Pass the order’s own market_deployer_id (0 matches nothing and is refused locally), and at most 256 ids per call. Ids that are not found are simply absent from the result.

​

History

info.user_fills(account_id)                                   # one row per side the account was on
info.order_history(account_id, contract_id=0)                 # filled / canceled / rejected / triggered orders
info.user_funding_flows(account_id, start_time=start_ms, end_time=end_ms, limit=1000)

• Rows are ascending by time. To page, pass the last row’s time as the next start_time — the bound is inclusive, so de-duplicate the overlapping row (execId for fills, orderId for orders).
• limit is 1 to 1000 (the default is 1000). There may be more rows when the page is full or when truncated is true — a page can be cut short to fit the reply, so a page with fewer rows than limit is not proof you have reached the end.
• end_time=0 means no upper bound. Times are Unix milliseconds.
• History is indexed shortly after execution: an order that just finished may take a moment to appear here.

​

WebSocket streams

sid = info.subscribe(
    {"type": "l2Book", "asset": "1"},
    lambda m: print(m["data"]["levels"][0][:1]),     # best bid
)
info.subscribe({"type": "l2Book", "asset": "1", "group": group}, print)   # a digitMerge grouping
info.subscribe({"type": "trades", "asset": "1"}, print)

# Per-address (private) channels take the wallet address as `user`:
info.subscribe({"type": "orderUpdates", "user": "0x<address>"}, print)
info.subscribe({"type": "userFills", "user": "0x<address>"}, print)
info.subscribe({"type": "userAccount", "user": "0x<address>", "marketDeployerId": 1}, print)

info.unsubscribe({"type": "l2Book", "asset": "1"}, sid)
info.close()

• asset may be given as an int; the SDK sends it as the string the server requires.
• l2Book groupings. group is optional and must be one of the contract’s digitMerge values; each grouping is a separate stream. A group equal to the contract’s tickSize is the raw book and is subscribed as such. A GroupRemoved frame means the grouping was removed from the contract and the stream has ended.
• userAccount pushes the account view for one market deployer periodically, so positions and balances can be streamed rather than polled.
• Snapshot frames. openOrders sends one snapshot when you subscribe — the userOrders response body — and no updates after it; use orderUpdates for changes. orderUpdates / userFills (recent history rows) and trades (recent trades, flagged isSnapshot) open with a snapshot whose shape differs from the updates that follow. candle has no snapshot: fetch history with candle_snapshot and apply the stream on top. Your callback must handle both shapes.
• Refused subscriptions come back as an error frame whose data.subscription echoes the request that was refused. Pass Info(ws_error_callback=...) to receive them.
• A malformed subscription dict raises WebsocketError before anything is sent.