Trading
Canonical request/response for every trading endpoint.
All trading transactions are built unsigned and submit to the v2 RPC. Quote builders carry the transaction under transactionBase64 (null in preview-only mode); simple builders return { "transactionBase64": "…" }. Compute failures come back 200 with { "err": "…" }. Shared conventions: Conventions.
POST
/transaction-builder/open-position
POST
/transaction-builder/close-position
POST
/transaction-builder/increase-position · /decrease-position
POST
/transaction-builder/reverse-position
POST
/transaction-builder/add-collateral · /remove-collateral
POST
/transaction-builder/place-trigger-order · /place-tp-sl · /edit-trigger-order · /cancel-trigger-order · /cancel-all-trigger-orders
POST
/transaction-builder/edit-limit-order · /cancel-limit-order
Open position
POST /transaction-builder/open-position
Opens a new position or increases an existing one. Supports market and limit orders and optional TP/SL. Omit owner for a preview-only quote.
inputTokenSymbol
string
✓
Collateral token (e.g. USDC, SOL)
outputTokenSymbol
string
✓
Market token (e.g. SOL, BTC)
inputAmountUi
string
✓
Input amount, UI units
leverage
number
✓
Leverage multiplier
tradeType
enum
✓
LONG or SHORT
orderType
enum
—
MARKET (default) or LIMIT
limitPrice
string
—
Trigger price for LIMIT (UI)
owner
string
—
Wallet pubkey. Omit for preview only
slippagePercentage
string
—
Default "0.5"
takeProfit
string
—
TP trigger price (UI); appends a TP order
stopLoss
string
—
SL trigger price (UI); appends an SL order
Response — OpenPositionResponseDto
newLeverage, newEntryPrice, newLiquidationPrice
Position after this trade
entryFee, entryFeeBeforeDiscount, discountPercentage
Entry-fee breakdown
youPayUsdUi, youRecieveUsdUi, outputAmountUi
Collateral in / size out
availableLiquidity
Market liquidity, USD
takeProfitQuote, stopLossQuote
Present when TP/SL supplied
oldLeverage, oldEntryPrice, oldLiquidationPrice
Present when increasing
transactionBase64
Unsigned tx (null in preview-only mode)
err
Set when the computation failed
Close position
POST /transaction-builder/close-position
Closes a position fully or partially, identified by (owner, marketSymbol, side).
marketSymbol
string
✓
Market token symbol
side
enum
✓
LONG or SHORT
inputUsdUi
string
✓
USD to close (full size = full close)
closeAll
boolean
—
Force full close regardless of inputUsdUi
withdrawTokenSymbol
string
✓
Token to withdraw into (display hint)
owner
string
✓
Owner wallet pubkey
slippagePercentage
string
—
Default "0.5"
Response — ClosePositionResponseDto: receiveTokenSymbol, receiveTokenAmountUi, receiveTokenAmountUsdUi, markPrice, settledPnl, fees, newLiquidationPrice, newSize, newLeverage, transactionBase64.
Increase / Decrease position
POST /transaction-builder/increase-position · POST /transaction-builder/decrease-position
Add or remove size on an open position. For a full exit use close-position.
marketSymbol, side, owner
✓
✓
Identify the position
sizeAmountUi
✓
✓
Size delta, target token (UI)
collateralAmountUi
✓
—
Collateral to add (may be "0")
collateralTokenSymbol
—
—
Increase only; defaults to collateral custody
withdrawTokenSymbol
—
—
Decrease only; defaults to collateral custody
slippagePercentage
—
—
Default "0.5"
Response: { "transactionBase64": "…" }.
Reverse position
POST /transaction-builder/reverse-position
Atomically closes the current side and opens the opposite side at the given leverage. A 2% haircut on close proceeds absorbs price drift.
marketSymbol
string
✓
Market token symbol
side
enum
✓
Current side; new position is the opposite
leverage
number
✓
Leverage for the new position
owner
string
✓
Owner wallet pubkey
slippagePercentage
string
—
Default "0.5"
Response — ReversePositionResponseDto: closeReceiveUsd, closeFees, closeSettledPnl, newSide, newLeverage, newEntryPrice, newLiquidationPrice, newSizeUsd, newSizeAmountUi, newCollateralUsd, openEntryFee, transactionBase64.
Collateral
POST /transaction-builder/add-collateral · POST /transaction-builder/remove-collateral
Adjust margin on an open position to move its leverage and liquidation price.
marketSymbol, side, owner
✓
✓
Identify the position
depositAmountUi + depositTokenSymbol
✓
—
Amount to add
withdrawAmountUsdUi + withdrawTokenSymbol
—
✓
USD to remove
Response — AddCollateralResponseDto / RemoveCollateralResponseDto: existingCollateralUsd, newCollateralUsd, existingLeverage, newLeverage, existingLiquidationPrice, newLiquidationPrice, transactionBase64. Add also returns depositUsdValue / maxAddableUsd; remove returns receiveAmountUi / receiveAmountUsdUi / maxWithdrawableUsd.
Trigger orders
Return { "transactionBase64": "…" } on success, 400 { "error": "…" } on validation failure. Up to 5 TP + 5 SL per market + side. Task walkthrough: Take-profit & stop-loss.
Place trigger order
POST /transaction-builder/place-trigger-order
marketSymbol, side, owner
✓
Position identity
triggerPriceUi
string
✓
Trigger price (UI)
sizeAmountUi
string
✓
Size to close when triggered (UI)
isStopLoss
boolean
✓
true = SL, false = TP
Place TP/SL (atomic)
POST /transaction-builder/place-tp-sl — marketSymbol, side, owner, sizeAmountUi, plus takeProfitUi and/or stopLossUi (each optional; supply one or both).
Edit trigger order
POST /transaction-builder/edit-trigger-order — replaces both price and size (no keep-existing). Fields: marketSymbol, side, owner, orderId (0–4), isStopLoss, triggerPriceUi, sizeAmountUi.
Cancel trigger order(s)
POST /transaction-builder/cancel-trigger-order — marketSymbol, side, owner, orderId (0–4; or 255 for all), isStopLoss.
POST /transaction-builder/cancel-all-trigger-orders — marketSymbol, side, owner.
Limit orders
Placing a limit order goes through open-position with orderType: "LIMIT". The endpoints below edit and cancel. Up to 5 limit orders per market + side. Task walkthrough: Limit orders.
Edit limit order
POST /transaction-builder/edit-limit-order
For limitPriceUi / sizeAmountUi, omit (or "0") to keep existing. TP/SL do not persist — re-send to keep, "0"/omit removes.
marketSymbol, side, owner
✓
Position identity
orderId
number
✓
Slot index (0–4)
limitPriceUi
string
—
New price (UI). Omit to keep
sizeAmountUi
string
—
New size (UI). Omit to keep
takeProfitUi
string
—
Set TP; "0"/omit removes
stopLossUi
string
—
Set SL; "0"/omit removes
Cancel limit order
POST /transaction-builder/cancel-limit-order — marketSymbol, side, owner, orderId (0–4). Returns reserved collateral and frees the slot.
Last updated
Was this helpful?