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

> Connect coding assistants and automated trading agents to Upside using machine-readable docs, signed write requests, unsigned reads, and real-time WebSocket streams.

Upside supports two complementary agent workflows:

* **Documentation agents** use machine-readable documentation to answer integration questions, generate code, and navigate the API surface.
* **Trading agents** use a dedicated agent wallet to read market and account state, sign approved actions, and react to real-time WebSocket events without exposing the master account's private key.

<Note>
  An AI model should never be treated as the final authority for order parameters, balances, or risk limits. Validate generated payloads in code and enforce deterministic checks before signing or submitting any write request.
</Note>

## Recommended architecture

<Steps>
  <Step title="Discover the documentation">
    Start with [`/llms.txt`](https://upside.mintlify.app/llms.txt) to identify the relevant pages and endpoints without loading the entire documentation set.
  </Step>

  <Step title="Load only the context you need">
    Fetch individual pages for focused tasks, or use [`/llms-full.txt`](https://upside.mintlify.app/llms-full.txt) when the agent needs broad API context for code generation or retrieval.
  </Step>

  <Step title="Read public and account state">
    Use [`POST /info`](/info/overview) for market configuration, prices, order books, orders, balances, positions, and authorized agent records. Read requests do not require request signing.
  </Step>

  <Step title="Execute through a controlled signer">
    Send state-changing operations through [`POST /exchange`](/exchange/overview). Keep the master key offline and authorize a separate API wallet with [`approveAgent`](/exchange/approve-agent) for automated execution.
  </Step>

  <Step title="React to real-time events">
    Subscribe to the [WebSocket API](/websocket/overview) for order-book updates, trades, candles, order changes, open orders, and fills instead of repeatedly polling REST endpoints. **Note:** WebSocket does not yet stream **position** or **balance/collateral** changes — poll [`POST /info`](/info/overview) (`userAccount`) for positions and balances. Native WebSocket streams for them are planned.
  </Step>
</Steps>

## Choose the right integration path

<CardGroup cols={2}>
  <Card title="Machine-readable docs" icon="file-lines" href="/agents/llms-txt">
    Give coding assistants and custom agents a concise documentation index or the full API reference in Markdown.
  </Card>

  <Card title="Agent wallets" icon="key" href="/agents/api-wallets">
    Delegate trading actions to a separate wallet, set an expiry, monitor authorization, and revoke access when needed.
  </Card>

  <Card title="Info API" icon="magnifying-glass" href="/info/overview">
    Retrieve configuration, live market state, account state, and order data without signing.
  </Card>

  <Card title="WebSocket streams" icon="wave-pulse" href="/websocket/overview">
    Maintain a synchronized local view of market and account events for low-latency agent workflows.
  </Card>
</CardGroup>

## Agent control loop

A production trading agent should separate reasoning from execution:

1. **Observe** — read configuration and current state from REST, then keep it fresh through WebSocket subscriptions.
2. **Propose** — let the model or strategy engine produce a structured intent, such as side, contract, size, price, and risk rationale.
3. **Validate** — enforce deterministic rules for contract IDs, numeric precision, maximum position size, leverage, reduce-only behavior, available margin, and allowed action types.
4. **Sign** — sign only the validated action with the authorized agent wallet and a unique nonce.
5. **Submit** — send the envelope to `POST /exchange` and inspect both transport-level and business-level errors.
6. **Reconcile** — confirm the resulting order or fill through `POST /info` and private WebSocket channels. Positions and balances are currently available only via `POST /info` (`userAccount`) — WebSocket does not push them yet.

<Warning>
  Never expose a master or agent private key to an LLM prompt, chat transcript, application log, analytics event, or error-reporting service. Keep signing in a separate, deterministic component backed by a secure secret store.
</Warning>

## Starter system prompt

Use the following as a base prompt for an API-aware coding agent:

```text theme={null}
You are integrating with the Upside API.

Documentation index:
https://upside.mintlify.app/llms.txt

Full documentation:
https://upside.mintlify.app/llms-full.txt

Rules:
- Use POST /info for reads and POST /exchange for writes.
- Do not invent fields, action types, endpoints, or response properties.
- Preserve numeric strings exactly where the API expects strings.
- For writes, use EIP-712 signing (secp256k1) with a unique nonce; see the Authentication page for the Agent and typed paths.
- On the QA environment, `registerAccount` requires a valid single-use `inviteCode` at the envelope top level (not part of the signature); obtain it from the Upside team.
- WebSocket streams market data, order updates, open orders, and fills only. It does NOT yet push position or balance/collateral changes — poll POST /info (userAccount) for positions and balances. Native WS streams for them are planned.
- Never request, reveal, print, or log a private key.
- Return proposed actions as structured JSON for deterministic validation before signing.
- Cite the documentation page used for every non-obvious implementation decision.
```

## Production checklist

* Pin explicit risk limits outside the model prompt.
* Reject unknown fields and unsupported action types with a strict schema.
* Use a named agent wallet with an expiry for each environment or strategy.
* Maintain a monotonic nonce per signing address.
* Reconcile every submitted action against order and fill updates.
* Add a kill switch that revokes the agent and stops the signer independently of the model.
* Test against non-production infrastructure and small limits before increasing exposure.