> ## 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: Perpetuals Trading Guide for Developers

> Upside is an action-based perpetuals exchange. The API provides signed writes, unsigned reads, and real-time WebSocket streams for developers.

Upside is a perpetuals exchange built for programmatic trading. Instead of a traditional REST API with per-resource URLs, every write operation flows through a single `POST /exchange` endpoint — routed by the `action.type` field in the request body. Reads flow through `POST /info`, routed by the `type` field. Real-time market and account updates are delivered over WebSocket. This action-based design keeps the interface minimal and consistent across all trading operations.

## API Channels

The Upside API exposes three channels:

| Channel       | Endpoint         | Auth Required         |
| ------------- | ---------------- | --------------------- |
| **Write**     | `POST /exchange` | Yes — ECDSA signature |
| **Read**      | `POST /info`     | No                    |
| **Streaming** | WebSocket        | No                    |

### Action-Based Routing

Unlike REST APIs that use distinct URLs per resource, Upside routes all requests by a type field in the JSON body:

* **`POST /exchange`** — All state-changing operations (place order, cancel, register account, etc.) share this single URL. The server dispatches by `action.type`.
* **`POST /info`** — All read queries share this URL. The server dispatches by the top-level `type` field.

This means you always `POST` to the same URL and change only the JSON payload to perform different operations.

## Environments

<Warning>
  The UAT and QA environments are for testing only. Funds and accounts are not shared across environments. The Production URL is not yet public — contact the Upside team to get access.
</Warning>

| Environment    | REST Base URL               | WebSocket URL                |
| -------------- | --------------------------- | ---------------------------- |
| **QA**         | `https://dev.upsidemax.xyz` | `wss://dev.upsidemax.xyz/ws` |
| **UAT**        | Contact Upside team         | Contact Upside team          |
| **Production** | TBD — contact Upside team   | TBD — contact Upside team    |

## Testnet Constraints

The QA and UAT environments currently operate with a single contract:

* **Contract:** SOL1
* **Contract ID:** `a` = `1`
* **Quote currency:** USDT1
* **Price (`p`):** Must be an integer; maximum value is `10000`
* **Size (`s`):** Must be a positive integer

<Note>
  These constraints apply to the testnet only. Production contracts will support decimal prices and sizes, and will list additional assets beyond SOL1.
</Note>

## API Version

Current API version: **0.5.4**

## Explore the API

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/guide/quickstart">
    Register an account, place a limit order, and cancel it — all in under 50 lines of Python.
  </Card>

  <Card title="Authentication" icon="key" href="/guide/authentication">
    Learn how to sign `POST /exchange` requests using ECDSA secp256k1.
  </Card>

  <Card title="Write API Overview" icon="pen" href="/exchange/overview">
    Explore all write actions: orders, cancels, account registration, and more.
  </Card>

  <Card title="Read API Overview" icon="magnifying-glass" href="/info/overview">
    Query orders, balances, market data, and configuration via `POST /info`.
  </Card>

  <Card title="WebSocket Overview" icon="bolt" href="/websocket/overview">
    Subscribe to real-time order book updates, trades, and account events.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/guide/error-codes">
    Reference for HTTP-level and business-level error codes with troubleshooting tips.
  </Card>
</CardGroup>