Upside API Data Types, Formats, and Conventions

Upside uses a small set of consistent conventions for data representation throughout the API. Understanding these conventions upfront will save you debugging time — in particular, note that prices and sizes are strings, not numbers, and that raw integer values in responses must be scaled before display.

Numeric Values: Strings to Avoid Float Precision Loss

All prices, quantities, and monetary amounts are represented as decimal strings rather than JSON numbers. This avoids the floating-point precision loss that occurs when JSON parsers store large or fractional numbers as IEEE 754 doubles.

{
  "p": "85000",
  "s": "10"
}

Always treat these fields as strings when reading or writing. Pass them through to your exchange layer without converting to float.

Raw Integers and Scale Factors

Numeric values in API responses are raw integers. To obtain the human-readable display value, divide by 10 raised to the scale exponent for that field. Use the configs endpoint to retrieve priceScale and qtyScale for each contract.

Raw value	Scale	Display value
`"850000"`	`priceScale = 2`	`8500.00`
`"1000"`	`qtyScale = 1`	`100.0`

def to_display(raw: str, scale: int) -> float:
    return int(raw) / (10 ** scale)

price_display = to_display("850000", price_scale)  # → 8500.0

The SOL1 contract’s priceScale and qtyScale are published by the configs endpoint. Always read scale values from configs rather than hardcoding them — they differ per contract and can change when new contracts are listed.

Timestamps

All timestamps are int64 Unix milliseconds — the number of milliseconds elapsed since 1970-01-01T00:00:00Z. Timestamps are represented as JSON integers (not strings).

{
  "time": 1754450974231
}

import datetime
dt = datetime.datetime.utcfromtimestamp(1754450974231 / 1000)
# → datetime.datetime(2025, 8, 5, 18, 29, 34, 231000)

Ethereum Addresses

Addresses follow the standard Ethereum format: 0x prefix followed by 40 lowercase hexadecimal characters (42 characters total).

"address": "0x7b94aeea275c43ab537a8cd55f7551688c6521ad"

Always send addresses in lowercase. The server compares addresses case-insensitively, but using lowercase consistently avoids subtle bugs in signature verification and logging.

Contract (Asset) IDs

Each perpetual contract has an integer ID stored in the a field of order, cancel, and modify actions. On testnet, the only available contract is SOL1 with ID 1. Call configs to enumerate all contracts and their IDs in any environment.

{ "a": 1 }   // asset = SOL1

Client Order IDs (cloid)

A client order ID is an int64 decimal string that you assign when placing an order. It must be a unique positive integer. You can use it later to cancel or query orders without needing the server-assigned oid.

{ "c": "1778763737044" }

A Unix millisecond timestamp works well as a client order ID for most use cases — it is unique, monotonically increasing, and easy to generate without a counter.

Short Key Convention (Order Payloads)

Order-related actions use single-letter compact keys to reduce payload size. The mapping is:

Short key	Full name	Type	Description
`a`	`asset`	integer	Contract ID
`b`	`isBuy`	boolean	`true` = buy, `false` = sell
`p`	`price`	string	Limit price
`s`	`size`	string	Order quantity
`r`	`reduceOnly`	boolean	If `true`, order can only reduce an open position
`t`	`orderType`	object	Order type: `{"limit": {"tif": "Gtc"}}`
`c`	`clientOrderId`	string	Optional client-assigned int64 ID

Example order object using short keys:

{
  "a": 1,
  "b": true,
  "p": "50",
  "s": "10",
  "r": false,
  "t": { "limit": { "tif": "Gtc" } },
  "c": "1778763737044"
}

Full Key Convention (Margin and Mode Actions)

Margin and account mode actions use full field names rather than single-letter abbreviations:

Field	Type	Description
`asset`	integer	Contract ID
`isBuy`	boolean	Side of the position to adjust
`isCross`	boolean	`true` = cross margin, `false` = isolated margin
`ntli`	string	New total leverage or isolated margin amount

Example leverage update using full keys:

{
  "type": "updateLeverage",
  "asset": 1,
  "isCross": true,
  "leverage": 10
}

Overview

Authentication

Request Format

Reference

Upside API Data Types, Formats, and Conventions

Numeric Values: Strings to Avoid Float Precision Loss

Raw Integers and Scale Factors

Timestamps

Ethereum Addresses

Contract (Asset) IDs

Client Order IDs (cloid)

Short Key Convention (Order Payloads)

Full Key Convention (Margin and Mode Actions)

​Numeric Values: Strings to Avoid Float Precision Loss

​Raw Integers and Scale Factors

​Timestamps

​Ethereum Addresses

​Contract (Asset) IDs

​Client Order IDs (cloid)

​Short Key Convention (Order Payloads)

​Full Key Convention (Margin and Mode Actions)

Numeric Values: Strings to Avoid Float Precision Loss

Raw Integers and Scale Factors

Timestamps

Ethereum Addresses

Contract (Asset) IDs

Client Order IDs (cloid)

Short Key Convention (Order Payloads)

Full Key Convention (Margin and Mode Actions)