Preview a grid

POST https://rest.haasapi.com/v1/partner/users/{user_id}/bots/preview

Dry-runs a grid strategy for an end-user: computes where its orders would sit at the live price, without creating a bot or placing anything. config is the same config a create takes, including symbol. Grid strategies only (spot_grid, futures_grid).

Requires the partner scope.

Request body

{
  "type": "spot_grid",
  "config": {
    "symbol": "BTC_USDT",
    "lower_limit": 25000,
    "upper_limit": 35000,
    "grid_count": 20,
    "investment_asset": "USDT",
    "investment_amount": 500
  }
}

PreviewPartnerBotRequest

Field	Type	Description
`type`	WhiteLabelScriptType	The grid strategy to preview: spot_grid or futures_grid.
`config`	object	The strategy configuration by its snake_case keys, including `symbol`.

Example request

curl "https://rest.haasapi.com/v1/partner/users/{user_id}/bots/preview" \
  -X POST \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"spot_grid","config":{"symbol":"BTC_USDT","lower_limit":25000,"upper_limit":35000,"grid_count":20,"investment_asset":"USDT","investment_amount":500}}'

Response

200 OK. Returns a PartnerGridPreview.

{
  "summary": {
    "current_price": "30000",
    "lower_limit": "25000",
    "upper_limit": "35000",
    "grid_count": 20,
    "grid_mode": "arithmetic",
    "grid_spacing": "500",
    "min_profitable_spacing": "60",
    "is_profitable": true,
    "profitability_message": "Each grid step clears fees.",
    "buy_order_count": 10,
    "sell_order_count": 10,
    "total_buy_value": "250",
    "total_sell_quantity": "0.008",
    "min_profit_per_grid": "0.9",
    "max_profit_per_grid": "1.4",
    "investment_asset": "USDT",
    "investment_amount": "500",
    "max_win": null,
    "max_loss": null,
    "leverage": null
  },
  "levels": [
    {
      "index": 0,
      "price": "25000",
      "quantity": "0.01",
      "value": "250",
      "side": "buy"
    },
    {
      "index": 10,
      "price": "30000",
      "quantity": "0",
      "value": "0",
      "side": "middle"
    },
    {
      "index": 20,
      "price": "35000",
      "quantity": "0.008",
      "value": "280",
      "side": "sell"
    }
  ]
}

Fields

PartnerGridPreview

Field	Type	Description
`summary`	PartnerGridPreviewSummary	The grid as a whole: price bounds, spacing, profitability, and totals.
`levels`	array of PartnerGridPreviewLevel	Each grid line, low to high.

PartnerGridPreviewSummary

Field	Type	Description
`current_price`	string (decimal)	The live price the grid was computed against (the ask).
`lower_limit`	string (decimal)
`upper_limit`	string (decimal)
`grid_count`	integer (int32)
`grid_mode`	string, nullable	How the grid lines are spaced (e.g. arithmetic or geometric).
`grid_spacing`	string (decimal)
`min_profitable_spacing`	string (decimal)	The spacing below which fees eat the per-grid profit.
`is_profitable`	boolean	Whether each grid step clears fees at the current spacing.
`profitability_message`	string, nullable
`buy_order_count`	integer (int32)
`sell_order_count`	integer (int32)
`total_buy_value`	string (decimal)
`total_sell_quantity`	string (decimal)
`min_profit_per_grid`	string (decimal)
`max_profit_per_grid`	string (decimal)
`investment_asset`	string, nullable
`investment_amount`	string (decimal)
`max_win`	string, nullable	Futures only: the max win as a decimal string; null for spot.
`max_loss`	string, nullable	Futures only: the max loss as a decimal string; null for spot.
`leverage`	integer (int32), nullable	Futures only: the leverage; null for spot.

PartnerGridPreviewLevel

Field	Type	Description
`index`	integer (int32)
`price`	string (decimal)
`quantity`	string (decimal)
`value`	string (decimal)
`side`	string	buy, sell, or middle.

Errors

All errors are RFC 9457 problem documents.

Status	Description
`400`	The request is malformed (invalid limit, unusable cursor, …). (`code: invalid_request`)
`401`	Missing, malformed, disabled, or revoked API key. (`code: invalid_api_key`)
`404`	No accessible end-user with that id. (`code: user_not_found`)
`409`	A request with this Idempotency-Key is still being processed. (`code: idempotency_in_progress`)
`422`	Preview is only available for grid strategies. (`code: not_grid_strategy`) The configuration was rejected - see the message. (`code: invalid_config`) The Idempotency-Key was already used with a different request. (`code: idempotency_key_reuse`)
`500`	An unexpected error inside the API. Nothing about the request caused it; retry, and quote the instance value if it persists. (`code: internal_error`)
`502`	An internal service answered in a way the API could not serve. Retry. (`code: upstream_error`)
`503`	The request could not be served right now. Retry with the same key - do not discard it. (`code: temporarily_unavailable`) The current market price could not be fetched; retry. (`code: price_unavailable`)
`504`	An internal service did not answer within the deadline. Retry with backoff. (`code: upstream_timeout`)

{
  "type": "https://docs.haasapi.com/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The request is malformed (invalid limit, unusable cursor, …).",
  "code": "invalid_request"
}