# 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"},"message":{"type":"string","description":"Human-readable error message"},"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"},"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"},"message":{"type":"string","description":"Human-readable error message"},"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"},"message":{"type":"string","description":"Human-readable error message"},"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"],"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 to add to investment.\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":"Whether to reinvest total profit when modifying range (default false)"},"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":"When type=adjust_params: `reinvest` means keep params, add current profit to investment"}}},"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"},"message":{"type":"string","description":"Human-readable error message"},"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"},"message":{"type":"string","description":"Human-readable error message"},"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":"Immediately close with market price (when order is in limit close process)"},"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"},"message":{"type":"string","description":"Human-readable error message"},"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"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.pionex.com/docs/api-docs/bot-api/futures-grid.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.