Skip to content
Clear Street Clear Street Clear Street
Start Trading
API Reference
V1
Orders

Preview Orders

$ clst v1:orders preview-orders
POST/v1/accounts/{account_id}/orders/preview

Preview the impact of orders without submitting them. For each order the engine evaluates every pre-trade risk check and projects the account’s balances and positions as if the order were fully filled — at the limit price for limit orders and at the current reference price for market orders. Orders are evaluated independently: they do not see each other’s projected fills. Nothing is submitted and no account state changes.

The response carries one result per requested order, in request order. When the request contains more than one order, every order must carry a unique id, which is echoed on its result. An order that cannot be previewed gets an error on its own result without affecting the rest of the batch; the response is still 200 OK — per-order outcomes live only in the rows, and non-2xx statuses are reserved for request-level failures (invalid batch, authorization, engine unavailable).

ParametersExpand Collapse
--account-id: number

Account identifier

--preview: array of NewOrderRequest { order_type, quantity, side, 13 more }
ReturnsExpand Collapse
V1OrderPreviewOrdersResponse: BaseResponse { metadata, error }
data: array of OrderPreviewEntry
union_member_0: object { preview, id }

The order was previewed successfully.

preview: object { account_id, amount, buying_power, 5 more }

The projected impact of the order.

account_id: number

The account the order was previewed for.

amount: object { gross_amount, net_amount }

Monetary size of the previewed order.

gross_amount: string

Total cash impact of the order before estimated fees and commissions.

net_amount: string

Total cash impact of the order after estimated fees and commissions.

buying_power: object { after, before, change }

Buying power before and after the order.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

currency: string

Currency for all monetary values.

equity: object { after, before, change }

Account equity before and after the order.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

errors: array of OrderPreviewError { description, metadata, type }

Risk-check errors that would prevent the order from being accepted. Empty when the order would pass every pre-trade risk check.

description: string

Human-readable description of the error.

metadata: map[string]

Structured details for the error (stringified values), e.g. required and available amounts, and leg_index/leg_symbol for multileg leg errors.

type: string

Stable error code.

margin_details: object { initial_margin_excess, initial_margin_requirement, maintenance_margin_excess, 3 more }

Margin requirements and excess before and after the order.

initial_margin_excess: object { after, before, change }

Initial margin excess.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

initial_margin_requirement: object { after, before, change }

Initial margin requirement.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

maintenance_margin_excess: object { after, before, change }

Maintenance margin excess.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

maintenance_margin_requirement: object { after, before, change }

Maintenance margin requirement.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

overnight_margin_excess: object { after, before, change }

Overnight margin excess.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

overnight_margin_requirement: object { after, before, change }

Overnight margin requirement.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

positions: array of OrderPreviewPosition { instrument_id, quantity, symbol }

Positions in the traded instruments before and after the order.

instrument_id: string

The instrument’s identifier.

quantity: object { after, before, change }

Net position quantity before and after the order.

after: string

The value with the previewed order also fully filled.

before: string

The value before the order, as the risk engine evaluates it: the account’s open orders are projected as filled.

change: string

The previewed order’s isolated impact: after - before.

symbol: string

The instrument’s symbol.

id: optional string

The client-provided id of the order this entry belongs to, echoed from the request. Always present when the request contains more than one order, since ids are required there.

union_member_1: object { error, id }

The order could not be previewed. Shaped exactly like the top-level error object on rejected submissions.

error: object { code, message, details }

Why this order’s preview failed.

code: number

The error code is used to identify the nature of the error. It corresponds to an HTTP status code.

message: string

A human-readable message providing more details about the error.

details: optional array of map[unknown]

Additional error details, if any. This can include structured information such as field violations or error metadata.

id: optional string

The client-provided id of the order this entry belongs to, echoed from the request. Always present when the request contains more than one order, since ids are required there.

Preview Orders

clst v1:orders preview-orders \
  --api-key 'My API Key' \
  --account-id 0 \
  --preview "{order_type: LIMIT, quantity: '100', side: BUY, time_in_force: DAY}" \
  --preview "{order_type: LIMIT, quantity: '10', side: BUY, time_in_force: DAY}"
{
  "data": [
    {
      "id": "preview-1",
      "preview": {
        "account_id": 19816,
        "amount": {
          "gross_amount": "10000.00",
          "net_amount": "10000.00"
        },
        "buying_power": {
          "after": "190000.00",
          "before": "200000.00",
          "change": "-10000.00"
        },
        "currency": "USD",
        "equity": {
          "after": "100000.00",
          "before": "100000.00",
          "change": "0.00"
        },
        "errors": [],
        "margin_details": {
          "initial_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "initial_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          },
          "maintenance_margin_excess": {
            "after": "97500.00",
            "before": "100000.00",
            "change": "-2500.00"
          },
          "maintenance_margin_requirement": {
            "after": "2500.00",
            "before": "0.00",
            "change": "2500.00"
          },
          "overnight_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "overnight_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          }
        },
        "positions": [
          {
            "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
            "quantity": {
              "after": "100",
              "before": "0",
              "change": "100"
            },
            "symbol": "AAPL"
          }
        ]
      }
    },
    {
      "error": {
        "code": 400,
        "message": "Security not found: BADSYM"
      },
      "id": "preview-2"
    }
  ],
  "metadata": {
    "request_id": "d3e5b1a2-8c4f-4b6e-9d2a-1f0c9b8a7654"
  }
}
{
  "data": [
    {
      "id": "preview-1",
      "preview": {
        "account_id": 19816,
        "amount": {
          "gross_amount": "10000.00",
          "net_amount": "10000.00"
        },
        "buying_power": {
          "after": "190000.00",
          "before": "200000.00",
          "change": "-10000.00"
        },
        "currency": "USD",
        "equity": {
          "after": "100000.00",
          "before": "100000.00",
          "change": "0.00"
        },
        "errors": [],
        "margin_details": {
          "initial_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "initial_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          },
          "maintenance_margin_excess": {
            "after": "97500.00",
            "before": "100000.00",
            "change": "-2500.00"
          },
          "maintenance_margin_requirement": {
            "after": "2500.00",
            "before": "0.00",
            "change": "2500.00"
          },
          "overnight_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "overnight_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          }
        },
        "positions": [
          {
            "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
            "quantity": {
              "after": "100",
              "before": "0",
              "change": "100"
            },
            "symbol": "AAPL"
          }
        ]
      }
    }
  ],
  "metadata": {
    "request_id": "d3e5b1a2-8c4f-4b6e-9d2a-1f0c9b8a7654"
  }
}
Returns Examples
{
  "data": [
    {
      "id": "preview-1",
      "preview": {
        "account_id": 19816,
        "amount": {
          "gross_amount": "10000.00",
          "net_amount": "10000.00"
        },
        "buying_power": {
          "after": "190000.00",
          "before": "200000.00",
          "change": "-10000.00"
        },
        "currency": "USD",
        "equity": {
          "after": "100000.00",
          "before": "100000.00",
          "change": "0.00"
        },
        "errors": [],
        "margin_details": {
          "initial_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "initial_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          },
          "maintenance_margin_excess": {
            "after": "97500.00",
            "before": "100000.00",
            "change": "-2500.00"
          },
          "maintenance_margin_requirement": {
            "after": "2500.00",
            "before": "0.00",
            "change": "2500.00"
          },
          "overnight_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "overnight_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          }
        },
        "positions": [
          {
            "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
            "quantity": {
              "after": "100",
              "before": "0",
              "change": "100"
            },
            "symbol": "AAPL"
          }
        ]
      }
    },
    {
      "error": {
        "code": 400,
        "message": "Security not found: BADSYM"
      },
      "id": "preview-2"
    }
  ],
  "metadata": {
    "request_id": "d3e5b1a2-8c4f-4b6e-9d2a-1f0c9b8a7654"
  }
}
{
  "data": [
    {
      "id": "preview-1",
      "preview": {
        "account_id": 19816,
        "amount": {
          "gross_amount": "10000.00",
          "net_amount": "10000.00"
        },
        "buying_power": {
          "after": "190000.00",
          "before": "200000.00",
          "change": "-10000.00"
        },
        "currency": "USD",
        "equity": {
          "after": "100000.00",
          "before": "100000.00",
          "change": "0.00"
        },
        "errors": [],
        "margin_details": {
          "initial_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "initial_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          },
          "maintenance_margin_excess": {
            "after": "97500.00",
            "before": "100000.00",
            "change": "-2500.00"
          },
          "maintenance_margin_requirement": {
            "after": "2500.00",
            "before": "0.00",
            "change": "2500.00"
          },
          "overnight_margin_excess": {
            "after": "95000.00",
            "before": "100000.00",
            "change": "-5000.00"
          },
          "overnight_margin_requirement": {
            "after": "5000.00",
            "before": "0.00",
            "change": "5000.00"
          }
        },
        "positions": [
          {
            "instrument_id": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
            "quantity": {
              "after": "100",
              "before": "0",
              "change": "100"
            },
            "symbol": "AAPL"
          }
        ]
      }
    }
  ],
  "metadata": {
    "request_id": "d3e5b1a2-8c4f-4b6e-9d2a-1f0c9b8a7654"
  }
}