Accounts - Phoenix

This page covers the trader account model after a trader is eligible to use Phoenix. To activate a trader account, see Trader Onboarding.

Trader account indexes

A Phoenix trader account is a PDA derived from the authority wallet, pda_index, subaccount_index, and the Phoenix program id. In the TypeScript SDK these are passed as traderPdaIndex and traderSubaccountIndex; in Rust, TraderKey::new(...) uses (pda_index = 0, subaccount_index = 0) and TraderKey::new_with_idx(...) lets you specify both indexes. Use pda_index = 0 for user accounts. With exchange gating enabled, only pda_index = 0 can be activated; a non-zero PDA index cannot be activated. In the future this will be used to support multiple portfolios.

subaccount_index = 0 is the cross-margin account. It is created during onboarding with max_positions between 32 and 128 inclusive; the default is 128.
subaccount_index > 0 is an isolated account. Isolated accounts have max_positions = 1, so each account is intended for one isolated position.

Cross vs isolated

Cross margin and isolated margin are represented as separate trader subaccounts under the same authority and pda_index.

Account	Index	Created by	Intended use	State stream behavior
Cross account	`subaccount_index = 0`	Trader onboarding	Shared collateral and many positions	Included in the trader-state snapshot and deltas
Isolated account	`subaccount_index > 0`	Register child subaccount, then sync from parent	One isolated position with separate collateral	Included in the same trader-state snapshot and deltas

Subscribe to trader state once per authority and traderPdaIndex. The stream returns the cross account and every registered isolated subaccount in the same snapshot, then sends deltas keyed by subaccountIndex.

Trader state across subaccounts

Use the SDK state primitives instead of applying raw snapshot and delta messages yourself. In TypeScript, createTraderStateStore(client) exposes subaccountIndices(), subaccount(index), position(index, symbol), orders(index, symbol), triggers(index, symbol), and marginInputs() across all subaccounts. In Rust, Trader::apply_update(&msg) maintains a Trader container whose subaccounts map includes cross and isolated accounts.

import { createPhoenixClient, createTraderStateStore } 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 },
});

const traderState = createTraderStateStore(client);
const resource = traderState.resource({
  authority: "AUTHORITY_PUBKEY",
  traderPdaIndex: 0,
});

const release = resource.retain();
const snapshot = await resource.ready();

for (const subaccount of snapshot?.subaccounts ?? []) {
  console.log(subaccount.subaccountIndex, subaccount.collateral);
}

const unsubscribe = resource.subscribe((state, previous) => {
  if (state.snapshot === previous.snapshot) return;

  for (const subaccountIndex of resource.subaccountIndices()) {
    const subaccount = resource.subaccount(subaccountIndex);
    console.log({
      subaccountIndex,
      collateral: subaccount?.collateral,
      positions: subaccount?.positionSymbols,
      orderSymbols: subaccount?.orderSymbols,
    });
  }
});

// Later, when this component/service no longer needs live state:
unsubscribe();
release();

References:

Set position authority

Use the on-chain DelegateTrader instruction to set or replace the position_authority for a trader account. The current account authority signs the transaction; the new position authority is recorded on the trader account but does not need to sign the delegation transaction.

Set position_authority to an embedded wallet, such as a Privy wallet, when you want your app to support one-click transaction signing for trading actions while keeping collateral withdrawals controlled by the user’s authority wallet.

The SDK parameter traderPdaIndex corresponds to the account’s portfolio_index, and traderSubaccountIndex corresponds to subaccount_index.

TypeScript

import { createPhoenixClient } from "@ellipsis-labs/rise";

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

const authority = "PHANTOM_WALLET_PUBKEY";
const newPositionAuthority = "PRIVY_WALLET_PUBKEY";

const delegateTraderIx = await client.ixs.buildDelegateTrader({
  traderWallet: authority,
  traderPdaIndex: 0,
  traderSubaccountIndex: 0,
  newPositionAuthority,
});

// Send this instruction in a transaction signed by `authority`.

DelegateTrader updates one trader account. If you use isolated accounts, each isolated trader account has its own stored position_authority. Syncing a child isolated account from its parent cross account copies the parent’s current position_authority to the child.

Send market orders with position authority

When a trader account has a separate position_authority, build order instructions with the trader account’s original authority, but make the position authority the signing wallet.

SDK	Trader account owner	Market-order signer
TypeScript	Pass `authority` as the trader account authority	Pass `positionAuthority` separately
Rust	Derive `TraderKey` from the trader account authority	Pass `position_authority` to `MarketOrderTicket::authority(...)`

import { Side } from "@ellipsis-labs/rise";

const authority = "PHANTOM_WALLET_PUBKEY";
const positionAuthority = "PRIVY_WALLET_PUBKEY";
const symbol = "SOL";

const marketPacket = await client.orderPackets.buildMarketOrderPacket({
  symbol,
  side: Side.Bid,
  baseUnits: "0.25",
});

const placeMarketIx = await client.ixs.placeMarketOrder({
  authority,
  positionAuthority,
  symbol,
  orderPacket: marketPacket,
});

// Send the transaction with `positionAuthority` as the signer.

In TypeScript, authority is still used to resolve the trader PDA, and positionAuthority becomes the signer account in the Phoenix instruction. In Rust, TraderKey::new(authority) still resolves the trader PDA from the original wallet authority, but the ticket’s .authority(position_authority) is the signer placed into the market-order instruction.

Do not derive a new trader account from the position authority. The trader account remains the PDA for the user’s authority wallet; only the signer changes.

Create isolated accounts

Onboarding creates the user’s cross-margin trader account at traderPdaIndex = 0 and traderSubaccountIndex = 0. After that cross account exists, create isolated accounts by registering a non-zero subaccount index under traderPdaIndex = 0, then syncing the parent cross account to the child isolated account. The sync instruction copies the parent account’s current capabilities and fee configuration to the isolated account.

import { MarginType, createPhoenixClient } from "@ellipsis-labs/rise";

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

const authority = "AUTHORITY_PUBKEY";
const traderPdaIndex = 0;
const isolatedSubaccountIndex = 1;

const registerIsolatedIx = await client.ixs.buildRegisterTrader({
  authority,
  marginType: MarginType.Isolated,
  traderPdaIndex,
  traderSubaccountIndex: isolatedSubaccountIndex,
});

const syncIsolatedIx = await client.ixs.buildSyncParentToChild({
  traderWallet: authority,
  traderPdaIndex,
  traderSubaccountIndex: isolatedSubaccountIndex,
});

const instructions = [registerIsolatedIx, syncIsolatedIx];

// Send the instructions in a transaction signed by `authority`.
// The parent cross account must already exist.

Use traderSubaccountIndex = 0 only for the cross account. Isolated accounts use non-zero subaccount indexes.

Fund isolated accounts and open positions

When you open an isolated position yourself, mirror the same instruction order used by the server-built isolated order routes:

Pick a non-zero isolated subaccount index.
If that child account does not exist, register it.
Sync the parent cross account to the child account.
Transfer collateral from the parent cross account to the child account with TransferCollateral.
Place the order on the child account.
Optionally append TransferCollateralChildToParent to sweep child collateral back to the parent when the child has no active limit orders or positions, including when the order you just placed closes the isolated position.

The parent cross account is subaccount 0. TransferCollateral moves a specific amount between two trader accounts; use srcSubaccountIndex = 0 and dstSubaccountIndex = childSubaccountIndex to fund an isolated child. TypeScript amounts are native USDC units, so 1 USDC = 1_000_000n. The Rust builder accepts decimal USDC amounts.

Unused isolated collateral does not stay parked forever. The server-built isolated order routes append TransferCollateralChildToParent by default, which sweeps collateral back to cross margin in the same transaction if the order closes the position and leaves no active limit orders. An off-chain crank can also sweep idle isolated collateral when the subaccount has no active limit orders or positions.

import {
  MarginType,
  OrderFlags,
  SelfTradeBehavior,
  Side,
  createPhoenixClient,
} from "@ellipsis-labs/rise";

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

const authority = "AUTHORITY_PUBKEY";
const traderPdaIndex = 0;
const childSubaccountIndex = 1;
const symbol = "SOL";
const usdc = (wholeUsdc: bigint) => wholeUsdc * 1_000_000n;

const traderSnapshot = await client.api
  .traders()
  .getTraderStateSnapshot(authority, { traderPdaIndex });

const childExists = traderSnapshot.snapshot.subaccounts.some(
  (subaccount) => subaccount.subaccountIndex === childSubaccountIndex
);

const instructions = [];

if (!childExists) {
  instructions.push(
    await client.ixs.buildRegisterTrader({
      authority,
      marginType: MarginType.Isolated,
      traderPdaIndex,
      traderSubaccountIndex: childSubaccountIndex,
    })
  );
}

instructions.push(
  await client.ixs.buildSyncParentToChild({
    traderWallet: authority,
    traderPdaIndex,
    traderSubaccountIndex: childSubaccountIndex,
  })
);

instructions.push(
  await client.ixs.buildTransferCollateral({
    authority,
    traderPdaIndex,
    srcSubaccountIndex: 0,
    dstSubaccountIndex: childSubaccountIndex,
    amount: usdc(100n),
  })
);

const orderPacket = await client.ixs.orderPackets.buildLimitOrderPacket({
  symbol,
  side: Side.Bid,
  priceUsd: "150",
  baseUnits: "1",
  selfTradeBehavior: SelfTradeBehavior.CancelProvide,
  orderFlags: OrderFlags.None,
  cancelExisting: false,
});

instructions.push(
  await client.ixs.buildPlaceLimitOrder({
    authority,
    symbol,
    orderPacket,
    traderPdaIndex,
    traderSubaccountIndex: childSubaccountIndex,
  })
);

// Optional: mimics the server isolated-order routes' default cleanup step.
// If this order closes the isolated position and leaves no resting orders,
// the remaining child collateral is moved back to the cross account.
instructions.push(
  await client.ixs.buildTransferCollateralChildToParent({
    authority,
    traderPdaIndex,
    childSubaccountIndex,
  })
);

// Send the instructions in a transaction signed by `authority`.
// If you use `positionAuthority`, pass it to transfer/order builders and
// sign the relevant instructions with that delegated authority.

The server routes also check that the parent has enough transferable collateral before creating the transfer instruction. If your app builds these instructions client-side, perform the same check from trader state so you do not try to move collateral reserved for existing margin requirements.

Return isolated collateral to cross margin

Use TransferCollateralChildToParent when an isolated child account should return its collateral to the parent cross account. This instruction targets one child subaccount and transfers all available collateral back to subaccount 0; it does not take an amount parameter. The child account must have no active limit orders or positions. If the child account has no collateral left to transfer, the instruction no-ops on-chain. This is useful after a close-position order. Place the close order first, then append TransferCollateralChildToParent; if the close leaves the isolated account with no active position and no active limit orders, the remaining collateral is moved back to the cross account.

const authority = "AUTHORITY_PUBKEY";
const traderPdaIndex = 0;
const isolatedSubaccountIndex = 1;

const transferToParentIx =
  await client.ixs.buildTransferCollateralChildToParent({
    authority,
    traderPdaIndex,
    childSubaccountIndex: isolatedSubaccountIndex,
  });

// Send the instruction in a transaction signed by `authority`.
// The parent cross account and child isolated account must already exist.

​Trader account indexes

​Cross vs isolated

​Trader state across subaccounts

​Set position authority

​Send market orders with position authority

​Create isolated accounts

​Fund isolated accounts and open positions

​Return isolated collateral to cross margin

Trader account indexes

Cross vs isolated

Trader state across subaccounts

Set position authority

Send market orders with position authority

Create isolated accounts

Fund isolated accounts and open positions

Return isolated collateral to cross margin