> 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"},"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/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"},"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/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"},"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/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 |
```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"},"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/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"},"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/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"},"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/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"},"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/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"},"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/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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://www.pionex.com/docs/api-docs/bot-api/spot-grid.md?ask=
```
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.