Trader Interactions

Note

Flash v2 trading is basket-backed: your positions and orders live inside a per-wallet basket, funded from a deposit ledger. Complete the one-time setup below before you trade.

Set up flashClient, poolConfig, and walletKeypair as shown on the Flash SDK v2 landing page. Every snippet on this page assumes all three are in scope. Trading instructions are sent with sendAndConfirmErTransaction, signed by your walletKeypair (or a session key if you've set one up for a UI).

One-time setup

Run these once per wallet. The init/activate steps are idempotent — if the account already exists the SDK returns an empty instruction set, so they're safe to re-run; depositDirect always transfers funds.

import { BN } from '@coral-xyz/anchor'

const usdcMint = poolConfig.getTokenFromSymbol('USDC').mintKey

// 1) Deposit ledger (tracks your collateral).
await flashClient.sendAndConfirmTransaction(
  (await flashClient.initializeUserDepositLedger()).instructions,
)

// 2) Basket (holds your positions + orders).
await flashClient.sendAndConfirmTransaction(
  (await flashClient.initializeBasket()).instructions,
)

// 3) Trade vault for each collateral mint (once per mint, globally).
await flashClient.sendAndConfirmTransaction(
  (await flashClient.initTradeVault(usdcMint)).instructions,
)

// 4) Fund the deposit ledger (amount in base units).
await flashClient.sendAndConfirmTransaction(
  (await flashClient.depositDirect(usdcMint, new BN(25_000_000))).instructions, // 25 USDC
)

// 5) Activate the basket for trading.
await flashClient.sendAndConfirmTransaction(
  (await flashClient.delegateBasket(flashClient.wallet)).instructions,
)

depositDirect(tokenMint, amount, tokenProgramId?, depositor?) wraps native SOL (NATIVE_MINT) automatically and does idempotent ATA creation for SPL tokens. Pass TOKEN_2022_PROGRAM_ID as the third arg for Token-2022 mints.

Resolving the market

A position is scoped to a market — identified by a target asset, a collateral token, and a side. For a given target + side, the collateral is fixed by the market, so you look it up rather than choosing it:

import { Side, isVariant } from '@flash_trade/flash-sdk-v2'

const getMarket = (targetSymbol: string, side: Side) => {
  const targetCustody = poolConfig.custodies.find(
    (c) => c.mintKey.equals(poolConfig.getTokenFromSymbol(targetSymbol).mintKey),
  )!
  const market = poolConfig.markets.find(
    (m) =>
      m.targetCustody.equals(targetCustody.custodyAccount) &&
      isVariant(m.side, 'long') === isVariant(side, 'long'),
  )
  if (!market) throw new Error(`no ${isVariant(side, 'long') ? 'long' : 'short'} market for ${targetSymbol}`)
  const collateral = poolConfig.custodies.find((c) => c.custodyAccount.equals(market.collateralCustody))!
  return { market: market.marketAccount, side, collateralSymbol: collateral.symbol }
}

Prices & slippage

Read the current oracle price and convert it to a slippage-bounded ContractOraclePrice with getPriceAfterSlippage:

import { BN } from '@coral-xyz/anchor'
import { Side, type ContractOraclePrice } from '@flash_trade/flash-sdk-v2'

const getEntryPrice = async (
  targetSymbol: string,
  side: Side,
  isEntry: boolean,
  slippageBps = new BN(100), // 1%
): Promise<ContractOraclePrice> => {
  const custody = poolConfig.custodies.find(
    (c) => c.mintKey.equals(poolConfig.getTokenFromSymbol(targetSymbol).mintKey),
  )!
  const program = flashClient.erProgram ?? flashClient.program
  const oracle = (await program.account.customOracle.fetch(custody.intOracleAccount)) as {
    price: BN
    expo: number
  }
  return flashClient.getPriceAfterSlippage(
    isEntry,
    slippageBps,
    { price: oracle.price, exponent: new BN(oracle.expo) },
    side,
  )
}

Privilege accounts (Referral & Stake)

Position operations (openPosition, closePosition, increasePositionSize, decreasePositionSize) accept a trailing (privilege, referralAccount, tokenStakeAccount) triplet that determines your fee tier.

Privilege	When	Pass
Privilege.None (default)	no FAF stake, no referral	nothing — omit both accounts, trade at full fee
Privilege.Stake	trader holds an active FAF stake	trader's own tokenStakeAccount
Privilege.Referral	trader was referred	trader's own referralAccount and the referrer's tokenStakeAccount

import { Privilege, findTokenStakeAddress, findReferralAddress } from '@flash_trade/flash-sdk-v2'

const [tokenStakeAccount] = findTokenStakeAddress(flashClient.wallet, flashClient.programId)
const [referralAccount]   = findReferralAddress(flashClient.wallet, flashClient.programId)

A missing or invalid privilege account never reverts the trade — the program just charges full fee. If you don't care about discounts, omit the trailing args entirely (they default to Privilege.None).

Open a position

The 2nd and 3rd args are the market's collateral symbol — you pay collateral in the market's own token.

const collateralAmount = new BN(5_000_000)  // collateral, in the market's collateral-token base units
const leverage         = new BN(20_000)     // 2× (BPS_DECIMALS = 4)

const openPosition = async (targetSymbol: string, side: Side) => {
  const { market, collateralSymbol } = getMarket(targetSymbol, side)
  const price = await getEntryPrice(targetSymbol, side, true)

  // sizeAmount is in TARGET-token base units (not USD). Derive it from a quote at
  // your target leverage so you don't trip MinLeverage by guessing a raw size.
  const { sizeAmount } = await flashClient.views.getOpenPositionQuoteEr(poolConfig, {
    market, targetSymbol, collateralSymbol, receivingSymbol: collateralSymbol,
    amountIn: collateralAmount, leverage,
  })

  const { instructions } = await flashClient.openPosition(
    targetSymbol,
    collateralSymbol,  // lock symbol
    collateralSymbol,  // collateral symbol
    side,
    poolConfig,
    price,
    collateralAmount,
    sizeAmount,
    // optional: privilege, referralAccount, tokenStakeAccount
  )

  const sig = await flashClient.sendAndConfirmErTransaction(instructions, [walletKeypair])
  console.log('opened:', sig)
}

await openPosition('SOL', Side.Long)

openPosition only opens a new position. To add to an existing position in the same market, use increasePositionSize.

Close a position

Pass an optional receivingSymbol (6th arg) to receive proceeds as a different token; omit it to receive the market's collateral.

const closePosition = async (targetSymbol: string, side: Side) => {
  const { market, collateralSymbol } = getMarket(targetSymbol, side)
  const price = await getEntryPrice(targetSymbol, side, false) // exit price

  const { instructions } = await flashClient.closePosition(
    targetSymbol, collateralSymbol, side, poolConfig, price,
    // receivingSymbol?, privilege?, referralAccount?, tokenStakeAccount?
  )

  // If the position has trigger (TP/SL) orders, cancel them in the same tx:
  const { instructions: cancelIxs } = await flashClient.cancelAllTriggerOrders(market)

  const sig = await flashClient.sendAndConfirmErTransaction([...instructions, ...cancelIxs], [walletKeypair])
  console.log('closed:', sig)
}

Increase / decrease position size

const { collateralSymbol } = getMarket('SOL', Side.Long)

// Increase: add size (and collateral — must be non-zero).
const inc = await flashClient.increasePositionSize(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  await getEntryPrice('SOL', Side.Long, true),
  new BN(20_000_000), // sizeDelta
  new BN(2_000_000),  // collateralAmount to add
  // receivingSymbol?, privilege?, referralAccount?, tokenStakeAccount?
)
await flashClient.sendAndConfirmErTransaction(inc.instructions, [walletKeypair])

// Decrease: partially close.
const dec = await flashClient.decreasePositionSize(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  await getEntryPrice('SOL', Side.Long, false),
  new BN(20_000_000), // sizeDelta to remove
  // dispensingSymbol?, privilege?, referralAccount?, tokenStakeAccount?
)
await flashClient.sendAndConfirmErTransaction(dec.instructions, [walletKeypair])

Add / remove collateral

const { collateralSymbol } = getMarket('SOL', Side.Long)

// Add collateral (amount in the pay token's base units).
const add = await flashClient.addCollateral(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  new BN(3_000_000), // collateralDelta
  // receivingSymbol? — defaults to the market's collateral
)
await flashClient.sendAndConfirmErTransaction(add.instructions, [walletKeypair])

// Remove collateral (amount in USD, 6 decimals).
const remove = await flashClient.removeCollateral(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  new BN(2_000_000), // collateralDeltaUsd = $2.00
  // dispensingSymbol? — defaults to the market's collateral
)
await flashClient.sendAndConfirmErTransaction(remove.instructions, [walletKeypair])

removeCollateral takes a USD amount (6 decimals); addCollateral takes an amount in the pay token's base units.

Limit orders

A limit order carries its own take-profit and stop-loss inline. Build the three prices as ContractOraclePrice from the live oracle exponent.

const { collateralSymbol } = getMarket('SOL', Side.Long)

const { instructions } = await flashClient.placeLimitOrder(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  limitPrice,        // ContractOraclePrice — trigger
  new BN(5_000_000), // reserveAmount (collateral reserved for the fill)
  new BN(50_000_000),// sizeAmount
  stopLossPrice,     // ContractOraclePrice (use { price: BN_ZERO, exponent } to skip)
  takeProfitPrice,   // ContractOraclePrice
  // receivingSymbol?
)
await flashClient.sendAndConfirmErTransaction(instructions, [walletKeypair])

Edit and cancel by orderId (the order's index in your basket):

const edit = await flashClient.editLimitOrder(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  orderId, limitPrice, sizeAmount, stopLossPrice, takeProfitPrice, /* receivingSymbol? */
)
await flashClient.sendAndConfirmErTransaction(edit.instructions, [walletKeypair])

const cancel = await flashClient.cancelLimitOrder('SOL', collateralSymbol, Side.Long, poolConfig, orderId)
await flashClient.sendAndConfirmErTransaction(cancel.instructions, [walletKeypair])

Trigger orders (Take Profit / Stop Loss)

A trigger order attaches a TP or SL to an open position. isStopLoss selects which: true = stop-loss, false = take-profit. deltaSizeAmount is how much of the position to close when it fires.

const { market, collateralSymbol } = getMarket('SOL', Side.Long)

const tp = await flashClient.placeTriggerOrder(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  takeProfitPrice, positionSizeAmount, false, // isStopLoss = false → take-profit
  // receiveSymbol?
)
const sl = await flashClient.placeTriggerOrder(
  'SOL', collateralSymbol, Side.Long, poolConfig,
  stopLossPrice, positionSizeAmount, true,    // isStopLoss = true → stop-loss
)
await flashClient.sendAndConfirmErTransaction([...tp.instructions, ...sl.instructions], [walletKeypair])

// Edit / cancel
await flashClient.editTriggerOrder('SOL', collateralSymbol, Side.Long, poolConfig, orderId, newPrice, deltaSize, isStopLoss)
await flashClient.cancelTriggerOrder(market, orderId, isStopLoss) // takes the market PublicKey
await flashClient.cancelAllTriggerOrders(market)

TP/SL price rules:

• Stop Loss — above liq price & below current price for LONG; below liq price & above current price for SHORT.

• Take Profit — above current price for LONG; below current price for SHORT.

• Virtual tokens — take profit must be below the max-profit price for LONG.

Quotes (views)

Quote before you trade. The *Er variants read the basket-held position (pass owner for position-bound quotes). All take the poolConfig and an arg object.

// collateralSymbol must be the market's collateral token (from getMarket), not a
// hardcoded 'USDC' — the wrong symbol makes the market PDA mismatch (ConstraintSeeds).
const { market, collateralSymbol } = getMarket('SOL', Side.Long)
const owner = flashClient.wallet

const openQuote = await flashClient.views.getOpenPositionQuoteEr(poolConfig, {
  market, targetSymbol: 'SOL', collateralSymbol, receivingSymbol: collateralSymbol,
  amountIn: new BN(5_000_000), leverage: new BN(20000), // 2x, BPS_DECIMALS = 4
})

const closeQuote = await flashClient.views.getClosePositionQuoteEr(poolConfig, {
  owner, market, targetSymbol: 'SOL', collateralSymbol,
  dispensingSymbol: collateralSymbol, sizeDeltaUsd: new BN(10_000_000),
})

const pnl  = await flashClient.views.getPnlEr(poolConfig, { owner, market, targetSymbol: 'SOL', collateralSymbol })
const data = await flashClient.views.getPositionDataEr(poolConfig, { owner, market, targetSymbol: 'SOL', collateralSymbol })
const liq  = await flashClient.views.getLiquidationPriceEr(poolConfig, { owner, market, targetSymbol: 'SOL', collateralSymbol })

// Add/remove-collateral quotes, entry/exit price & fee, liquidation state — same shape.

Views are read-only simulations (no signing, no transaction). Poll getPositionDataEr for a live PnL / leverage / liquidation-price ticker.

Reading positions & orders

Your open positions and orders are embedded in the basket:

const basket = await flashClient.erAccounts!.fetchBasket(flashClient.wallet)

basket.positions // PositionMeta[] — size, collateral, entry, market, …
basket.orders    // OrderMeta[]   — limit + trigger orders

basket.getPosition(marketPk)     // the position for a market, if any
basket.hasOpenPosition(marketPk) // boolean
basket.getOpenPositionCount()

To stream updates, subscribe to the basket PDA with onAccountChange — see Reading accounts on the landing page.