> 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/spot-grid.md).

# Spot Grid

Spot Grid Bot management (private)

## Get spot grid order

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

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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"}}},"SpotGridOrder":{"type":"object","description":"Spot grid bot order (wraps OrderResult with GridV5OrderData)","properties":{"buOrderType":{"type":"string","description":"Order type (always `grid_v5` for spot grid)"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key 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":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"note":{"type":"string","description":"Order note"},"buOrderData":{"$ref":"#/components/schemas/SpotGridOrderData"}}},"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}},"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/spotGrid/order":{"get":{"tags":["Spot Grid"],"summary":"Get spot grid order","description":"Query a spot grid bot order by ID. Weight: 1.","operationId":"getSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"buOrderId","in":"query","required":true,"description":"Bot order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Get spot grid AI strategy

> Query AI-recommended grid strategy parameters for a trading pair. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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"}}},"SpotGridAiStrategy":{"type":"object","description":"AI-recommended spot grid strategy","properties":{"annualized":{"type":"string","description":"Annualized return of the recommended strategy"},"totalApr":{"type":"string","description":"Total APR"},"high":{"type":"string","description":"Recommended grid upper price"},"low":{"type":"string","description":"Recommended grid lower price"},"gridCount":{"type":"integer","description":"Recommended number of grid levels"},"strategyId":{"type":"string","description":"Strategy ID"},"volatility":{"type":"string","description":"Market volatility indicator"},"maxDrawDown":{"type":"string","description":"Maximum drawdown"},"options":{"type":"array","description":"List of strategy options by time period","items":{"$ref":"#/components/schemas/SpotGridAiStrategyOption"}}}},"SpotGridAiStrategyOption":{"type":"object","description":"AI strategy option for a specific backtesting period","properties":{"period":{"type":"integer","description":"Backtesting period in days (e.g. 7, 14, 30)"},"annualized":{"type":"string","description":"Annualized return for this period"},"totalApr":{"type":"string","description":"Total APR for this period"},"high":{"type":"string","description":"Grid upper price for this period"},"low":{"type":"string","description":"Grid lower price for this period"},"gridCount":{"type":"integer","description":"Number of grid levels for this period"},"maxDrawDown":{"type":"string","description":"Maximum drawdown for this period"},"volatility":{"type":"string","description":"Volatility for this period"},"suitabilityMin":{"type":"integer","description":"Minimum suitability score"},"suitabilityMax":{"type":"integer","description":"Maximum suitability score"}}},"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/spotGrid/aiStrategy":{"get":{"tags":["Spot Grid"],"summary":"Get spot grid AI strategy","description":"Query AI-recommended grid strategy parameters for a trading pair. Weight: 1.","operationId":"getSpotGridAiStrategy","parameters":[{"$ref":"#/components/parameters/Timestamp"},{"name":"base","in":"query","required":true,"description":"Base currency (e.g. BTC)","schema":{"type":"string"}},{"name":"quote","in":"query","required":true,"description":"Quote currency (e.g. USDT)","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridAiStrategy"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Create spot grid order

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

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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":{"CreateSpotGridRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"note":{"type":"string","description":"Optional order note"},"buOrderData":{"$ref":"#/components/schemas/CreateSpotGridOrderData"}}},"CreateSpotGridOrderData":{"type":"object","required":["top","bottom","row","gridType","quoteTotalInvestment"],"properties":{"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels (2–200)"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quoteTotalInvestment":{"type":"string","description":"Quote currency investment amount"},"lossStopType":{"type":"string","description":"Stop loss mode:\n`price` — trigger when market price reaches `lossStop`,\n`profit_amount` — trigger when unrealized loss reaches `lossStop` amount,\n`profit_ratio` — trigger when unrealized loss reaches `lossStop` ratio (e.g. `\"-0.1\"` = -10%)\n","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"profitStopType":{"type":"string","description":"Take profit mode:\n`price` — trigger when market price reaches `profitStop`,\n`profit_amount` — trigger when realized profit reaches `profitStop` amount,\n`profit_ratio` — trigger when realized profit reaches `profitStop` ratio (e.g. `\"0.1\"` = 10%)\n","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing.\nDuring the delay the condition must remain satisfied; if it recovers the timer resets.\nOmit or set to `0` to trigger immediately.\n"},"condition":{"type":"string","description":"Trigger price — bot starts only when price crosses this level (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"slippage":{"type":"string","description":"Open position slippage tolerance (e.g. \"0.01\" = 1%)"},"closeSellModel":{"type":"string","description":"Close sell mode on cancellation:\n`NOT_SELL` - Keep base+quote as-is, do not sell (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"],"default":"NOT_SELL"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"SpotGridOrder":{"type":"object","description":"Spot grid bot order (wraps OrderResult with GridV5OrderData)","properties":{"buOrderType":{"type":"string","description":"Order type (always `grid_v5` for spot grid)"},"buOrderId":{"type":"string","description":"Bot order ID"},"userId":{"type":"string","description":"User ID"},"keyId":{"type":"string","description":"API Key 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":"integer","format":"int64","description":"Creation timestamp in milliseconds"},"closeTime":{"type":"integer","format":"int64","description":"Close timestamp in milliseconds"},"note":{"type":"string","description":"Order note"},"buOrderData":{"$ref":"#/components/schemas/SpotGridOrderData"}}},"SpotGridOrderData":{"type":"object","description":"Spot grid order detail data (GridV5OrderData)","properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"Grid upper price"},"bottom":{"type":"string","description":"Grid lower price"},"row":{"type":"integer","format":"int64","description":"Number of grid levels"},"lossStopType":{"type":"string","description":"Stop loss mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"lossStop":{"type":"string","description":"Stop loss threshold. Interpretation depends on `lossStopType`:\n- `price`: price value (e.g. `\"40000\"`)\n- `profit_amount`: loss amount in quote currency (e.g. `\"-50\"`)\n- `profit_ratio`: loss ratio (e.g. `\"-0.1\"` = -10%)\n"},"lossStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after stop loss condition is first met before executing. `0` means immediate."},"profitStopType":{"type":"string","description":"Take profit mode: `price`, `profit_amount`, `profit_ratio`","enum":["price","profit_amount","profit_ratio"]},"profitStop":{"type":"string","description":"Take profit threshold. Interpretation depends on `profitStopType`:\n- `price`: price value (e.g. `\"55000\"`)\n- `profit_amount`: profit amount in quote currency (e.g. `\"100\"`)\n- `profit_ratio`: profit ratio (e.g. `\"0.1\"` = 10%)\n"},"profitStopDelay":{"type":"integer","format":"int64","description":"Seconds to wait after take profit condition is first met before executing. `0` means immediate."},"condition":{"type":"string","description":"Trigger price set at creation (optional)"},"conditionDirection":{"type":"string","description":"Trigger direction: `\"-1\"` price drops below condition, `\"1\"` price rises above condition","enum":["-1","1"]},"baseTotalInvestment":{"type":"string","description":"Total base currency investment"},"quoteTotalInvestment":{"type":"string","description":"Total quote currency investment"},"gridType":{"type":"string","description":"Grid spacing type: `arithmetic` or `geometric`","enum":["arithmetic","geometric"]},"openPrice":{"type":"string","description":"Market price at order creation"},"earnCoin":{"type":"string","description":"Profit-earning currency (always quote)"},"trend":{"type":"string","description":"Grid direction (always `long` for spot grid)"},"status":{"type":"string","description":"Bot status:\n`prepare`, `lock_currency`, `init_grid`, `running`,\n`destroy_grid`, `unlock_currency`, `canceled`\n"},"createTime":{"type":"integer","format":"int64","description":"Status change timestamp in milliseconds"},"baseInvestment":{"type":"string","description":"Actual base investment amount"},"quoteInvestment":{"type":"string","description":"Actual quote investment amount"},"perVolume":{"type":"string","description":"Volume per grid level"},"baseAmount":{"type":"string","description":"Current base balance in bot account"},"quoteAmount":{"type":"string","description":"Current quote balance in bot account"},"realizedProfit":{"type":"string","description":"Total realized profit (grid profit + float P&L)"},"gridProfit":{"type":"string","description":"Accumulated grid profit"},"totalCostInBase":{"type":"string","description":"Total cost in base currency"},"totalCostInQuote":{"type":"string","description":"Total cost in quote currency"},"totalFeeInBase":{"type":"string","description":"Total fee in base currency"},"totalFeeInQuote":{"type":"string","description":"Total fee in quote currency"},"averageCost":{"type":"string","description":"Average cost price"},"profitWithdrawn":{"type":"string","description":"Total profit extracted so far"},"reasonBy":{"type":"string","description":"Close reason:\n`user_cancel`, `loss_stop`, `profit_stop`, `not_enough_balance`, `create_failed`\n"},"investCoin":{"type":"string","description":"Investment currency: `USDT` or quote currency"},"closeSellModel":{"type":"string","description":"Close sell mode:\n`TO_QUOTE` - Return base+quote as-is,\n`TO_USDT` - Sell base to quote on close\n","enum":["TO_QUOTE","TO_USDT"]},"slippage":{"type":"string","description":"Open position slippage (e.g. \"0.01\" = 1%)"},"pausePrice":{"type":"string","description":"Price when paused"},"profitAutoReinvest":{"type":"boolean","description":"Whether profit auto-reinvest is enabled"},"breakEvenWithoutGridProfit":{"type":"string","description":"Break-even price (excluding grid profit)"},"breakEvenWithGridProfit":{"type":"string","description":"Break-even price (including grid profit)"},"openQuotePrice":{"type":"string","description":"Quote/USDT price at order creation"}}},"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/spotGrid/create":{"post":{"tags":["Spot Grid"],"summary":"Create spot grid order","description":"Create a new spot grid bot order. Weight: 1.","operationId":"createSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSpotGridRequest"}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridOrder"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Check spot grid parameters

> Validate spot grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\
> \
> Pass a positive \`quote\_total\_investment\` to receive full estimate fields.\
> The current market price is fetched automatically — \`open\_price\` is not required.\
> \
> \*\*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 |\
> \|---|---|---|\
> \| \`number invalid: {value}\` | \`top\` or \`bottom\` is not a valid numeric string | No |\
> \| \`number int too long: {value}\` | Integer part of \`top\` or \`bottom\` exceeds 15 digits | No |\
> \| \`number decimal too long: {value}\` | Decimal part of \`top\` or \`bottom\` exceeds 15 digits | No |\
> \| \`invalid quote total investment\` | \`quote\_total\_investment\` must be >= 0 | No |\
> \| \`bottom must be less than top\` | \`bottom\` must be strictly less than \`top\` | No |\
> \| \`row must be between 2 and 1000\` | \`row\` must be in the range \[2, 1000] | No |\
> \| \`invalid grid\_type\` | \`grid\_type\` must be \`arithmetic\` or \`geometric\` | No |\
> \| \`grid price duplicated: reduce row or widen range\` | Grid range too narrow or \`row\` too large — adjacent grid prices are identical | Yes |\
> \| \`quote\_total\_investment not match quote precision: max {N} decimal places\` | \`quote\_total\_investment\` exceeds the allowed decimal precision | Yes |\
> \| \`less than min investment\` | \`quote\_total\_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":"Spot Grid","description":"Spot 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":{"CheckSpotGridParamsRequest":{"type":"object","required":["base","quote","buOrderData"],"properties":{"base":{"type":"string","description":"Base currency"},"quote":{"type":"string","description":"Quote currency"},"buOrderData":{"$ref":"#/components/schemas/CheckSpotGridParamsOrderData"}}},"CheckSpotGridParamsOrderData":{"type":"object","required":["top","bottom","row","grid_type","quote_total_investment"],"properties":{"top":{"type":"string","description":"Grid upper price. Must be a valid numeric string, strictly greater than `bottom`."},"bottom":{"type":"string","description":"Grid lower price. Must be a valid numeric string."},"row":{"type":"integer","description":"Number of grid levels (2–1000).","minimum":2,"maximum":1000},"grid_type":{"type":"string","description":"Grid spacing type: `arithmetic` (equal difference) or `geometric` (equal ratio)","enum":["arithmetic","geometric"]},"quote_total_investment":{"type":"string","description":"Investment amount in quote currency (must be > 0 and >= `min_investment`).\nPassing `\"0\"` will return `result=false` with message `\"less than min investment\"` and partial data.\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"}}},"SpotGridCheckParamsData":{"type":"object","description":"Spot grid parameter check result data.\n\n**When result=true**: All fields are populated.\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`\"grid price duplicated: reduce row or widen range\"`,\n`\"quote_total_investment not match quote precision: max {N} decimal places\"`, or `\"less than min investment\"`.\n","properties":{"min_investment":{"type":"string","description":"Minimum investment amount in quote currency"},"max_investment":{"type":"string","description":"Maximum investment amount in quote currency"},"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_fee":{"type":"string","description":"Estimated opening trading fee."}}},"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/spotGrid/checkParams":{"post":{"tags":["Spot Grid"],"summary":"Check spot grid parameters","description":"Validate spot grid bot creation parameters and estimate investment values without creating an order. Weight: 1.\n\nPass a positive `quote_total_investment` to receive full estimate fields.\nThe current market price is fetched automatically — `open_price` is not required.\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| `number invalid: {value}` | `top` or `bottom` is not a valid numeric string | No |\n| `number int too long: {value}` | Integer part of `top` or `bottom` exceeds 15 digits | No |\n| `number decimal too long: {value}` | Decimal part of `top` or `bottom` exceeds 15 digits | No |\n| `invalid quote total investment` | `quote_total_investment` must be >= 0 | No |\n| `bottom must be less than top` | `bottom` must be strictly less than `top` | No |\n| `row must be between 2 and 1000` | `row` must be in the range [2, 1000] | No |\n| `invalid grid_type` | `grid_type` must be `arithmetic` or `geometric` | No |\n| `grid price duplicated: reduce row or widen range` | Grid range too narrow or `row` too large — adjacent grid prices are identical | Yes |\n| `quote_total_investment not match quote precision: max {N} decimal places` | `quote_total_investment` exceeds the allowed decimal precision | Yes |\n| `less than min investment` | `quote_total_investment` is `\"0\"` or less than `min_investment` | Yes |\n","operationId":"checkSpotGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckSpotGridParamsRequest"}}}},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SpotGridCheckParamsData"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Adjust spot grid parameters

> Modify grid range (top/bottom/row) or adjust investment for a running spot grid order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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":{"AdjustSpotGridParamsRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"top":{"type":"string","description":"New grid upper price"},"bottom":{"type":"string","description":"New grid lower price"},"row":{"type":"integer","format":"int32","description":"New number of grid levels"},"quoteInvest":{"type":"string","description":"Additional quote investment amount"}}},"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/spotGrid/adjustParams":{"post":{"tags":["Spot Grid"],"summary":"Adjust spot grid parameters","description":"Modify grid range (top/bottom/row) or adjust investment for a running spot grid order. Weight: 1.","operationId":"adjustSpotGridParams","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdjustSpotGridParamsRequest"}}}},"responses":{"200":{"description":"Adjustment applied successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"action_id":{"type":"string","description":"Adjustment action ID"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Add investment to spot grid

> Add additional investment to a running spot grid order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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":{"InvestInSpotGridRequest":{"type":"object","required":["buOrderId","quoteInvest"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"quoteInvest":{"type":"string","description":"Additional investment amount in quote currency"}}},"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/spotGrid/investIn":{"post":{"tags":["Spot Grid"],"summary":"Add investment to spot grid","description":"Add additional investment to a running spot grid order. Weight: 1.","operationId":"investInSpotGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestInSpotGridRequest"}}}},"responses":{"200":{"description":"Investment added successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"action_id":{"type":"string","description":"Investment action ID"}}}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Cancel spot grid order

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

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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":{"CancelSpotGridRequest":{"type":"object","required":["buOrderId"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"closeSellModel":{"type":"string","description":"Close sell mode set at creation:\n`NOT_SELL` - Keep base+quote as-is (default),\n`TO_QUOTE` - Sell base to quote on close,\n`TO_USDT` - Sell base to USDT on close\n","enum":["NOT_SELL","TO_QUOTE","TO_USDT"]},"slippage":{"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/spotGrid/cancel":{"post":{"tags":["Spot Grid"],"summary":"Cancel spot grid order","description":"Close and cancel a spot grid bot order. Weight: 1.","operationId":"cancelSpotGridOrder","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSpotGridRequest"}}}},"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Extract profit from spot grid

> Extract accumulated grid profit from a running spot grid order. Weight: 1.

```json
{"openapi":"3.0.3","info":{"title":"Pionex Bot Open API","version":"1.0.0"},"tags":[{"name":"Spot Grid","description":"Spot 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":{"ProfitSpotGridRequest":{"type":"object","required":["buOrderId","amount"],"properties":{"buOrderId":{"type":"string","description":"Bot order ID"},"amount":{"type":"string","description":"Amount to extract"}}},"BaseResponse":{"type":"object","properties":{"result":{"type":"boolean","description":"Request success indicator"},"timestamp":{"type":"integer","format":"int64","description":"Response timestamp in milliseconds"}}},"TransferRecord":{"type":"object","description":"Record of a profit extraction transfer","properties":{"transferId":{"type":"string","description":"Transfer ID"},"buOrderId":{"type":"string","description":"Bot order ID"},"type":{"type":"string","description":"Transfer type (e.g. `profit`)"},"direction":{"type":"string","description":"Transfer direction: `out` (extract from bot)"},"coin":{"type":"string","description":"Transfer currency"},"amount":{"type":"string","description":"Transfer amount"},"amountC":{"type":"string","description":"Transfer amount in platform currency"},"status":{"type":"string","description":"Transfer status"},"createTime":{"type":"integer","format":"int64","description":"Transfer timestamp in milliseconds"},"error":{"type":"string","description":"Error message (if failed)"}}},"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/spotGrid/profit":{"post":{"tags":["Spot Grid"],"summary":"Extract profit from spot grid","description":"Extract accumulated grid profit from a running spot grid order. Weight: 1.","operationId":"profitSpotGrid","parameters":[{"$ref":"#/components/parameters/Timestamp"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfitSpotGridRequest"}}}},"responses":{"200":{"description":"Profit extracted successfully","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/BaseResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransferRecord"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```