Skip to main content
Do not build new integrations around /v1/invite/activate or /v1/referral/activate. These sponsored activation routes will be deprecated on June 30, 2026.

​
Choose a path

Use the first path that matches your situation:
  1. New traders using the Phoenix UI should onboard in the Phoenix app at phoenix.trade.
  2. New traders or SDK integrations with a valid referral code should register the trader account with the user’s wallet, then use /v1/referral/activate-tx to apply the referral.
  3. Large integrations onboarding more than 100 users should ask Phoenix for a finite-use delegated signer. The integration can decide whether it or its users pay rent.
  4. Protocols that want permissionless onboarding should ask Phoenix to grant onboarding privileges to a program PDA controlled by the protocol’s on-chain program.

​
Referral activation transaction

Most users should onboard through the Phoenix app at phoenix.trade. Use /v1/referral/activate-tx when you are building an SDK or integration flow for a trader with a valid referral code. /v1/referral/activate-tx does not create the trader account. Register the trader’s default cross-margin account first with the trader’s wallet, or another payer controlled by your app. The endpoint only validates the referral code, adds the Phoenix onboarder signature to the activation transaction, submits it, and records the referral claim. The flow is:
  1. Ensure the trader account exists at traderPdaIndex = 0 and traderSubaccountIndex = 0. If it is missing, register it first.
  2. Fetch the current referral activation accounts from GET /v1/referral/activation-permission.
  3. Build the referral activation transaction. This transaction contains the delegated onboarding instruction, not RegisterTrader.
  4. Have the trader authority sign the transaction. If you use a separate fee payer, that payer signs too.
  5. Submit the partially signed transaction to POST /v1/referral/activate-tx.
  6. Phoenix validates the referral code and transaction, signs the delegated activation, submits the transaction, and returns the transaction signature and trader PDA.
Example request: 
{
    "referral_code": "CODE",
    "trader_authority": "TRADER_AUTHORITY_PUBKEY",
    "recent_blockhash": "RECENT_BLOCKHASH",
    "transaction": "BASE64_ENCODED_TRANSACTION"
}
Example response: 
{
    "signature": "TRANSACTION_SIGNATURE",
    "trader_pda": "TRADER_ACCOUNT_PDA",
    "referral_code": "CODE",
    "status": "activated"
}
status can be activated, submitted, or already_activated. A submitted response means the transaction was confirmed and the referral claim was recorded, but Phoenix did not observe the trader account before the API timeout. 
import {
  MarginType,
  createPhoenixClient,
} from "@ellipsis-labs/rise";
import { Connection, PublicKey, VersionedTransaction } from "@solana/web3.js";

declare const wallet: {
  publicKey: { toBase58(): string };
  signTransaction(tx: VersionedTransaction): Promise<VersionedTransaction>;
};

declare function sendPhoenixInstructions(instructions: unknown[]): Promise<string>;

const apiUrl = "https://perp-api.phoenix.trade";
const rpcUrl = "https://api.mainnet-beta.solana.com";
const referralCode = "CODE";
const traderPdaIndex = 0;
const traderSubaccountIndex = 0;
const traderAuthority = wallet.publicKey.toBase58();

const client = createPhoenixClient({
  apiUrl,
  rpcUrl,
  exchangeMetadata: { stream: false },
});
const connection = new Connection(rpcUrl);

const traderAccount = await client.pda.getTraderAddress({
  authority: traderAuthority,
  traderPdaIndex,
  subaccountIndex: traderSubaccountIndex,
});

if (!(await connection.getAccountInfo(new PublicKey(traderAccount)))) {
  const registerTraderIx = await client.ixs.buildRegisterTrader({
    authority: traderAuthority,
    marginType: MarginType.Cross,
    traderPdaIndex,
    traderSubaccountIndex,
  });

  await sendPhoenixInstructions([registerTraderIx]);
}

const { blockhash } = await connection.getLatestBlockhash();

const built = await client.api.invite().buildActivateReferralTxRequest({
  referralCode,
  traderAuthority,
  traderPdaIndex,
  traderSubaccountIndex,
  recentBlockhash: blockhash,
  signTransaction: async (_transaction, context) => {
    const tx = VersionedTransaction.deserialize(
      context.unsignedTransactionBytes
    );
    const signed = await wallet.signTransaction(tx);
    return signed.serialize();
  },
});

const activation = await client.api.invite().activateReferralTx(built.request);

console.log(activation.trader_pda, activation.status);
Phoenix does not sponsor this flow. Trader account rent is paid when your app registers the trader account, and the activation transaction fee is paid by the transaction signer.
The Rust SDK includes a full runnable example for this flow: rust/examples/referral_activation_tx.rs.

​
Builder delegated signer

Use a builder delegated signer when a team expects to onboard more than 100 traders, such as a wallet, bot, protocol, or campaign integration. In this model, the builder reaches out to Phoenix and receives a finite-use delegated onboarding grant. The grant allows a specific signer to onboard a limited number of traders. The builder then owns the onboarding UX and chooses the payer model:
  • the builder can pay transaction fees and trader-account rent for users
  • the user can pay rent from their own wallet
  • the builder can support both modes depending on product needs
This is the right path when the integration needs more control than /v1/referral/activate-tx, does not want to route every user through a referral-code API call, or expects a large number of activations. Builder responsibilities:
  • keep the delegated signer secure
  • track remaining onboarding uses
  • make onboarding idempotent for retries
  • confirm the trader account is active before marking the user onboarded
  • request a new grant or use-budget increase before the grant is exhausted
Complete delegated-signer examples are available in the Rise public repository: The core transaction is: 
import {
  buildRegisterTraderIx,
  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 delegatedSigner = "DELEGATED_SIGNER_PUBKEY";
const traderAuthority = "TRADER_AUTHORITY_PUBKEY";
const permissionAccount = "PERMISSION_ACCOUNT_PDA";
const traderPdaIndex = 0;
const traderSubaccountIndex = 0;

declare function accountExists(address: string): Promise<boolean>;

const traderAccount = await client.pda.getTraderAddress({
  authority: traderAuthority,
  traderPdaIndex,
  subaccountIndex: traderSubaccountIndex,
});

const instructions = [];

if (!(await accountExists(traderAccount))) {
  instructions.push(
    buildRegisterTraderIx({
      programAddress: client.pda.getProgramAddress(),
      logAuthorityAddress: await client.pda.getLogAuthorityAddress(),
      globalConfigurationAddress:
        await client.pda.getGlobalConfigurationAddress(),
      payer: delegatedSigner,
      trader: traderAuthority,
      traderAccount,
      maxPositions: 128n,
      traderPdaIndex,
      traderSubaccountIndex,
    })
  );
}

instructions.push(
  await client.ixs.buildOnboardTraderDelegated({
    authority: delegatedSigner,
    traderAuthority,
    permissionAccount,
    traderPdaIndex,
    traderSubaccountIndex,
  })
);

// Send these instructions in a transaction signed by `delegatedSigner`.
The full examples can also run an optional grant step when the grant manager is authorized to create or refresh the builder’s onboarding budget.

​
Program PDA onboarding

Use program PDA onboarding when a builder wants permissionless onboarding through its own on-chain program. In this model, Phoenix grants trader-onboarding privileges to a PDA controlled by the builder’s program. Users call the builder program, and the program uses its PDA as the delegated Phoenix signer. The program can enforce the builder’s own rules before spending an onboarding use. The high-level flow is:
  1. Phoenix grants onboarding privileges to the program PDA.
  2. A user calls the builder program to onboard.
  3. The builder program registers the Phoenix trader account if needed, then activates it using its PDA authority.
  4. The resulting Phoenix trader account is owned by the trader authority, not by the builder program.
This path is useful when:
  • onboarding should happen without a backend-held signer
  • the builder wants on-chain rules for who can onboard
  • users should be able to onboard directly through the builder program
  • the builder wants its program, not a keypair, to hold the delegated authority
The builder program decides whether the user pays rent, the builder pays rent, or another payer is allowed. The trader authority still owns the resulting Phoenix trader account. The Rise public repository includes a programs/trader-onboarder example that demonstrates this pattern. At a high level, the program instruction looks like:
Rust
pub fn create_trader_idempotent(ctx: CreateTrader) -> ProgramResult {
    // The payer funds rent for the Phoenix trader account.
    register_trader_if_missing(&ctx)?;

    // The builder program signs the delegated onboarding call with its PDA.
    onboard_with_program_pda(&ctx)?;

    Ok(())
}

​
After onboarding

Registration creates the trader’s default cross-margin account at traderPdaIndex = 0 and traderSubaccountIndex = 0. Referral activation and delegated onboarding then make that account eligible to trade. For account indexes and isolated subaccounts, see Trader Accounts.