> 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-protocol/build-on-flash/flash-trade-v2/reference/trading.md).

# Trading

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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-v2/reference/conventions.md).

| Method | Path                                                                                                                                         |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `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.

| Field                | Type   | Req | Description                                |
| -------------------- | ------ | --- | ------------------------------------------ |
| `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`

| Field                                                      | Description                               |
| ---------------------------------------------------------- | ----------------------------------------- |
| `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           |

```bash
curl -X POST $FLASH_API_URL/transaction-builder/open-position -d '{
  "inputTokenSymbol": "USDC", "outputTokenSymbol": "SOL",
  "inputAmountUi": "100.0", "leverage": 5.0, "tradeType": "LONG",
  "owner": "bRXn4PPnUCLKP3kdHbX6FFQFpw2AhFzBVMgo4ZaWvtfb"
}'
```

***

## Close position

`POST /transaction-builder/close-position`

Closes a position fully or partially, identified by `(owner, marketSymbol, side)`.

| Field                 | Type    | Req | Description                                 |
| --------------------- | ------- | --- | ------------------------------------------- |
| `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 <a href="#increase-decrease-position" id="increase-decrease-position"></a>

`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`.

| Field                           | increase | decrease | Description                                   |
| ------------------------------- | :------: | :------: | --------------------------------------------- |
| `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.

| Field                | Type   | Req | Description                                    |
| -------------------- | ------ | --- | ---------------------------------------------- |
| `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.

| Field                                         | add | remove | Description           |
| --------------------------------------------- | :-: | :----: | --------------------- |
| `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](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-v2/guides/take-profit-and-stop-loss.md).

### Place trigger order

`POST /transaction-builder/place-trigger-order`

| Field                           | Type    | Req | Description                       |
| ------------------------------- | ------- | --- | --------------------------------- |
| `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](#open-position) with `orderType: "LIMIT"`. The endpoints below edit and cancel. Up to 5 limit orders per market + side. Task walkthrough: [Limit orders](/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-v2/guides/limit-orders.md).

### 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.

| Field                           | Type   | Req | Description                  |
| ------------------------------- | ------ | --- | ---------------------------- |
| `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.


---

# 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-protocol/build-on-flash/flash-trade-v2/reference/trading.md?ask=<question>&goal=<endgoal>
```

`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.