Transaction Builder
Transaction builder endpoints do two things:
Preview — Calculate fees, leverage, liquidation price, and other outputs before committing.
Build — Return a base64-encoded Solana transaction ready to be signed and sent.
Preview only: omit the owner field.
Preview + transaction: include owner with the wallet pubkey.
All responses include an err field — null on success, or an error message if computation failed. Always check err !== null before using the response.
Open Position
Open a new position or increase an existing one.
POST /transaction-builder/open-positionRequest body:
json
{
"inputTokenSymbol": "USDC",
"outputTokenSymbol": "SOL",
"inputAmountUi": "100.0",
"leverage": 5.0,
"tradeType": "LONG",
"owner": "YOUR_WALLET_PUBKEY"
}inputTokenSymbol
string
yes
Token you're paying with (e.g., "USDC", "SOL")
outputTokenSymbol
string
yes
Market token (e.g., "SOL", "BTC")
inputAmountUi
string
yes
Amount to pay, human-readable
leverage
number
yes
Leverage multiplier (e.g., 5.0 for 5x)
tradeType
string
yes
"LONG", "SHORT", or "SWAP"
orderType
string
no
"MARKET" (default) or "LIMIT"
limitPrice
string
no
Trigger price for limit orders
degenMode
boolean
no
Enable high-leverage degen mode
tradingFeeDiscountPercent
number
no
Fee discount from staking (0–100)
owner
string
no
Wallet pubkey. Omit for preview-only; include to build the transaction
slippagePercentage
string
no
Slippage tolerance (default "0.5")
takeProfit
string
no
TP trigger price — creates TP order in the same transaction
stopLoss
string
no
SL trigger price — creates SL order in the same transaction
tokenStakeFafAccount
string
no
FAF stake account (for fee discount)
userReferralAccount
string
no
Referral account
privilege
string
no
"NONE", "STAKE", or "REFERRAL" — overrides auto-inference
Preview only (no transaction):
bash
With transaction + TP/SL:
bash
Response:
json
oldLeverage / oldEntryPrice / oldLiquidationPrice
Previous values — present when increasing an existing position, null for new positions
newLeverage / newEntryPrice / newLiquidationPrice
Values after this trade
entryFee
Entry fee after discount
entryFeeBeforeDiscount
Entry fee before discount
openPositionFeePercent
Fee rate as a percentage string (e.g., "0.03600" = 0.036%)
availableLiquidity
Available liquidity for this market
youPayUsdUi
Total USD collateral you're paying
youRecieveUsdUi
Total USD position size after leverage
marginFeePercentage
Hourly borrow rate (e.g., "0.00800" = 0.008%/hr)
outputAmount
Size in native token units (raw u64)
outputAmountUi
Size in human-readable token amount
transactionBase64
Ready-to-sign Solana transaction (null if owner not provided)
takeProfitQuote / stopLossQuote
Projected PnL at TP/SL prices (present when takeProfit / stopLoss provided)
swapInPriceUi / swapOutPriceUi / swapFeeUsdUi
Present for SWAP trade type only
err
Error message or null
Close Position
Close all or part of an existing position.
Request body:
json
positionKey
string
yes
Position account pubkey to close
inputUsdUi
string
yes
USD amount to close — use full position size for a full close
withdrawTokenSymbol
string
yes
Token to receive proceeds in
keepLeverageSame
boolean
no
Keep leverage constant during partial close
slippagePercentage
string
no
Slippage tolerance (default "0.5")
tradingFeeDiscountPercent
number
no
Fee discount from staking (0–100)
tokenStakeFafAccount
string
no
FAF stake account
userReferralAccount
string
no
Referral account
privilege
string
no
"NONE", "STAKE", or "REFERRAL"
Response:
json
receiveTokenAmountUi
Amount of the receive token you'll get
markPrice
Current market price — what you're closing at
entryPrice
Your original entry price
existingSize → newSize
Position size before and after the close ("0.00" for full close)
settledPnl
Realized PnL in USD (negative for a loss)
fees
Total fees (exit + borrow) after discount
lockAndUnsettledFeeUsd
Present for partial closes only — fee on locked collateral
Add Collateral
Deposit more collateral to reduce leverage and move your liquidation price further away.
Request body:
json
positionKey
string
yes
Position account pubkey
depositAmountUi
string
yes
Amount to deposit (in deposit token units)
depositTokenSymbol
string
yes
Token to deposit
owner
string
yes
Wallet pubkey — always required for collateral changes
slippagePercentage
string
no
Slippage tolerance
Response:
json
Remove Collateral
Withdraw collateral from a position. Increases leverage and moves the liquidation price closer.
Request body:
json
positionKey
string
yes
Position account pubkey
withdrawAmountUsdUi
string
yes
USD amount to withdraw
withdrawTokenSymbol
string
yes
Token to receive
owner
string
yes
Wallet pubkey
slippagePercentage
string
no
Slippage tolerance
Response:
json
Reverse Position
Flip a position from Long to Short (or vice versa) in a single atomic transaction. Closes the existing position and opens a new one in the opposite direction.
Request body:
json
positionKey
string
yes
Position account pubkey to reverse
owner
string
yes
Wallet pubkey
slippagePercentage
string
no
Slippage tolerance
tradingFeeDiscountPercent
number
no
Fee discount (0–100)
tokenStakeFafAccount
string
no
FAF stake account
userReferralAccount
string
no
Referral account
privilege
string
no
"NONE", "STAKE", or "REFERRAL"
degenMode
boolean
no
Enable degen mode for the new position
Response:
json
Note: newCollateralUsd reflects a 2% haircut applied during the reversal.
Last updated
Was this helpful?