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

Preview Orders

client.V1.Orders.PreviewOrders(ctx, accountID, body) (*V1OrderPreviewOrdersResponse, error)
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
accountID int64
body V1OrderPreviewOrdersParams
Preview param.Field[[]NewOrderRequest]

Type of order

One of the following:
const RequestOrderTypeMarket RequestOrderType = "MARKET"
const RequestOrderTypeLimit RequestOrderType = "LIMIT"
const RequestOrderTypeStop RequestOrderType = "STOP"
const RequestOrderTypeStopLimit RequestOrderType = "STOP_LIMIT"
const RequestOrderTypeTrailingStop RequestOrderType = "TRAILING_STOP"
const RequestOrderTypeTrailingStopLimit RequestOrderType = "TRAILING_STOP_LIMIT"
Quantity string

Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer)

Side Side

Side of the order

One of the following:
const SideBuy Side = "BUY"
const SideSell Side = "SELL"
TimeInForce RequestTimeInForce

Time in force

One of the following:
const RequestTimeInForceDay RequestTimeInForce = "DAY"
const RequestTimeInForceGoodTillCancel RequestTimeInForce = "GOOD_TILL_CANCEL"
const RequestTimeInForceImmediateOrCancel RequestTimeInForce = "IMMEDIATE_OR_CANCEL"
const RequestTimeInForceFillOrKill RequestTimeInForce = "FILL_OR_KILL"
const RequestTimeInForceGoodTillDate RequestTimeInForce = "GOOD_TILL_DATE"
const RequestTimeInForceAtOpen RequestTimeInForce = "AT_OPEN"
const RequestTimeInForceAtClose RequestTimeInForce = "AT_CLOSE"
ID stringOptional

Optional client-provided unique ID (idempotency). Required to be unique per account.

maxLength64
ExpiresAt TimeOptional

The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE.

formatdate-time
ExtendedHours boolOptional

Allow trading outside regular trading hours. Some brokers disallow options outside RTH.

InstrumentID InstrumentIDOrSymbolOptional

Instrument ID (UUID) or symbol (equity ticker or OSI option symbol). Either symbol or instrument_id must be provided.

minLength1
LimitOffset stringOptional

Limit offset for trailing stop-limit orders (signed)

LimitPrice stringOptional

Limit price (required for LIMIT and STOP_LIMIT orders)

PositionIntent RequestPositionEffectOptional

Optional open/close intent for this order. When omitted, the platform determines the position effect.

One of the following:
const RequestPositionEffectOpen RequestPositionEffect = "OPEN"
const RequestPositionEffectClose RequestPositionEffect = "CLOSE"
StopPrice stringOptional

Stop price (required for STOP and STOP_LIMIT orders)

Strategy OrderStrategyUnionOptional

Optional execution strategy. One of SOR, VWAP, TWAP, or DMA. Defaults to SOR, the only strategy OTC common-stock orders support. VWAP and TWAP are supported only on MARKET and LIMIT orders, and DMA only on LIMIT orders; all three require DAY time-in-force. VWAP, TWAP, and DMA do not support extended_hours.

One of the following:
type OrderStrategyType struct{…}

Smart Order Router. Routes the order to the best available venue(s).

Type string

Execution strategy type.

type OrderStrategyObject struct{…}

Volume-Weighted Average Price. Works the order to track the volume-weighted average price over the execution window.

Type string

Execution strategy type.

EndAt TimeOptional

UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close.

formatdate-time
StartAt TimeOptional

UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received.

formatdate-time
type OrderStrategyObject2 struct{…}

Time-Weighted Average Price. Spreads execution evenly across the execution window.

Type string

Execution strategy type.

EndAt TimeOptional

UTC timestamp (RFC 3339) by which to finish working the order. Defaults to market close.

formatdate-time
StartAt TimeOptional

UTC timestamp (RFC 3339) at which to begin working the order. Defaults to the time the order is received.

formatdate-time
type OrderStrategyObject3 struct{…}

Direct Market Access. Routes the order straight to the named venue.

Destination string

Venue code the order is routed to.

Type string

Execution strategy type.

Symbol stringOptional

Trading symbol. For equities, use the ticker symbol (e.g., “TSLA”). For options, use the OSI symbol (e.g., “TSLA 250117C00190000”). Either symbol or instrument_id must be provided.

TrailingOffset stringOptional

Trailing offset amount (required for trailing orders)

TrailingOffsetType TrailingOffsetTypeOptional

Trailing offset type (PRICE or PERCENT_BPS)

One of the following:
const TrailingOffsetTypePrice TrailingOffsetType = "PRICE"
const TrailingOffsetTypeBps TrailingOffsetType = "BPS"
ReturnsExpand Collapse
type V1OrderPreviewOrdersResponse struct{…}
One of the following:
type OrderPreviewEntryObject struct{…}

The order was previewed successfully.

Preview OrderPreview

The projected impact of the order.

AccountID int64

The account the order was previewed for.

formatint64
Amount OrderPreviewAmount

Monetary size of the previewed order.

GrossAmount string

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

NetAmount string

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

BuyingPower OrderPreviewDelta

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 OrderPreviewDelta

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 []OrderPreviewError

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, 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.

MarginDetails OrderPreviewMarginDetails

Margin requirements and excess before and after the order.

InitialMarginExcess OrderPreviewDelta

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.

InitialMarginRequirement OrderPreviewDelta

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.

MaintenanceMarginExcess OrderPreviewDelta

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.

MaintenanceMarginRequirement OrderPreviewDelta

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.

OvernightMarginExcess OrderPreviewDelta

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.

OvernightMarginRequirement OrderPreviewDelta

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 []OrderPreviewPosition

Positions in the traded instruments before and after the order.

InstrumentID string

The instrument’s identifier.

formatuuid
Quantity OrderPreviewDelta

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 stringOptional

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.

type OrderPreviewEntryObject2 struct{…}

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

Error APIError

Why this order’s preview failed.

Code int64

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

formatint32
minimum0
Message string

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

Details []map[string, any]Optional

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

ID stringOptional

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

package main

import (
  "context"
  "fmt"

  "github.com/clear-street/clear-street-go"
  "github.com/clear-street/clear-street-go/option"
)

func main() {
  client := clearstreet.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.V1.Orders.PreviewOrders(
    context.TODO(),
    0,
    clearstreet.V1OrderPreviewOrdersParams{
      Preview: []clearstreet.NewOrderRequestParam{clearstreet.NewOrderRequestParam{
        OrderType: clearstreet.RequestOrderTypeLimit,
        Quantity: "100",
        Side: clearstreet.SideBuy,
        TimeInForce: clearstreet.RequestTimeInForceDay,
      }, clearstreet.NewOrderRequestParam{
        OrderType: clearstreet.RequestOrderTypeLimit,
        Quantity: "10",
        Side: clearstreet.SideBuy,
        TimeInForce: clearstreet.RequestTimeInForceDay,
      }},
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response)
}

{
  "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"
  }
}