> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/bot-api/futures-grid.md).

# Futures Grid

Futures Grid Bot management (private)

## Get futures grid order

> Query a futures grid bot order by ID. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridOrder":{"type":"object","properties":{"keyId":{"type":"string","description":"API Key ID"},"userId":{"type":"string","description":"User ID"},"exchange":{"type":"string","description":"Exchange identifier"},"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"status":{"type":"string","description":"Order status"},"createTime":{"type":"number","description":"Creation timestamp in milliseconds"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"groupId":{"type":"string","description":"Bound group ID"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID"},"note":{"type":"string","description":"Note"},"customizeName":{"type":"string","description":"Custom name"},"buOrderData":{"$ref":"#/components/schemas/FuturesGridOrderData"}}},"FuturesGridOrderData":{"type":"object","properties":{"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `condition_lock`, `open_position`, `init_grid`,\n`running`, `destroy_grid`, `close_position`, `unlock_currency`, `canceled`,\n`adjust_params`, `adjust_params_open_position`, `adjust_params_init_grid`,\n`pre_pause`, `pausing`, `paused`, `pre_resume`, `resuming`\n","enum":["prepare","lock_currency","condition_lock","open_position","init_grid","running","destroy_grid","close_position","unlock_currency","canceled","adjust_params","adjust_params_open_position","adjust_params_init_grid","pre_pause","pausing","paused","pre_resume","resuming"]},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel` - User cancelled,\n`force_liquidation` - Liquidated,\n`loss_stop` - Stop loss triggered,\n`profit_stop` - Take profit triggered,\n`not_enough_balance` - Insufficient balance during running,\n`not_enough_balance_when_lock` - Lock funds failed after order,\n`create_failed` - Order creation failed\n","enum":["user_cancel","force_liquidation","loss_stop","profit_stop","not_enough_balance","not_enough_balance_when_lock","create_failed"]},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Current price at creation"},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"type":{"type":"string","description":"Operation type (e.g. `invest_in` for adding investment)"},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Total investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"position":{"type":"string","description":"Current position size"},"positionOpenPrice":{"type":"string","description":"Position open price"},"marginBalance":{"type":"string","description":"Margin balance (after leverage)"},"extraBalance":{"type":"string","description":"Extra balance"},"liquidationTriggered":{"type":"boolean","description":"Whether liquidation was triggered"},"liquidationPrice":{"type":"string","description":"Liquidation price"},"liquidationFee":{"type":"string","description":"Liquidation fee"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated liquidation price (upward)"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated liquidation price (downward)"},"lossStopType":{"type":"string","description":"Stop loss type:\n`price` - By market price (default),\n`profit_amount` - By P&L amount,\n`profit_ratio` - By P&L ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value. Interpretation depends on lossStopType:\n`price` -> stop loss price,\n`profit_amount` -> stop loss amount,\n`profit_ratio` -> stop loss ratio\n"},"profitStopType":{"type":"string","description":"Take profit type:\n`price` - By price (default),\n`profit_amount` - By profit amount,\n`profit_ratio` - By profit ratio,\n`price_limit` - By limit price\n","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value. Interpretation depends on profitStopType:\n`price` -> take profit price,\n`profit_amount` -> profit amount,\n`profit_ratio` -> profit ratio\n"},"riskStatus":{"type":"string","description":"Risk status","enum":["TRADING","HOLDING","TAKEOVER","LIQUIDATION"],"default":"TRADING"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitWithdrawn":{"type":"string","description":"Total profit withdrawn"},"openQuotePrice":{"type":"string","description":"Average quote-to-USDT price for investment"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only,\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"quoteAmountBeforeSell":{"type":"string","description":"Quote amount before closing"},"quoteAmountSell":{"type":"string","description":"Quote amount sold on close"},"quoteSellPrice":{"type":"string","description":"Quote sell price on close"},"unlockUsdtAmount":{"type":"string","description":"USDT returned to main account (only when TO_USDT)"},"unlockQuoteAmount":{"type":"string","description":"Quote returned to main account"},"initQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"},"closedQuotePrice":{"type":"string","description":"Quote/USDT price at close"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"sharedProfit":{"type":"string","description":"Shared profit amount"},"marginStatus":{"type":"string","description":"Margin status: `NORMAL` or `INSUFFICIENT`","enum":["NORMAL","INSUFFICIENT"],"default":"NORMAL"},"investCoin":{"type":"string","description":"Investment currency. `USDT` or quote currency (e.g. BTC)"},"investmentFrom":{"type":"string","description":"Funding source:\n`USER` - User main account,\n`LOCK_ACTIVITY` - Lock activity pool,\n`FUTURE_GRID_BONUS` - Bonus pool\n","enum":["USER","LOCK_ACTIVITY","FUTURE_GRID_BONUS"]},"lockEndTime":{"type":"number","description":"Lock end time in milliseconds"},"profitWithdrawnU":{"type":"string","description":"Profit withdrawn (user portion)"},"profitWithdrawnC":{"type":"string","description":"Profit withdrawn (charity/bonus portion)"},"profitWithdrawnP":{"type":"string","description":"Profit withdrawn (Pionex/bonus fee portion)"},"usdtInvestment":{"type":"string","description":"USDT investment amount"},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"stopLossEnabled":{"type":"boolean","description":"Stop loss enabled while paused"},"stopProfitEnabled":{"type":"boolean","description":"Take profit enabled while paused"},"triggerPausePriceUp":{"type":"string","description":"Price trigger for pause (upward)"},"triggerPausePriceDown":{"type":"string","description":"Price trigger for pause (downward)"},"profitReduce":{"type":"string","description":"Grid profit from position reduction (accumulated)"},"closeOrderType":{"type":"string","description":"Close order type:\n`market` - Market price close,\n`limit` - Limit price close,\n`limit_high` - Neutral grid top limit close\n","enum":["market","limit","limit_high"]},"closedBaseAmount":{"type":"string","description":"Closed position amount"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"bonusBackUsdt":{"type":"string","description":"USDT recovered from bonus on close"},"bonusBackQuote":{"type":"string","description":"Quote recovered from bonus on close"},"notionalStatus":{"type":"string","description":"Notional status: `NORMAL` or `NOTIONAL_LIMIT`","enum":["NORMAL","NOTIONAL_LIMIT"],"default":"NORMAL"},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"},"bonusFeeRatio":{"type":"string","description":"Bonus fee ratio (e.g. \"0.2\" = 20%)"},"bonusFee":{"type":"string","description":"Bonus management fee recovered on close (in quote)"},"disableChangeTp":{"type":"boolean","description":"Whether modification of take profit is disabled"},"disableInvestInTrigger":{"type":"boolean","description":"Whether trigger investment is disabled"},"investInTriggers":{"type":"array","description":"Pending trigger investment list (max 1 item)","items":{"$ref":"#/components/schemas/InvestInTrigger"}},"investOutTriggers":{"type":"array","description":"Pending trigger reduction list (max 1 item)","items":{"$ref":"#/components/schemas/InvestOutTrigger"}},"autoExpiredTime":{"type":"number","description":"Auto-close timestamp in milliseconds (for bonus orders)"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type:\n`FUTURES_MOON` - Futures moon order,\n`FULLY_HEDGING` - Fully hedged order,\n`LOAN_GRID` - Loan grid,\n`LEVERAGE_GRID` - Leverage grid,\n`FUTURE_GRID_COIN_MARGINED` - Coin-margined futures grid\n","enum":["FUTURES_MOON","FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"profitExited":{"type":"string","description":"Exited profit"},"fundingFeePayment":{"type":"string","description":"Total funding fee paid (negative value)"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close (requires original order to enable follow close)"}}},"InvestInTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger investment price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"quoteInvestment":{"type":"string","description":"Trigger investment amount"},"extraMarginAmount":{"type":"string","description":"Trigger dynamic margin"},"addTime":{"type":"number","description":"Add time in milliseconds"},"investCoin":{"type":"string","description":"Investment currency (currently only supports quote)"}}},"InvestOutTrigger":{"type":"object","properties":{"condition":{"type":"string","description":"Trigger reduction price"},"conditionDirection":{"type":"string","description":"Direction: \"1\" (above current price), \"-1\" (below current price)","enum":["1","-1"]},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"addTime":{"type":"number","description":"Add time in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/order":{"get":{"tags":["Futures Grid"],"summary":"Get futures grid order","description":"Query a futures grid bot order by ID. Weight: 1.","operationId":"getFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"buOrderId","in":"query","required":true,"description":"Bot order ID","schema":{"type":"string"}},{"name":"lang","in":"query","description":"Language","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Create futures grid order

> Create a new futures grid bot order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CreateFuturesGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"copyFrom":{"type":"string","description":"Copy source order ID"},"copyType":{"type":"string","description":"Copy type"},"copyBotOrderId":{"type":"string","description":"Copy bot order ID. Set this to the `bu_order_id` of an existing copy trading pool's lead order to join that pool: the newly created futures grid order will be attached to the pool and copied by its followers. This is the only field that makes a new order join an existing copy trading pool, so it must be a valid lead order ID — an invalid or closed value will cause the request to fail."},"buOrderData":{"$ref":"#/components/schemas/CreateFuturesGridOrderData"}}},"CreateFuturesGridOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quoteInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"number","description":"Number of grid levels"},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"number","description":"Leverage multiplier"},"extraMargin":{"type":"string","description":"Extra margin amount"},"quoteInvestment":{"type":"string","description":"Investment amount"},"condition":{"type":"string","description":"Trigger price (for conditional orders)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"-1\" (price drops to) or \"1\" (price rises to)","enum":["-1","1"]},"lossStopType":{"type":"string","description":"Stop loss type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"lossStop":{"type":"string","description":"Stop loss value (interpretation depends on lossStopType)"},"lossStopDelay":{"type":"number","description":"Stop loss delay in seconds"},"profitStopType":{"type":"string","description":"Take profit type: `price` (default), `profit_amount`, `profit_ratio`, `price_limit`","enum":["price","profit_amount","profit_ratio","price_limit"]},"profitStop":{"type":"string","description":"Take profit value (interpretation depends on profitStopType)"},"profitStopDelay":{"type":"number","description":"Take profit delay in seconds"},"lossStopHigh":{"type":"string","description":"Upper stop loss price for neutral grid (above top)"},"shareRatio":{"type":"string","description":"Profit sharing ratio"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default), `FUTURE_GRID_BONUS`","enum":["USER","FUTURE_GRID_BONUS"]},"uiInvestCoin":{"type":"string","description":"Frontend-recorded investment currency type (stored only)"},"lossStopLimitPrice":{"type":"string","description":"Limit stop loss price (when lossStopType=price_limit)"},"lossStopLimitHighPrice":{"type":"string","description":"Upper limit stop loss price for neutral grid (when lossStopType=price_limit)"},"profitStopLimitPrice":{"type":"string","description":"Limit take profit price (when profitStopType=price_limit)"},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"bonusId":{"type":"string","description":"Bonus UUID (when investmentFrom=FUTURE_GRID_BONUS)"},"uiExtraData":{"type":"string","description":"Frontend extra data for coin-margined futures grid"},"movingIndicatorType":{"type":"string","description":"Moving indicator type (e.g. `sma`)"},"movingIndicatorInterval":{"type":"string","description":"Moving indicator interval (e.g. 1m, 15m, 30m, 1h, 4h, 12h)"},"movingIndicatorParam":{"type":"string","description":"Moving indicator parameters JSON (e.g. {\"length\":720})"},"movingTrailingUpParam":{"type":"string","description":"SMA trailing up trigger ratio (e.g. 0.05)"},"cateType":{"type":"string","description":"Category type","enum":["FULLY_HEDGING","LOAN_GRID","LEVERAGE_GRID","FUTURE_GRID_COIN_MARGINED"]},"movingTop":{"type":"string","description":"Moving grid upper limit"},"movingBottom":{"type":"string","description":"Moving grid lower limit"},"enableFollowClosed":{"type":"boolean","description":"Whether to follow close"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/create":{"post":{"tags":["Futures Grid"],"summary":"Create futures grid order","description":"Create a new futures grid bot order. Weight: 1.","operationId":"createFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFuturesGridRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"buOrderData":{"type":"object","description":"Bot order data"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid parameters

> Validate futures grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\
> \
> Pass a positive \`quote\_investment\` to receive full estimate fields.\
> The current market price is fetched automatically — \`open\_price\` is not required.\
> \
> \*\*Extra Margin Modes\*\* (controlled by \`extra\_margin\`):\
> \
> \| | \`extra\_margin=false\` (Manual) | \`extra\_margin=true\` (Auto-split) |\
> \|---|---|---|\
> \| \`quote\_investment\` meaning | Trading capital only | Total input (auto-split into trading capital + extra margin) |\
> \| \`extra\_margin\_amount\` | User-specified extra margin, on top of \`quote\_investment\` | Typically omitted; system auto-calculates |\
> \| \`estimate\_investment\` | = \`quote\_investment\` | < \`quote\_investment\` (trading capital portion) |\
> \| \`estimate\_extra\_margin\` | = \`extra\_margin\_amount\` | Auto-calculated (= \`quote\_investment\` − \`estimate\_investment\`) |\
> \| \`min/max\_investment\` | Range for trading capital (excl. extra margin) | Range for total input (incl. extra margin) |\
> \
> \*\*FailedWithData\*\*: For errors marked "Yes" below, the response includes a \`data\` field\
> even when \`result=false\`, containing \`min\_investment\`, \`max\_investment\`, and \`slippage\`\
> so the client can display the valid investment range.\
> \
> \*\*Validation error messages\*\* (returned in \`message\` when \`result\` is \`false\`):\
> \
> \| Message | Cause | Includes data |\
> \|---|---|---|\
> \| \`base should end with .PERP\` | \`base\` must end with \`.PERP\`, e.g. \`BTC.PERP\` | No |\
> \| \`invalid trend\` | \`trend\` must be \`long\`, \`short\`, or \`no\_trend\` | No |\
> \| \`invalid grid\_type\` | \`grid\_type\` must be \`arithmetic\` or \`geometric\` | No |\
> \| \`bottom must greater than 0\` | \`bottom\` must be a positive number | No |\
> \| \`top must greater than bottom\` | \`top\` must be strictly greater than \`bottom\` | No |\
> \| \`top must less or equal than max:{maxPrice}\` | \`top\` exceeds the symbol's maximum allowed price | No |\
> \| \`top not match quote precision\` | \`top\` has more decimal places than the symbol allows | No |\
> \| \`bottom not match quote precision\` | \`bottom\` has more decimal places than the symbol allows | No |\
> \| \`row must greater than 1\` | \`row\` must be >= 2 | No |\
> \| \`row must less than 501\` | \`row\` must be <= 500 | No |\
> \| \`invalid leverage\` | \`leverage\` is outside the symbol's allowed leverage range | No |\
> \| \`extra\_margin should greater than or equal 0\` | \`extra\_margin\_amount\` must be >= 0 | No |\
> \| \`invalid condition\_direction\` | \`condition\_direction\` must be \`""\`, \`"1"\`, or \`"-1"\` | No |\
> \| \`quote\_investment not match spending precision: max {N} decimal places\` | \`quote\_investment\` exceeds the allowed decimal precision | Yes |\
> \| \`extra\_margin\_amount not match spending precision: max {N} decimal places\` | \`extra\_margin\_amount\` exceeds the allowed decimal precision | Yes |\
> \| \`grid profit per volume less than 0\` | Grid range too narrow or \`row\` too large — profit per grid is negative | Yes |\
> \| \`less than min investment\` | \`quote\_investment\` is \`"0"\` or less than \`min\_investment\` | Yes |<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CheckFuturesGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency, must end with `.PERP`"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckFuturesGridParamsOrderData"}}},"CheckFuturesGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","trend","leverage","quote_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be greater than `bottom` and match the symbol's price precision."},"bottom":{"type":"string","description":"Grid lower price. Must be greater than 0 and match the symbol's price precision."},"row":{"type":"integer","description":"Number of grid levels (2–500)","minimum":2,"maximum":500},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"trend":{"type":"string","description":"Grid direction: `long`, `short`, or `no_trend` (neutral)","enum":["long","short","no_trend"]},"leverage":{"type":"integer","description":"Leverage multiplier (1 to symbol's maximum leverage)"},"extra_margin":{"type":"boolean","description":"Controls how the investment is split between trading capital and extra margin (a safety buffer against liquidation).\n\n- `false` (default) — **Manual mode**: `quote_investment` is used entirely as trading capital (position margin + order margin + fee). Extra margin must be specified separately via `extra_margin_amount`.\n- `true` — **Auto-split mode**: `quote_investment` represents the **total input**. The system automatically splits it into trading capital and extra margin reserve. A portion is allocated as extra margin to reduce liquidation risk.\n\nThis flag also affects `min_investment` / `max_investment`:\n- `false`: the range covers trading capital only (excluding extra margin).\n- `true`: the range covers the total input (including the auto-calculated extra margin).\n","default":false},"quote_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\n\n- When `extra_margin=false`: this is the **trading capital** only (extra margin is provided separately via `extra_margin_amount`).\n- When `extra_margin=true`: this is the **total input** — the system will auto-split it into trading capital (`estimate_investment`) and extra margin (`estimate_extra_margin`).\n\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\n"},"extra_margin_amount":{"type":"string","description":"Additional margin amount on top of `quote_investment`, used as a safety buffer against liquidation. Must be >= 0. Omit or pass empty string to use 0.\n\n- When `extra_margin=false`: this value is passed through as-is. It does **not** count toward `quote_investment` or the `min_investment`/`max_investment` range, but it improves the estimated liquidation price.\n- When `extra_margin=true`: typically not needed, as the system auto-calculates extra margin from `quote_investment`. If provided, it is added on top of the auto-calculated margin and also improves the estimated liquidation price.\n"},"condition":{"type":"string","description":"Trigger price. When set, the bot starts only after the price reaches this level."},"condition_direction":{"type":"string","description":"Trigger direction: `\"-1\"` price drops to trigger level, `\"1\"` price rises to trigger level","enum":["-1","1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridCheckParamsData":{"type":"object","description":"Futures grid parameter check result data.\n\n**When result=true**: All fields are populated with full estimate data.\nLiquidation price fields are cleared when `quote_investment` is outside [`min_investment`, `max_investment`].\n\n**When result=false with data (FailedWithData)**: Only `min_investment`, `max_investment`, and `slippage`\nare valid; all other estimate fields are empty. This occurs when `message` is one of:\n`\"quote_investment not match spending precision: max {N} decimal places\"`,\n`\"extra_margin_amount not match spending precision: max {N} decimal places\"`,\n`\"grid profit per volume less than 0\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum allowed `quote_investment`.\n- When `extra_margin=false`: minimum trading capital (excluding extra margin).\n- When `extra_margin=true`: minimum total input (including auto-calculated extra margin).\n"},"max_investment":{"type":"string","description":"Maximum allowed `quote_investment`.\n- When `extra_margin=false`: maximum trading capital (excluding extra margin).\n- When `extra_margin=true`: maximum total input (including auto-calculated extra margin).\n"},"slippage":{"type":"string","description":"Recommended opening slippage (e.g. `\"0.01\"` = 1%)"},"estimate_per_volume":{"type":"string","description":"Estimated per-grid buy/sell quantity."},"estimate_investment":{"type":"string","description":"Estimated amount allocated to trading capital (= position margin + order margin + fee). Does **not** include extra margin.\n- When `extra_margin=false`: equals `quote_investment` (all input goes to trading capital).\n- When `extra_margin=true`: less than `quote_investment` — the remainder goes to `estimate_extra_margin`.\n"},"estimate_extra_margin":{"type":"string","description":"Estimated extra margin — a safety buffer that reduces liquidation risk but is not used for grid trading itself.\n- When `extra_margin=false`: equals the input `extra_margin_amount` (pass-through).\n- When `extra_margin=true`: auto-calculated as `quote_investment - estimate_investment`.\n"},"estimate_fee":{"type":"string","description":"Estimated opening trading fee (included in `estimate_investment`)."},"estimate_position_occupy_margin":{"type":"string","description":"Estimated margin occupied by positions opened immediately at creation (included in `estimate_investment`)."},"estimate_order_occupy_margin":{"type":"string","description":"Estimated margin occupied by pending grid orders (included in `estimate_investment`)."},"estimate_position":{"type":"string","description":"Estimated position opened immediately at order creation. Positive = long, negative = short."},"estimate_liquidation_price_up":{"type":"string","description":"Estimated upper liquidation price. Returns `\"0\"` for long-only grids (no upper liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."},"estimate_liquidation_price_down":{"type":"string","description":"Estimated lower liquidation price. Returns `\"0\"` for short-only grids (no lower liquidation risk). Empty when `quote_investment` is out of [`min_investment`, `max_investment`]."}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/checkParams":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid parameters","description":"Validate futures grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\n\nPass a positive `quote_investment` to receive full estimate fields.\nThe current market price is fetched automatically — `open_price` is not required.\n\n**Extra Margin Modes** (controlled by `extra_margin`):\n\n| | `extra_margin=false` (Manual) | `extra_margin=true` (Auto-split) |\n|---|---|---|\n| `quote_investment` meaning | Trading capital only | Total input (auto-split into trading capital + extra margin) |\n| `extra_margin_amount` | User-specified extra margin, on top of `quote_investment` | Typically omitted; system auto-calculates |\n| `estimate_investment` | = `quote_investment` | < `quote_investment` (trading capital portion) |\n| `estimate_extra_margin` | = `extra_margin_amount` | Auto-calculated (= `quote_investment` − `estimate_investment`) |\n| `min/max_investment` | Range for trading capital (excl. extra margin) | Range for total input (incl. extra margin) |\n\n**FailedWithData**: For errors marked \"Yes\" below, the response includes a `data` field\neven when `result=false`, containing `min_investment`, `max_investment`, and `slippage`\nso the client can display the valid investment range.\n\n**Validation error messages** (returned in `message` when `result` is `false`):\n\n| Message | Cause | Includes data |\n|---|---|---|\n| `base should end with .PERP` | `base` must end with `.PERP`, e.g. `BTC.PERP` | No |\n| `invalid trend` | `trend` must be `long`, `short`, or `no_trend` | No |\n| `invalid grid_type` | `grid_type` must be `arithmetic` or `geometric` | No |\n| `bottom must greater than 0` | `bottom` must be a positive number | No |\n| `top must greater than bottom` | `top` must be strictly greater than `bottom` | No |\n| `top must less or equal than max:{maxPrice}` | `top` exceeds the symbol's maximum allowed price | No |\n| `top not match quote precision` | `top` has more decimal places than the symbol allows | No |\n| `bottom not match quote precision` | `bottom` has more decimal places than the symbol allows | No |\n| `row must greater than 1` | `row` must be >= 2 | No |\n| `row must less than 501` | `row` must be <= 500 | No |\n| `invalid leverage` | `leverage` is outside the symbol's allowed leverage range | No |\n| `extra_margin should greater than or equal 0` | `extra_margin_amount` must be >= 0 | No |\n| `invalid condition_direction` | `condition_direction` must be `\"\"`, `\"1\"`, or `\"-1\"` | No |\n| `quote_investment not match spending precision: max {N} decimal places` | `quote_investment` exceeds the allowed decimal precision | Yes |\n| `extra_margin_amount not match spending precision: max {N} decimal places` | `extra_margin_amount` exceeds the allowed decimal precision | Yes |\n| `grid profit per volume less than 0` | Grid range too narrow or `row` too large — profit per grid is negative | Yes |\n| `less than min investment` | `quote_investment` is `\"0\"` or less than `min_investment` | Yes |\n","operationId":"checkFuturesGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckFuturesGridParamsRequest"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridCheckParamsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Adjust futures grid (add investment / modify range)

> Add investment, modify grid range, or set trigger investment for a futures grid order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"AdjustFuturesGridRequest":{"type":"object","required":["buOrderId","type","extraMargin","openPrice"],"description":"Adjust a futures grid order. The fields controlling how the investment amount is\ntreated (`isReinvest`, `keepInvestment`, `quoteInvestment`, `adjustParamsSence`)\noverlap and interact — pick ONE intent from the table below and set exactly the\nlisted fields. Do not mix intents.\n\nInvestment-intent decision table (only relevant when `type=adjust_params`):\n\n| Intent                                             | Set these fields                                                        |\n|----------------------------------------------------|-------------------------------------------------------------------------|\n| Only change grid range/row, keep investment fixed  | `keepInvestment=true` (leave `isReinvest`/`quoteInvestment` unset)      |\n| Add funds to the order                             | `quoteInvestment=<amount>` (do NOT rely on `isReinvest`; see its note)  |\n| Reinvest current floating profit, add no new funds | `adjustParamsSence=\"reinvest\"`, `isReinvest=true`, `quoteInvestment=0`  |\n\nPrecedence & hidden rules (read before setting flags):\n- `keepInvestment=true` overrides `isReinvest` — when set, `isReinvest` is ignored.\n- Passing `quoteInvestment>0` is implicitly treated as reinvest, even if you send\n  `isReinvest=false`. To keep the investment untouched, use `keepInvestment=true`,\n  NOT `isReinvest=false`.\n- `isReinvest=false` (without `keepInvestment`) requires current floating PnL > 0;\n  otherwise the request is rejected with reason `PROFIT_LESS_THAN_ZERO`.\n- Always call `adjustParamsCheck` first with the same body to preview the outcome\n  and catch these constraints before executing.\n","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Adjustment type:\n`invest_in` - Add investment,\n`adjust_params` - Modify grid range,\n`invest_in_trigger` - Trigger investment\n","enum":["invest_in","adjust_params","invest_in_trigger"]},"quoteInvestment":{"type":"number","description":"When type=invest_in: additional investment amount (must be > 0).\nWhen type=adjust_params: amount of new funds to add to the investment.\nNOTE: any value > 0 is implicitly treated as reinvest (forces isReinvest=true\ninternally), so do not send quoteInvestment>0 together with keepInvestment=true.\nLeave 0/unset for the \"keep investment\" or \"reinvest profit only\" intents.\n"},"extraMargin":{"type":"boolean","description":"true: reserve extra margin, false: no extra margin"},"openPrice":{"type":"number","description":"Current price"},"bottom":{"type":"string","description":"New grid lower price (required when type=adjust_params)"},"top":{"type":"string","description":"New grid upper price (required when type=adjust_params)"},"row":{"type":"number","description":"New grid level count (required when type=adjust_params)"},"extraMarginAmount":{"type":"number","description":"Extra margin amount to add (when type=adjust_params)"},"isRecommend":{"type":"boolean","description":"Whether using recommended parameters (when type=adjust_params)"},"isReinvest":{"type":"boolean","description":"When type=adjust_params: whether to fold current floating profit into the\ninvestment base (default false). Interacts with other fields — see the\ndecision table and precedence rules on this schema before using:\n- Ignored when keepInvestment=true.\n- Implicitly forced true when quoteInvestment>0.\n- When left false without keepInvestment, requires current PnL > 0, else the\n  request is rejected with `PROFIT_LESS_THAN_ZERO`.\nFor the common \"keep investment unchanged\" intent, prefer keepInvestment=true\nover isReinvest=false.\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default) or `LOCK_ACTIVITY`","enum":["USER","LOCK_ACTIVITY"]},"condition":{"type":"string","description":"Trigger price (when type=invest_in_trigger)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]},"slippage":{"type":"string","description":"Slippage for add investment / modify range"},"adjustParamsSence":{"type":"string","description":"\"Reinvest profit only\" intent. Set to `reinvest` (only valid when\ntype=adjust_params) to keep params/funds unchanged and fold current floating\nprofit into the investment. When set to `reinvest`, you MUST also send\nisReinvest=true and quoteInvestment=0 / extraMarginAmount=0, otherwise the\nrequest is rejected. Leave empty for the other intents.\n","enum":["reinvest"]},"keepInvestment":{"type":"boolean","description":"\"Keep investment fixed\" intent (recommended for pure range/row edits).\nWhen `true` and type=adjust_params: only modify grid range/row without\nresetting the investment amount. Overrides isReinvest (isReinvest is ignored),\nskips the PnL check, but still validates the price range. Do not combine with\nquoteInvestment>0 or adjustParamsSence=reinvest.\nWhen `false` (default): investment base is recalculated after modification and\nthe PnL check applies.\n","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/adjustParams":{"post":{"tags":["Futures Grid"],"summary":"Adjust futures grid (add investment / modify range)","description":"Add investment, modify grid range, or set trigger investment for a futures grid order. Weight: 1.","operationId":"adjustFuturesGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustFuturesGridRequest"}}}},"responses":{"200":{"description":"Adjustment applied successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Reduce futures grid position

> Reduce position size of a futures grid order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ReduceFuturesGridRequest":{"type":"object","required":["buOrderId","openPrice","reduceNum"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"openPrice":{"type":"string","description":"Current price"},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"slippage":{"type":"string","description":"Reduction slippage"},"condition":{"type":"string","description":"Trigger reduction price (must be > 0)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ReduceFuturesGridResponse":{"type":"object","properties":{"checkResult":{"type":"boolean","description":"Check result"},"reason":{"type":"string","description":"Failure reason:\n`LOSS_GTE_INVESTMENT` - Total equity minus dynamic margin <= 0,\n`POSITION_TOO_SMALL` - Position too small to reduce,\n`REDUCE_TOO_MUCH` - reduceNum too large,\n`REDUCE_TOO_SMALL` - reduceNum too small,\n`SYMBOL_MAINTENANCE` - Symbol under maintenance\n","enum":["LOSS_GTE_INVESTMENT","POSITION_TOO_SMALL","REDUCE_TOO_MUCH","REDUCE_TOO_SMALL","SYMBOL_MAINTENANCE"]}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduce":{"post":{"tags":["Futures Grid"],"summary":"Reduce futures grid position","description":"Reduce position size of a futures grid order. Weight: 1.","operationId":"reduceFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReduceFuturesGridRequest"}}}},"responses":{"200":{"description":"Reduction result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReduceFuturesGridResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Cancel futures grid order

> Close and cancel a futures grid bot order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"CancelFuturesGridRequest":{"type":"object","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeNote":{"type":"string","description":"Close note"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Close position only (default),\n`TO_USDT` - Close position and sell quote to USDT\n","enum":["TO_QUOTE","TO_USDT"]},"immediate":{"type":"boolean","description":"Force-cancel an order that is stuck in the `close_position` state because its limit take-profit / stop-loss order has triggered but not yet filled. This is NOT a generic \"cancel faster\" flag.\n\n- `false` (default): normal cancellation. Use this for orders in any regular state (e.g. `running`). It runs the full close flow: update status, dispatch the close action, and settle.\n- `true`: special recovery path ONLY valid when the order is in the `close_position` state with an unfilled limit TP/SL order. It sends the close action directly with a market price. If the order is in any other state, the request is rejected with `Forbidden: invalid status`.\n\nDo not set `true` as a default \"force close\" option — for normal close-outs always use `false`."},"closeSlippage":{"type":"string","description":"Close position slippage (e.g. \"0.01\" = 1%)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/cancel":{"post":{"tags":["Futures Grid"],"summary":"Cancel futures grid order","description":"Close and cancel a futures grid bot order. Weight: 1.","operationId":"cancelFuturesGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelFuturesGridRequest"}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid adjust parameters (dry-run)

> Validate adjust params / invest-in parameters and return estimated data without executing.\
> Use this before calling adjustParams to preview the impact.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"AdjustFuturesGridRequest":{"type":"object","required":["buOrderId","type","extraMargin","openPrice"],"description":"Adjust a futures grid order. The fields controlling how the investment amount is\ntreated (`isReinvest`, `keepInvestment`, `quoteInvestment`, `adjustParamsSence`)\noverlap and interact — pick ONE intent from the table below and set exactly the\nlisted fields. Do not mix intents.\n\nInvestment-intent decision table (only relevant when `type=adjust_params`):\n\n| Intent                                             | Set these fields                                                        |\n|----------------------------------------------------|-------------------------------------------------------------------------|\n| Only change grid range/row, keep investment fixed  | `keepInvestment=true` (leave `isReinvest`/`quoteInvestment` unset)      |\n| Add funds to the order                             | `quoteInvestment=<amount>` (do NOT rely on `isReinvest`; see its note)  |\n| Reinvest current floating profit, add no new funds | `adjustParamsSence=\"reinvest\"`, `isReinvest=true`, `quoteInvestment=0`  |\n\nPrecedence & hidden rules (read before setting flags):\n- `keepInvestment=true` overrides `isReinvest` — when set, `isReinvest` is ignored.\n- Passing `quoteInvestment>0` is implicitly treated as reinvest, even if you send\n  `isReinvest=false`. To keep the investment untouched, use `keepInvestment=true`,\n  NOT `isReinvest=false`.\n- `isReinvest=false` (without `keepInvestment`) requires current floating PnL > 0;\n  otherwise the request is rejected with reason `PROFIT_LESS_THAN_ZERO`.\n- Always call `adjustParamsCheck` first with the same body to preview the outcome\n  and catch these constraints before executing.\n","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Adjustment type:\n`invest_in` - Add investment,\n`adjust_params` - Modify grid range,\n`invest_in_trigger` - Trigger investment\n","enum":["invest_in","adjust_params","invest_in_trigger"]},"quoteInvestment":{"type":"number","description":"When type=invest_in: additional investment amount (must be > 0).\nWhen type=adjust_params: amount of new funds to add to the investment.\nNOTE: any value > 0 is implicitly treated as reinvest (forces isReinvest=true\ninternally), so do not send quoteInvestment>0 together with keepInvestment=true.\nLeave 0/unset for the \"keep investment\" or \"reinvest profit only\" intents.\n"},"extraMargin":{"type":"boolean","description":"true: reserve extra margin, false: no extra margin"},"openPrice":{"type":"number","description":"Current price"},"bottom":{"type":"string","description":"New grid lower price (required when type=adjust_params)"},"top":{"type":"string","description":"New grid upper price (required when type=adjust_params)"},"row":{"type":"number","description":"New grid level count (required when type=adjust_params)"},"extraMarginAmount":{"type":"number","description":"Extra margin amount to add (when type=adjust_params)"},"isRecommend":{"type":"boolean","description":"Whether using recommended parameters (when type=adjust_params)"},"isReinvest":{"type":"boolean","description":"When type=adjust_params: whether to fold current floating profit into the\ninvestment base (default false). Interacts with other fields — see the\ndecision table and precedence rules on this schema before using:\n- Ignored when keepInvestment=true.\n- Implicitly forced true when quoteInvestment>0.\n- When left false without keepInvestment, requires current PnL > 0, else the\n  request is rejected with `PROFIT_LESS_THAN_ZERO`.\nFor the common \"keep investment unchanged\" intent, prefer keepInvestment=true\nover isReinvest=false.\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency (default)"},"investmentFrom":{"type":"string","description":"Funding source: `USER` (default) or `LOCK_ACTIVITY`","enum":["USER","LOCK_ACTIVITY"]},"condition":{"type":"string","description":"Trigger price (when type=invest_in_trigger)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]},"slippage":{"type":"string","description":"Slippage for add investment / modify range"},"adjustParamsSence":{"type":"string","description":"\"Reinvest profit only\" intent. Set to `reinvest` (only valid when\ntype=adjust_params) to keep params/funds unchanged and fold current floating\nprofit into the investment. When set to `reinvest`, you MUST also send\nisReinvest=true and quoteInvestment=0 / extraMarginAmount=0, otherwise the\nrequest is rejected. Leave empty for the other intents.\n","enum":["reinvest"]},"keepInvestment":{"type":"boolean","description":"\"Keep investment fixed\" intent (recommended for pure range/row edits).\nWhen `true` and type=adjust_params: only modify grid range/row without\nresetting the investment amount. Overrides isReinvest (isReinvest is ignored),\nskips the PnL check, but still validates the price range. Do not combine with\nquoteInvestment>0 or adjustParamsSence=reinvest.\nWhen `false` (default): investment base is recalculated after modification and\nthe PnL check applies.\n","default":false}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"AdjustParamsCheckResponse":{"type":"object","description":"Adjust params check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the adjustment is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"estimateInvestment":{"type":"string","description":"Estimated investment amount after adjustment"},"estimateExtraMargin":{"type":"string","description":"Estimated extra margin after adjustment"},"minInvestment":{"type":"string","description":"Minimum required investment"},"maxInvestment":{"type":"string","description":"Maximum allowed investment"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after adjustment"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after adjustment"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"estimatePerVolume":{"type":"string","description":"Estimated per-grid volume after adjustment"},"slippage":{"type":"string","description":"Recommended slippage"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/adjustParamsCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid adjust parameters (dry-run)","description":"Validate adjust params / invest-in parameters and return estimated data without executing.\nUse this before calling adjustParams to preview the impact.\nWeight: 1.\n","operationId":"adjustFuturesGridParamsCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustFuturesGridRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code, reason message, and partial estimate data.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdjustParamsCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid reduce (dry-run)

> Validate reduce parameters and return estimated data without executing.\
> Use this before calling reduce to preview the impact.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"ReduceFuturesGridRequest":{"type":"object","required":["buOrderId","openPrice","reduceNum"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"openPrice":{"type":"string","description":"Current price"},"reduceNum":{"type":"number","description":"Reduction amount: order precision * reduceNum"},"slippage":{"type":"string","description":"Reduction slippage"},"condition":{"type":"string","description":"Trigger reduction price (must be > 0)"},"conditionDirection":{"type":"string","description":"Trigger direction: \"1\" (above current) or \"-1\" (below current)","enum":["1","-1"]}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"ReduceCheckResponse":{"type":"object","description":"Reduce check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the reduction is feasible"},"reason":{"type":"string","description":"Failure reason when checkResult is false"},"maxReduceNum":{"type":"integer","description":"Maximum reduce number allowed"},"reduceAmount":{"type":"string","description":"Estimated total reduction amount"},"reduceInvestment":{"type":"string","description":"Estimated investment to be returned"},"reduceGridprofit":{"type":"string","description":"Estimated grid profit to be returned"},"reducePnl":{"type":"string","description":"Estimated PnL from reduction"},"reduceFee":{"type":"string","description":"Estimated fee for reduction"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Upward liquidation price after reduction"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Downward liquidation price after reduction"},"estimateDeltaPosition":{"type":"string","description":"Estimated position change"},"estimateDeltaProfit":{"type":"string","description":"Estimated profit/loss from position change"},"slippage":{"type":"string","description":"Recommended slippage"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid reduce (dry-run)","description":"Validate reduce parameters and return estimated data without executing.\nUse this before calling reduce to preview the impact.\nWeight: 1.\n","operationId":"reduceFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReduceFuturesGridRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code, reason message, and partial estimate data.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ReduceCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid pause (dry-run)

> Validate whether a futures grid order can be paused (\`immediate\` or \`conditional\` mode)\
> and return current plus post-trigger estimated liquidation prices without executing.\
> Does not accept \`openPrice\`; the backend uses the live market price.\
> \`triggerPausePriceUp\` / \`triggerPausePriceDown\` are independent — set either or both.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridPauseCheckRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now; `conditional` = pause on trigger price"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price (when mode=conditional). Optional; set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price (when mode=conditional). Optional."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridPauseCheckResponse":{"type":"object","description":"Pause check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be paused"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_RUNNING)"},"estimateLiquidationPriceUp":{"type":"string","description":"Current upward liquidation price"},"estimateLiquidationPriceDown":{"type":"string","description":"Current downward liquidation price"},"estimateLiquidationPriceUpAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — upward liquidation price after the upward pause triggers"},"estimateLiquidationPriceDownAfterTriggerUp":{"type":"string","description":"Returned when triggerPausePriceUp is set — downward liquidation price after the upward pause triggers"},"estimateLiquidationPriceUpAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — upward liquidation price after the downward pause triggers"},"estimateLiquidationPriceDownAfterTriggerDown":{"type":"string","description":"Returned when triggerPausePriceDown is set — downward liquidation price after the downward pause triggers"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/pauseCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid pause (dry-run)","description":"Validate whether a futures grid order can be paused (`immediate` or `conditional` mode)\nand return current plus post-trigger estimated liquidation prices without executing.\nDoes not accept `openPrice`; the backend uses the live market price.\n`triggerPausePriceUp` / `triggerPausePriceDown` are independent — set either or both.\nWeight: 1.\n","operationId":"pauseFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridPauseCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridPauseCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Pause futures grid order

> Pause a running futures grid order. Runs the same validation as \`pauseCheck\`, then\
> executes asynchronously. Once paused the grid stops auto-refilling orders while the\
> position is retained; \`immediate\` mode takes effect at the live market price.\
> Does not return a \`status\` field (async processing).\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridPauseRequest":{"type":"object","required":["buOrderId","mode"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"mode":{"type":"string","enum":["immediate","conditional"],"description":"Pause mode: `immediate` = pause now (backend uses live market price, not client-supplied); `conditional` = pause on trigger price"},"stopProfitEnabled":{"type":"boolean","description":"Whether to keep take-profit active while paused"},"stopLossEnabled":{"type":"boolean","description":"Whether to keep stop-loss active while paused"},"triggerPausePriceUp":{"type":"string","description":"Upward trigger price. Set either direction or both."},"triggerPausePriceDown":{"type":"string","description":"Downward trigger price."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridPauseResponse":{"type":"object","description":"Pause execution result (no status field; processed asynchronously)","properties":{"stopLossEnabled":{"type":"boolean","description":"Effective stop-loss retention state"},"stopProfitEnabled":{"type":"boolean","description":"Effective take-profit retention state"},"triggerPausePriceUp":{"type":"string","description":"Effective upward trigger price"},"triggerPausePriceDown":{"type":"string","description":"Effective downward trigger price"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/pause":{"post":{"tags":["Futures Grid"],"summary":"Pause futures grid order","description":"Pause a running futures grid order. Runs the same validation as `pauseCheck`, then\nexecutes asynchronously. Once paused the grid stops auto-refilling orders while the\nposition is retained; `immediate` mode takes effect at the live market price.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"pauseFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridPauseRequest"}}}},"responses":{"200":{"description":"Pause accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridPauseResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid resume (dry-run)

> Validate whether a paused futures grid order can be resumed and return the estimated\
> liquidation prices after resuming, without executing. Order must be in \`paused\` state.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridResumeRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridResumeCheckResponse":{"type":"object","description":"Resume check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the order can be resumed"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / ORDER_NOT_PAUSED)"},"estimateLiquidationPriceUp":{"type":"string","description":"Estimated upward liquidation price after resuming"},"estimateLiquidationPriceDown":{"type":"string","description":"Estimated downward liquidation price after resuming"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/resumeCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid resume (dry-run)","description":"Validate whether a paused futures grid order can be resumed and return the estimated\nliquidation prices after resuming, without executing. Order must be in `paused` state.\nWeight: 1.\n","operationId":"resumeFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridResumeRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridResumeCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Resume futures grid order

> Resume a paused futures grid order. Runs the same validation as \`resumeCheck\`, then\
> executes. After resuming the grid restarts auto-refilling and the liquidation price\
> moves with the market.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridResumeRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridResumeResponse":{"type":"object","description":"Resume execution result","properties":{"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/resume":{"post":{"tags":["Futures Grid"],"summary":"Resume futures grid order","description":"Resume a paused futures grid order. Runs the same validation as `resumeCheck`, then\nexecutes. After resuming the grid restarts auto-refilling and the liquidation price\nmoves with the market.\nWeight: 1.\n","operationId":"resumeFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridResumeRequest"}}}},"responses":{"200":{"description":"Resume accepted.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridResumeResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid add margin (dry-run)

> Validate whether the add-margin amount is valid and return the estimated liquidation\
> prices before and after the change, without executing.\
> Does not accept \`openPrice\`; the backend uses the live market price.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginCheckRequest":{"type":"object","required":["buOrderId","amount"],"description":"Shared by addMarginCheck and reduceMarginCheck; the direction is determined by the route, not a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal, serialized as an unquoted number)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginCheckResponse":{"type":"object","description":"Add/reduce margin check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the amount is valid"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / EXCEEDS_MAX_AMOUNT)"},"estimateLiquidationPriceUpBefore":{"type":"string","description":"Estimated upward liquidation price before the change"},"estimateLiquidationPriceDownBefore":{"type":"string","description":"Estimated downward liquidation price before the change"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after the change"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after the change"},"maxAmount":{"type":"string","description":"Returned by reduceMarginCheck only — max reducible margin = min(existing extra margin, total equity − 1.05× used margin, margin account balance)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/addMarginCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid add margin (dry-run)","description":"Validate whether the add-margin amount is valid and return the estimated liquidation\nprices before and after the change, without executing.\nDoes not accept `openPrice`; the backend uses the live market price.\nWeight: 1.\n","operationId":"addMarginFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Add margin to futures grid order

> Transfer margin into a futures grid order. Runs the same validation as \`addMarginCheck\`,\
> then executes asynchronously. Directly affects available balance and the order's\
> liquidation price — a funds operation, call with care.\
> Does not return a \`status\` field (async processing).\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginTransferRequest":{"type":"object","required":["buOrderId","coin","amount"],"description":"Shared by addMargin and reduceMargin; the direction (in/out) is fixed server-side by the route and not exposed as a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginTransferResponse":{"type":"object","description":"Add/reduce margin execution result (no status field; processed asynchronously)","properties":{"transferId":{"type":"string","description":"Transfer record ID"},"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/addMargin":{"post":{"tags":["Futures Grid"],"summary":"Add margin to futures grid order","description":"Transfer margin into a futures grid order. Runs the same validation as `addMarginCheck`,\nthen executes asynchronously. Directly affects available balance and the order's\nliquidation price — a funds operation, call with care.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"addMarginFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginTransferRequest"}}}},"responses":{"200":{"description":"Add margin accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginTransferResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check futures grid reduce margin (dry-run)

> Validate whether the reduce-margin amount is valid (subject to the \`maxAmount\` hard limit)\
> and return the estimated liquidation prices before and after the change, without executing.\
> Exceeding \`maxAmount\` returns \`checkResult=false\` with reason \`EXCEEDS\_MAX\_AMOUNT\`.\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginCheckRequest":{"type":"object","required":["buOrderId","amount"],"description":"Shared by addMarginCheck and reduceMarginCheck; the direction is determined by the route, not a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal, serialized as an unquoted number)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginCheckResponse":{"type":"object","description":"Add/reduce margin check result with estimate data","properties":{"checkResult":{"type":"boolean","description":"Whether the amount is valid"},"reason":{"type":"string","description":"Failure reason when checkResult is false (fixed constant, e.g. FORBIDDEN_COPY_BOT_SUBORDER / FORBIDDEN_FULLY_HEDGING / EXCEEDS_MAX_AMOUNT)"},"estimateLiquidationPriceUpBefore":{"type":"string","description":"Estimated upward liquidation price before the change"},"estimateLiquidationPriceDownBefore":{"type":"string","description":"Estimated downward liquidation price before the change"},"estimateLiquidationPriceUpAfter":{"type":"string","description":"Estimated upward liquidation price after the change"},"estimateLiquidationPriceDownAfter":{"type":"string","description":"Estimated downward liquidation price after the change"},"maxAmount":{"type":"string","description":"Returned by reduceMarginCheck only — max reducible margin = min(existing extra margin, total equity − 1.05× used margin, margin account balance)"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceMarginCheck":{"post":{"tags":["Futures Grid"],"summary":"Check futures grid reduce margin (dry-run)","description":"Validate whether the reduce-margin amount is valid (subject to the `maxAmount` hard limit)\nand return the estimated liquidation prices before and after the change, without executing.\nExceeding `maxAmount` returns `checkResult=false` with reason `EXCEEDS_MAX_AMOUNT`.\nWeight: 1.\n","operationId":"reduceMarginFuturesGridCheck","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginCheckRequest"}}}},"responses":{"200":{"description":"Check result. On success: `result=true` with estimate data.\nOn business validation failure: `result=false` with `BOT_INVALID_ARGUMENT` code and reason message.\n","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginCheckResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Reduce margin of futures grid order

> Transfer margin out of a futures grid order. Runs the same validation as\
> \`reduceMarginCheck\` (including the \`maxAmount\` check), then executes asynchronously.\
> Directly reduces the order's available margin and raises liquidation risk — a funds\
> operation, call with care.\
> Does not return a \`status\` field (async processing).\
> Weight: 1.<br>

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridMarginTransferRequest":{"type":"object","required":["buOrderId","coin","amount"],"description":"Shared by addMargin and reduceMargin; the direction (in/out) is fixed server-side by the route and not exposed as a request field.","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"number","description":"Margin amount to add / reduce (decimal)"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridMarginTransferResponse":{"type":"object","description":"Add/reduce margin execution result (no status field; processed asynchronously)","properties":{"transferId":{"type":"string","description":"Transfer record ID"},"code":{"type":"integer","format":"int32","description":"RPC return code"},"message":{"type":"string","description":"RPC return message"}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/reduceMargin":{"post":{"tags":["Futures Grid"],"summary":"Reduce margin of futures grid order","description":"Transfer margin out of a futures grid order. Runs the same validation as\n`reduceMarginCheck` (including the `maxAmount` check), then executes asynchronously.\nDirectly reduces the order's available margin and raises liquidation risk — a funds\noperation, call with care.\nDoes not return a `status` field (async processing).\nWeight: 1.\n","operationId":"reduceMarginFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridMarginTransferRequest"}}}},"responses":{"200":{"description":"Reduce margin accepted (async).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridMarginTransferResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Set / update / clear take-profit & stop-loss

> Set, update, or clear the take-profit and/or stop-loss of an \*\*already running\*\*\
> futures grid order. Weight: 1.\
> \
> This does NOT create triggers for a not-yet-started order — use \`create\` (fields\
> \`lossStopType\` / \`profitStopType\` etc.) for that. This endpoint mutates the\
> take-profit / stop-loss of an existing order in place.\
> \
> \*\*Request field naming\*\*: unlike the other \`futuresGrid\` endpoints (which use\
> camelCase), this endpoint takes \*\*snake\_case\*\* field names, and the trigger\
> settings are passed as a \`list\` of items — one item per trigger you want to set.\
> A single call may contain a \`stop\_loss\` item, a \`stop\_profit\` item, or both.\
> \
> \*\*\`type\`\*\* — which trigger the item configures. Only two values are accepted\
> (App-side legacy spellings such as \`stop-loss\` and the entry-trigger value\
> \`condition\` are rejected here):\
> \
> \| \`type\` | Meaning |\
> \|---|---|\
> \| \`stop\_loss\` | Configure the stop-loss trigger |\
> \| \`stop\_profit\` | Configure the take-profit trigger |\
> \
> \*\*\`stop\_type\`\*\* — decides how \`value\` (and \`limit\_price\`) is interpreted.\
> \*\*Required\*\*; unlike the App, an empty value is NOT accepted (no implicit\
> fallback to \`price\`):\
> \
> \| \`stop\_type\` | \`value\` means | \`limit\_price\` |\
> \|---|---|---|\
> \| \`price\` | Trigger price | ignored |\
> \| \`price\_limit\` | Trigger price; order is placed as a \*\*limit\*\* order at \`limit\_price\` when hit | required |\
> \| \`profit\_amount\` | Profit/loss \*\*amount\*\* in the settlement currency | ignored |\
> \| \`profit\_ratio\` | Profit/loss \*\*ratio\*\* (e.g. \`0.5\` = +50%, \`-0.2\` = −20%) | ignored |\
> \
> \*\*Clearing a trigger\*\*: pass \`value\` as an empty string \`""\` for that item to\
> remove the previously set take-profit / stop-loss.\
> \
> \*\*\`value\` validation\*\*: when \`value\` is non-empty it only needs to be a valid\
> decimal — the endpoint does not enforce a positive value. \`0\` and negative values\
> are accepted (a stop-loss expressed as a negative \`profit\_ratio\` / \`profit\_amount\`\
> is meaningful).\
> \
> \*\*Neutral grid (\`no\_trend\`) upper stop-loss\*\*: for a neutral grid, a stop-loss can\
> additionally set an \*\*upper\*\* threshold above the grid range using\
> \`stop\_high\_price\` (and \`limit\_high\_price\` when \`stop\_type=price\_limit\`). These two\
> fields apply only to a \`stop\_loss\` item on a neutral grid and only when\
> \`stop\_type\` is \`price\` or \`price\_limit\`; they are ignored otherwise.\
> \
> \*\*\`\*\_sell\_model\`\*\* — settlement currency for the position closed by the trigger.\
> Optional; when empty the order's default is used:\
> \
> \| Value | Meaning |\
> \|---|---|\
> \| \`TO\_QUOTE\` | Settle to the quote currency |\
> \| \`TO\_USDT\` | Settle to USDT |\
> \
> Use \`loss\_stop\_sell\_model\` on a \`stop\_loss\` item and \`profit\_stop\_sell\_model\` on a\
> \`stop\_profit\` item.\
> \
> \*\*Asynchronous write\*\*: a successful response only means the request was accepted\
> and forwarded. The take-profit / stop-loss is persisted onto the order record\
> asynchronously — poll \`GET /futuresGrid/order\` and read \`lossStop\` / \`profitStop\`\
> (and related fields) to confirm the update took effect.\
> \
> \*\*Restrictions\*\* (return \`result=false\` with the message shown):\
> \
> \| Message | Cause |\
> \|---|---|\
> \| \`trigger price list nil\` | \`list\` is empty |\
> \| \`invalid type: {v}, must be one of stop\_loss/stop\_profit\` | \`type\` not in the allow-list |\
> \| \`invalid stop\_type: {v}, must be one of price/price\_limit/profit\_amount/profit\_ratio\` | \`stop\_type\` missing or not in the allow-list |\
> \| \`invalid amount: {v}\` | \`value\` / \`limit\_price\` / \`limit\_high\_price\` is not a valid decimal |\
> \| \`invalid loss\_stop\_sell\_model: {v}\` | \`loss\_stop\_sell\_model\` not \`TO\_QUOTE\` / \`TO\_USDT\` |\
> \| \`invalid profit\_stop\_sell\_model: {v}\` | \`profit\_stop\_sell\_model\` not \`TO\_QUOTE\` / \`TO\_USDT\` |\
> \| \`order is disable change tp\` | The order forbids changing take-profit / stop-loss |\
> \| \`forbidden by invalid status:{s}, order\_id:{id}\` | Order is closing/unlocking/canceled |\
> \| \`forbidden for future\_grid\_bonus order\` | Bonus-funded orders cannot set a stop-loss |\
> \
> \*\*Examples\*\* — request bodies for common combinations:\
> \
> Set a stop-loss at a fixed price:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_loss", "stop\_type": "price", "value": "70000" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Set a take-profit at a fixed price:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_profit", "stop\_type": "price", "value": "150000" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Set both take-profit and stop-loss in one call:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_loss",   "stop\_type": "price", "value": "70000" },\
> &#x20;   { "type": "stop\_profit", "stop\_type": "price", "value": "150000" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Stop-loss by loss ratio (−20%) and take-profit by profit ratio (+50%):\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_loss",   "stop\_type": "profit\_ratio", "value": "-0.2" },\
> &#x20;   { "type": "stop\_profit", "stop\_type": "profit\_ratio", "value": "0.5" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Take-profit by profit amount, settled to USDT:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_profit", "stop\_type": "profit\_amount", "value": "500", "profit\_stop\_sell\_model": "TO\_USDT" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Take-profit as a limit order (place a limit at 149000 when 150000 is hit),\
> with a 30s trigger delay:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_profit", "stop\_type": "price\_limit", "value": "150000", "limit\_price": "149000", "stop\_delay": 30 }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Neutral grid (\`no\_trend\`) — lower and upper stop-loss prices:\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_loss", "stop\_type": "price", "value": "70000", "stop\_high\_price": "160000" }\
> &#x20; ]\
> }\
> \`\`\`\
> \
> Clear a previously set stop-loss (empty \`value\`):\
> \`\`\`json\
> {\
> &#x20; "bu\_order\_id": "1234567890",\
> &#x20; "list": \[\
> &#x20;   { "type": "stop\_loss", "stop\_type": "price", "value": "" }\
> &#x20; ]\
> }\
> \`\`\`<br>

````json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Futures Grid","description":"Futures Grid Bot management (private)"}],"servers":[{"url":"https://api.pionex.com","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"PIONEX-KEY","description":"API Key authentication. Requires two headers:\n- `PIONEX-KEY`: Your API Key\n- `PIONEX-SIGNATURE`: HMAC SHA256 hex signature\n\nAnd a `timestamp` query parameter (milliseconds).\n"}},"parameters":{"Timestamp":{"name":"timestamp","in":"query","required":true,"description":"Current timestamp in milliseconds (valid range +/- 20 seconds)","schema":{"type":"integer","format":"int64"}}},"schemas":{"FuturesGridUpdateTriggerProfitLossRequest":{"type":"object","required":["bu_order_id","list"],"description":"Set / update / clear the take-profit and stop-loss of a running futures grid order.\nField names are snake_case (unlike the other futuresGrid endpoints).\n","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"list":{"type":"array","description":"One item per trigger to configure. May include a `stop_loss` item, a `stop_profit` item, or both.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"FuturesGridTriggerProfitLossItem":{"type":"object","required":["type","stop_type","value"],"description":"A single take-profit or stop-loss setting. Field names are snake_case.\nHow `value` / `limit_price` are interpreted depends on `stop_type`.\n","properties":{"type":{"type":"string","description":"Which trigger this item configures","enum":["stop_loss","stop_profit"]},"stop_type":{"type":"string","description":"How `value` is interpreted. Required (no implicit fallback):\n`price` (trigger price), `price_limit` (trigger price, closes via a limit\norder at `limit_price`), `profit_amount` (profit/loss amount),\n`profit_ratio` (profit/loss ratio).\n","enum":["price","price_limit","profit_amount","profit_ratio"]},"value":{"type":"string","description":"Trigger threshold, interpreted per `stop_type`. Empty string `\"\"` clears the\ntrigger. When non-empty it only needs to be a valid decimal — not enforced to\nbe positive; `0` and negative values are accepted (e.g. `-0.2` = a −20%\nstop-loss ratio).\n"},"limit_price":{"type":"string","description":"Limit price used to close the position when `stop_type=price_limit`. Required in that case."},"stop_delay":{"type":"integer","format":"int64","description":"Seconds to wait after the condition is first met before executing. `0` = immediate."},"loss_stop_sell_model":{"type":"string","description":"Settlement currency for a stop-loss close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"profit_stop_sell_model":{"type":"string","description":"Settlement currency for a take-profit close. Optional; empty = order default.","enum":["TO_QUOTE","TO_USDT"]},"stop_high_price":{"type":"string","description":"Upper stop-loss price for a neutral grid (`no_trend`). Applies only to a\n`stop_loss` item and only when `stop_type` is `price` or `price_limit`;\nignored otherwise.\n"},"limit_high_price":{"type":"string","description":"Upper limit stop-loss price for a neutral grid, used together with `stop_high_price` when `stop_type=price_limit`."}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"FuturesGridTriggerProfitLossResponse":{"type":"object","description":"Echo of the applied trigger settings. Persistence onto the order is asynchronous — poll `GET /futuresGrid/order` to confirm.","properties":{"bu_order_id":{"type":"string","description":"Bot order ID"},"result":{"type":"integer","format":"int32","description":"RPC return code"},"list":{"type":"array","description":"Echo of the trigger settings that were applied.","items":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossItem"}}}},"ErrorResponse":{"type":"object","properties":{"result":{"type":"boolean"},"code":{"type":"string","description":"Error code. Common bot error codes:\n- `BOT_INVALID_ARGUMENT` — Business validation failure (e.g. invalid parameters, order state conflict, PnL check failure). The `message` field contains the specific reason.\n- `BOT_INTERNAL_ERROR` — System/RPC error (network timeout, downstream service unavailable). Retrying may help.\n- `PARAMETER_ERROR` — Request parameter format error.\n"},"message":{"type":"string","description":"Human-readable error message with specific reason"},"data":{"description":"Optional partial data returned with validation errors (e.g. min_investment, estimate data)"},"timestamp":{"type":"integer","format":"int64"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/api/v1/bot/orders/futuresGrid/updateTriggerProfitLoss":{"post":{"tags":["Futures Grid"],"summary":"Set / update / clear take-profit & stop-loss","description":"Set, update, or clear the take-profit and/or stop-loss of an **already running**\nfutures grid order. Weight: 1.\n\nThis does NOT create triggers for a not-yet-started order — use `create` (fields\n`lossStopType` / `profitStopType` etc.) for that. This endpoint mutates the\ntake-profit / stop-loss of an existing order in place.\n\n**Request field naming**: unlike the other `futuresGrid` endpoints (which use\ncamelCase), this endpoint takes **snake_case** field names, and the trigger\nsettings are passed as a `list` of items — one item per trigger you want to set.\nA single call may contain a `stop_loss` item, a `stop_profit` item, or both.\n\n**`type`** — which trigger the item configures. Only two values are accepted\n(App-side legacy spellings such as `stop-loss` and the entry-trigger value\n`condition` are rejected here):\n\n| `type` | Meaning |\n|---|---|\n| `stop_loss` | Configure the stop-loss trigger |\n| `stop_profit` | Configure the take-profit trigger |\n\n**`stop_type`** — decides how `value` (and `limit_price`) is interpreted.\n**Required**; unlike the App, an empty value is NOT accepted (no implicit\nfallback to `price`):\n\n| `stop_type` | `value` means | `limit_price` |\n|---|---|---|\n| `price` | Trigger price | ignored |\n| `price_limit` | Trigger price; order is placed as a **limit** order at `limit_price` when hit | required |\n| `profit_amount` | Profit/loss **amount** in the settlement currency | ignored |\n| `profit_ratio` | Profit/loss **ratio** (e.g. `0.5` = +50%, `-0.2` = −20%) | ignored |\n\n**Clearing a trigger**: pass `value` as an empty string `\"\"` for that item to\nremove the previously set take-profit / stop-loss.\n\n**`value` validation**: when `value` is non-empty it only needs to be a valid\ndecimal — the endpoint does not enforce a positive value. `0` and negative values\nare accepted (a stop-loss expressed as a negative `profit_ratio` / `profit_amount`\nis meaningful).\n\n**Neutral grid (`no_trend`) upper stop-loss**: for a neutral grid, a stop-loss can\nadditionally set an **upper** threshold above the grid range using\n`stop_high_price` (and `limit_high_price` when `stop_type=price_limit`). These two\nfields apply only to a `stop_loss` item on a neutral grid and only when\n`stop_type` is `price` or `price_limit`; they are ignored otherwise.\n\n**`*_sell_model`** — settlement currency for the position closed by the trigger.\nOptional; when empty the order's default is used:\n\n| Value | Meaning |\n|---|---|\n| `TO_QUOTE` | Settle to the quote currency |\n| `TO_USDT` | Settle to USDT |\n\nUse `loss_stop_sell_model` on a `stop_loss` item and `profit_stop_sell_model` on a\n`stop_profit` item.\n\n**Asynchronous write**: a successful response only means the request was accepted\nand forwarded. The take-profit / stop-loss is persisted onto the order record\nasynchronously — poll `GET /futuresGrid/order` and read `lossStop` / `profitStop`\n(and related fields) to confirm the update took effect.\n\n**Restrictions** (return `result=false` with the message shown):\n\n| Message | Cause |\n|---|---|\n| `trigger price list nil` | `list` is empty |\n| `invalid type: {v}, must be one of stop_loss/stop_profit` | `type` not in the allow-list |\n| `invalid stop_type: {v}, must be one of price/price_limit/profit_amount/profit_ratio` | `stop_type` missing or not in the allow-list |\n| `invalid amount: {v}` | `value` / `limit_price` / `limit_high_price` is not a valid decimal |\n| `invalid loss_stop_sell_model: {v}` | `loss_stop_sell_model` not `TO_QUOTE` / `TO_USDT` |\n| `invalid profit_stop_sell_model: {v}` | `profit_stop_sell_model` not `TO_QUOTE` / `TO_USDT` |\n| `order is disable change tp` | The order forbids changing take-profit / stop-loss |\n| `forbidden by invalid status:{s}, order_id:{id}` | Order is closing/unlocking/canceled |\n| `forbidden for future_grid_bonus order` | Bonus-funded orders cannot set a stop-loss |\n\n**Examples** — request bodies for common combinations:\n\nSet a stop-loss at a fixed price:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"70000\" }\n  ]\n}\n```\n\nSet a take-profit at a fixed price:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_profit\", \"stop_type\": \"price\", \"value\": \"150000\" }\n  ]\n}\n```\n\nSet both take-profit and stop-loss in one call:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_loss\",   \"stop_type\": \"price\", \"value\": \"70000\" },\n    { \"type\": \"stop_profit\", \"stop_type\": \"price\", \"value\": \"150000\" }\n  ]\n}\n```\n\nStop-loss by loss ratio (−20%) and take-profit by profit ratio (+50%):\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_loss\",   \"stop_type\": \"profit_ratio\", \"value\": \"-0.2\" },\n    { \"type\": \"stop_profit\", \"stop_type\": \"profit_ratio\", \"value\": \"0.5\" }\n  ]\n}\n```\n\nTake-profit by profit amount, settled to USDT:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_profit\", \"stop_type\": \"profit_amount\", \"value\": \"500\", \"profit_stop_sell_model\": \"TO_USDT\" }\n  ]\n}\n```\n\nTake-profit as a limit order (place a limit at 149000 when 150000 is hit),\nwith a 30s trigger delay:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_profit\", \"stop_type\": \"price_limit\", \"value\": \"150000\", \"limit_price\": \"149000\", \"stop_delay\": 30 }\n  ]\n}\n```\n\nNeutral grid (`no_trend`) — lower and upper stop-loss prices:\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"70000\", \"stop_high_price\": \"160000\" }\n  ]\n}\n```\n\nClear a previously set stop-loss (empty `value`):\n```json\n{\n  \"bu_order_id\": \"1234567890\",\n  \"list\": [\n    { \"type\": \"stop_loss\", \"stop_type\": \"price\", \"value\": \"\" }\n  ]\n}\n```\n","operationId":"updateTriggerProfitLossFuturesGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuturesGridUpdateTriggerProfitLossRequest"}}}},"responses":{"200":{"description":"Trigger update accepted (persisted asynchronously).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FuturesGridTriggerProfitLossResponse"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
````