> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Upside API Data Types, Formats, and Conventions

> Reference for numeric strings, timestamps, address format, contract IDs, client order IDs, and the short key convention used in order payloads.

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.

```json theme={"system"}
{
  "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`       |

```python theme={"system"}
def to_display(raw: str, scale: int) -> float:
    return int(raw) / (10 ** scale)

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

<Note>
  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.
</Note>

## 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).

```json theme={"system"}
{
  "time": 1754450974231
}
```

```python theme={"system"}
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).

```text theme={"system"}
"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.

```json theme={"system"}
{ "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`.

```json theme={"system"}
{ "c": "1778763737044" }
```

<Tip>
  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.
</Tip>

## 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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "type": "updateLeverage",
  "asset": 1,
  "isCross": true,
  "leverage": 10
}
```