> For the complete documentation index, see [llms.txt](https://docs.flash.trade/flash-trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.trade/flash-trade/flash-trade-v1-deprecated/flash-trade-api/flash-trade-v1/transaction-builder.md). # Transaction Builder Transaction builder endpoints do two things: 1. **Preview** — Calculate fees, leverage, liquidation price, and other outputs before committing. 2. **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-position ``` **Request body:** json ```json { "inputTokenSymbol": "USDC", "outputTokenSymbol": "SOL", "inputAmountUi": "100.0", "leverage": 5.0, "tradeType": "LONG", "owner": "YOUR_WALLET_PUBKEY" } ``` | Field | Type | Required | Description | | --------------------------- | ------- | -------- | ---------------------------------------------------------------------- | | `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 ```bash curl -X POST https://flashapi.trade/transaction-builder/open-position \ -H "Content-Type: application/json" \ -d '{ "inputTokenSymbol": "USDC", "outputTokenSymbol": "SOL", "inputAmountUi": "100.0", "leverage": 5.0, "tradeType": "LONG" }' ``` **With transaction + TP/SL:** bash ```bash curl -X POST https://flashapi.trade/transaction-builder/open-position \ -H "Content-Type: application/json" \ -d '{ "inputTokenSymbol": "USDC", "outputTokenSymbol": "SOL", "inputAmountUi": "100.0", "leverage": 5.0, "tradeType": "LONG", "owner": "YOUR_WALLET_PUBKEY", "takeProfit": "160.00", "stopLoss": "130.00" }' ``` **Response:** json ```json { "oldLeverage": null, "newLeverage": "5.00", "oldEntryPrice": null, "newEntryPrice": "148.52", "oldLiquidationPrice": null, "newLiquidationPrice": "120.30", "entryFee": "0.45", "entryFeeBeforeDiscount": "0.50", "openPositionFeePercent": "0.03600", "availableLiquidity": "1234567.89", "youPayUsdUi": "100.00", "youRecieveUsdUi": "500.00", "marginFeePercentage": "0.00800", "outputAmount": "3370000000", "outputAmountUi": "3.37", "transactionBase64": "AQAAAA...", "takeProfitQuote": { "exitPriceUi": "160.00", "profitUsdUi": "38.75", "lossUsdUi": "0", "exitFeeUsdUi": "0.45", "receiveUsdUi": "138.30", "pnlPercentage": "38.75" }, "stopLossQuote": { "exitPriceUi": "130.00", "profitUsdUi": "0", "lossUsdUi": "62.33", "exitFeeUsdUi": "0.40", "receiveUsdUi": "37.27", "pnlPercentage": "-62.33" }, "err": null } ``` | Field | Description | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `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. ``` POST /transaction-builder/close-position ``` **Request body:** json ```json { "positionKey": "POSITION_ACCOUNT_PUBKEY", "inputUsdUi": "500.00", "withdrawTokenSymbol": "USDC" } ``` | Field | Type | Required | Description | | --------------------------- | ------- | -------- | ------------------------------------------------------------- | | `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 ```json { "receiveTokenSymbol": "USDC", "receiveTokenAmountUi": "105.23", "receiveTokenAmountUsdUi": "105.23", "markPrice": "148.52", "entryPrice": "145.00", "existingLiquidationPrice": "120.30", "newLiquidationPrice": "0.00", "existingSize": "500.00", "newSize": "0.00", "existingCollateral": "100.00", "newCollateral": "0.00", "existingLeverage": "5.00", "newLeverage": "0.00", "settledPnl": "5.23", "fees": "0.36", "feesBeforeDiscount": "0.40", "lockAndUnsettledFeeUsd": null, "transactionBase64": "AQAAAA...", "err": null } ``` | Field | Description | | -------------------------- | ------------------------------------------------------------------ | | `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. ``` POST /transaction-builder/add-collateral ``` **Request body:** json ```json { "positionKey": "POSITION_ACCOUNT_PUBKEY", "depositAmountUi": "50.0", "depositTokenSymbol": "USDC", "owner": "YOUR_WALLET_PUBKEY" } ``` | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------ | | `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 ```json { "existingCollateralUsd": "100.00", "newCollateralUsd": "150.00", "existingLeverage": "5.00", "newLeverage": "3.33", "existingLiquidationPrice": "120.30", "newLiquidationPrice": "105.00", "depositUsdValue": "50.00", "maxAddableUsd": "10000.00", "transactionBase64": "AQAAAA...", "err": null } ``` *** ### Remove Collateral Withdraw collateral from a position. Increases leverage and moves the liquidation price closer. ``` POST /transaction-builder/remove-collateral ``` **Request body:** json ```json { "positionKey": "POSITION_ACCOUNT_PUBKEY", "withdrawAmountUsdUi": "25.00", "withdrawTokenSymbol": "USDC", "owner": "YOUR_WALLET_PUBKEY" } ``` | Field | Type | Required | Description | | --------------------- | ------ | -------- | ----------------------- | | `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 ```json { "existingCollateralUsd": "100.00", "newCollateralUsd": "75.00", "existingLeverage": "5.00", "newLeverage": "6.67", "existingLiquidationPrice": "120.30", "newLiquidationPrice": "130.00", "receiveAmountUi": "25.00", "receiveAmountUsdUi": "25.00", "maxWithdrawableUsd": "80.00", "transactionBase64": "AQAAAA...", "err": null } ``` *** ### 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. ``` POST /transaction-builder/reverse-position ``` **Request body:** json ```json { "positionKey": "POSITION_ACCOUNT_PUBKEY", "owner": "YOUR_WALLET_PUBKEY" } ``` | Field | Type | Required | Description | | --------------------------- | ------- | -------- | -------------------------------------- | | `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 ```json { "closeReceiveUsd": "105.23", "closeFees": "0.36", "closeSettledPnl": "5.23", "newSide": "Short", "newLeverage": "5.00", "newEntryPrice": "148.52", "newLiquidationPrice": "175.00", "newSizeUsd": "500.00", "newSizeAmountUi": "3.37", "newCollateralUsd": "98.00", "openEntryFee": "0.45", "transactionBase64": "AQAAAA...", "err": null } ``` {% hint style="info" %} **Note:** `newCollateralUsd` reflects a 2% haircut applied during the reversal. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flash.trade/flash-trade/flash-trade-v1-deprecated/flash-trade-api/flash-trade-v1/transaction-builder.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.