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

# Rise SDK

> Developer SDKs for Phoenix perpetuals in TypeScript and Rust.

Rise is the developer-facing SDK surface for Phoenix perpetual futures. Use it after you understand the protocol concepts in the Phoenix docs and want to build an app, service, bot, or on-chain integration that reads Phoenix state and sends Phoenix instructions.

The SDK currently ships as:

* `rise/ts` - TypeScript SDK with HTTP route clients, a unified Phoenix client, exchange metadata caching, instruction builders, order-packet helpers, WebSocket adapters, trader-state stores, and margin helpers.
* `rise/rust` - Rust workspace centered on the `phoenix-rise` crate, with typed HTTP and WebSocket clients, `PhoenixMetadata`, `PhoenixTxBuilder`, trader-state containers, margin math, and low-level instruction builders.

## Install

### TypeScript

<CodeGroup>
  ```bash npm theme={null}
  npm add @ellipsis-labs/rise
  ```

  ```bash bun theme={null}
  bun add @ellipsis-labs/rise
  ```

  ```bash pnpm theme={null}
  pnpm add @ellipsis-labs/rise
  ```
</CodeGroup>

### Rust

<CodeGroup>
  ```bash Default SDK theme={null}
  cargo add phoenix-rise
  ```

  ```bash API only theme={null}
  cargo add phoenix-rise --no-default-features --features api
  ```

  ```bash On-chain CPI theme={null}
  cargo add phoenix-rise --no-default-features --features cpi
  ```
</CodeGroup>

## Create A Client

<CodeGroup>
  ```ts TypeScript theme={null}
  import { createPhoenixClient } from "@ellipsis-labs/rise";

  const client = createPhoenixClient({
    apiUrl: "https://perp-api.phoenix.trade",
    rpcUrl: "https://api.mainnet-beta.solana.com",
    ws: { connectMode: "eager" },
    exchangeMetadata: { stream: true },
  });
  ```

  ```rust Rust theme={null}
  use phoenix_rise::{PhoenixHttpClient, PhoenixMetadata};

  let http = PhoenixHttpClient::new_from_env()?;
  let exchange = http.get_exchange().await?.into();
  let metadata = PhoenixMetadata::new(exchange);
  ```
</CodeGroup>

For package setup and runnable examples, use the public SDK sources:

* [TypeScript README](https://github.com/Ellipsis-Labs/rise-public/blob/master/ts/README.md)
* [TypeScript examples](https://github.com/Ellipsis-Labs/rise-public/tree/master/ts/examples)
* [Rust README](https://github.com/Ellipsis-Labs/rise-public/blob/master/rust/README.md)
* [Rust SDK examples](https://github.com/Ellipsis-Labs/rise-public/tree/master/rust/sdk/examples)

## Which Client To Use

| Task                                                                   | TypeScript                                                      | Rust                                    |
| ---------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------- |
| HTTP snapshots, history, and transaction-builder routes                | `client.api` or `PhoenixHttpClient`                             | `PhoenixHttpClient`                     |
| Exchange params, market metadata, PDA context, and order-packet sizing | `client.exchange` cache                                         | `PhoenixMetadata`                       |
| Live market, orderbook, exchange, and trader streams                   | `client.streams`, `client.marketData()`, `client.orderbooks()`  | `PhoenixWSClient` plus typed containers |
| Trader snapshots and deltas                                            | `createTraderStateStore(client)`                                | `Trader::apply_update(...)`             |
| Build Phoenix instructions                                             | `client.ixs`                                                    | `PhoenixTxBuilder`                      |
| Margin and account-health calculations                                 | `createMarginCalculator(...)` and trader-state `marginInputs()` | `TraderPortfolio::compute_margin(...)`  |

Prefer the exchange cache for market parameters. In TypeScript, wait for `client.exchange.ready()` and read markets with `client.exchange.market(symbol)` or `client.exchange.marketMetadata(symbol)`. In Rust, build `PhoenixMetadata` from `http.get_exchange()` and update it with live market stats through `metadata.apply_market_stats(&stats)`.

Prefer trader-state primitives for snapshots and deltas. In TypeScript, `createTraderStateStore(client)` maintains local trader resources and exposes `marginInputs()`. In Rust, `Trader::apply_update(&msg)` applies `traderState` snapshots and deltas to the local container.

## First Reads

<CodeGroup>
  ```ts TypeScript theme={null}
  const snapshot = await client.exchange.ready();
  const sol = client.exchange.market("SOL");
  const solMetadata = client.exchange.marketMetadata("SOL");
  const trader = await client.api
    .traders()
    .getTraderStateSnapshot("AUTHORITY_PUBKEY", { traderPdaIndex: 0 });

  console.log(snapshot.markets.length, sol?.assetId, solMetadata?.logoUri);
  console.log(trader.snapshot.subaccounts);
  ```

  ```rust Rust theme={null}
  use phoenix_rise::{PhoenixHttpClient, PhoenixMetadata};
  use solana_pubkey::Pubkey;
  use std::str::FromStr;

  let http = PhoenixHttpClient::new_from_env()?;
  let exchange = http.get_exchange().await?.into();
  let metadata = PhoenixMetadata::new(exchange);
  let authority = Pubkey::from_str("AUTHORITY_PUBKEY")?;

  let sol = metadata.get_market("SOL");
  let trader = http.traders().get_trader(&authority).await?;

  println!("{:?} {}", sol.map(|m| &m.symbol), trader.len());
  ```
</CodeGroup>

Runnable references:

* [TypeScript HTTP client example](https://github.com/Ellipsis-Labs/rise-public/blob/master/ts/examples/01-http-client.ts)
* [TypeScript unified client example](https://github.com/Ellipsis-Labs/rise-public/blob/master/ts/examples/phoenix-client-example.ts)
* [Rust HTTP client example](https://github.com/Ellipsis-Labs/rise-public/blob/master/rust/sdk/examples/http_client.rs)
* [Rust Phoenix client example](https://github.com/Ellipsis-Labs/rise-public/blob/master/rust/sdk/examples/phoenix_client.rs)

## Reading Order

1. [Auth](/sdk/auth) - optional for most public reads, required for referral onboarding and notifications.
2. [Trader Onboarding](/sdk/register) - create or activate a trader account.
3. [Accounts](/sdk/accounts) - understand authority, position authority, cross accounts, isolated accounts, and trader-state streams.
4. [Collateral](/sdk/collateral) - move USDC into and out of Phoenix trader accounts.
5. [Exchange Data](/sdk/markets) - exchange cache, market metadata, L2 orderbooks, market stats, and market calendars.
6. [WS/API Best Practices](/sdk/ws-api-best-practices) - when to stream, when to poll, and how to avoid rate-limit and drift issues.
7. [Orders](/sdk/orders) - build order instructions and manage stop losses and conditionals.
8. [Margin](/sdk/margin) - join market prices, compute account health, margin, and liquidation estimates.
9. [On-Chain Programs](/sdk/on-chain-programs) and [LiteSVM Testing](/sdk/litesvm-testing) - program integrations and local tests.

## REST, WebSocket, and RPC

Use REST for startup snapshots, historical data, and server-built transaction workflows. Use WebSocket streams for current market state, exchange deltas, orderbooks, and trader state. Use Solana RPC for blockhashes, simulation, transaction submission, confirmation, and custom account reads.

The usual production pattern is:

1. Fetch HTTP snapshots on startup.
2. Subscribe to WebSocket streams.
3. Apply exchange and trader deltas locally through SDK caches.
4. Build and sign instructions with the user's wallet or signer service.
5. Confirm transactions through Solana RPC.
6. Reconcile from trader-state streams, falling back to fresh HTTP snapshots after reconnects or sequence gaps.