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

Submit Orders

OrderSubmitOrdersResponse v1().orders().submitOrders(OrderSubmitOrdersParamsparams, RequestOptionsrequestOptions = RequestOptions.none())
POST/v1/accounts/{account_id}/orders

Submit new orders

ParametersExpand Collapse
OrderSubmitOrdersParams params
Optional<Long> accountId
List<Order> orders
class NewOrderMultilegRequest:

Multileg strategy order request

List<Leg> legs

Legs that compose the strategy.

String ratio

Ratio for the leg.

String security

Trading symbol (e.g. “AAPL” or OSI symbol for options)

Side side

Leg side.

One of the following:
BUY("BUY")
SELL("SELL")
SELL_SHORT("SELL_SHORT")
OTHER("OTHER")
Optional<String> id

Optional leg reference identifier.

Optional<PositionEffect> positionEffect

Optional leg position effect.

One of the following:
OPEN("OPEN")
CLOSE("CLOSE")

Type of order (currently MARKET or LIMIT for multileg strategy submission)

One of the following:
MARKET("MARKET")
LIMIT("LIMIT")
STOP("STOP")
STOP_LIMIT("STOP_LIMIT")
TRAILING_STOP("TRAILING_STOP")
TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")
RequestTimeInForce timeInForce

Time in force

One of the following:
DAY("DAY")
GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")
IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")
FILL_OR_KILL("FILL_OR_KILL")
GOOD_TILL_DATE("GOOD_TILL_DATE")
AT_THE_OPENING("AT_THE_OPENING")
AT_THE_CLOSE("AT_THE_CLOSE")
GOOD_TILL_CROSSING("GOOD_TILL_CROSSING")
GOOD_THROUGH_CROSSING("GOOD_THROUGH_CROSSING")
AT_CROSSING("AT_CROSSING")
Optional<String> id

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

maxLength64
Optional<String> limitPrice

Strategy price, required for LIMIT orders.

Optional<String> quantity

Optional strategy-level quantity. Multiplies leg quantities. Defaults to 1.

class NewOrderRequest:

Request to submit a new order (PlaceOrderRequest from spec)

Type of order

One of the following:
MARKET("MARKET")
LIMIT("LIMIT")
STOP("STOP")
STOP_LIMIT("STOP_LIMIT")
TRAILING_STOP("TRAILING_STOP")
TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")
String quantity

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:
BUY("BUY")
SELL("SELL")
SELL_SHORT("SELL_SHORT")
OTHER("OTHER")
RequestTimeInForce timeInForce

Time in force

One of the following:
DAY("DAY")
GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")
IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")
FILL_OR_KILL("FILL_OR_KILL")
GOOD_TILL_DATE("GOOD_TILL_DATE")
AT_THE_OPENING("AT_THE_OPENING")
AT_THE_CLOSE("AT_THE_CLOSE")
GOOD_TILL_CROSSING("GOOD_TILL_CROSSING")
GOOD_THROUGH_CROSSING("GOOD_THROUGH_CROSSING")
AT_CROSSING("AT_CROSSING")
Optional<String> id

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

maxLength64
Optional<LocalDateTime> expiresAt

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

formatdate-time
Optional<Boolean> extendedHours

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

Optional<String> instrumentId

Instrument identifier

formatuuid
Optional<String> limitOffset

Limit offset for trailing stop-limit orders (signed)

Optional<String> limitPrice

Limit price (required for LIMIT and STOP_LIMIT orders)

Optional<PositionEffect> positionEffect

Required for options. Specifies whether the order opens or closes a position.

One of the following:
OPEN("OPEN")
CLOSE("CLOSE")
Optional<String> stopPrice

Stop price (required for STOP and STOP_LIMIT orders)

Optional<String> symbol

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.

Optional<String> trailingOffset

Trailing offset amount (required for trailing orders)

Optional<TrailingOffsetType> trailingOffsetType

Trailing offset type (PRICE or PERCENT_BPS)

One of the following:
PRICE("PRICE")
BPS("BPS")
ReturnsExpand Collapse
class OrderSubmitOrdersResponse:
List<Order> data
String id

Engine-assigned unique identifier for this order (UUID).

long accountId

Account placing the order

formatint64
String clientOrderId

Client-provided identifier echoed back.

LocalDateTime createdAt

Timestamp when order was created (UTC)

formatdate-time
String filledQuantity

Cumulative filled quantity

String instrumentId

Instrument identifier for the traded instrument.

formatuuid
SecurityType instrumentType

Type of security

One of the following:
COMMON_STOCK("COMMON_STOCK")
OPTION("OPTION")
CASH("CASH")
String leavesQuantity

Remaining unfilled quantity

OrderType orderType

Type of order (MARKET, LIMIT, etc.)

One of the following:
MARKET("MARKET")
LIMIT("LIMIT")
STOP("STOP")
STOP_LIMIT("STOP_LIMIT")
TRAILING_STOP("TRAILING_STOP")
TRAILING_STOP_LIMIT("TRAILING_STOP_LIMIT")
OTHER("OTHER")
String quantity

Total order quantity

Side side

Side of the order (BUY, SELL, SELL_SHORT)

One of the following:
BUY("BUY")
SELL("SELL")
SELL_SHORT("SELL_SHORT")
OTHER("OTHER")

Current status of the order

One of the following:
PENDING_NEW("PENDING_NEW")
NEW("NEW")
PARTIALLY_FILLED("PARTIALLY_FILLED")
FILLED("FILLED")
CANCELED("CANCELED")
REJECTED("REJECTED")
EXPIRED("EXPIRED")
PENDING_CANCEL("PENDING_CANCEL")
PENDING_REPLACE("PENDING_REPLACE")
REPLACED("REPLACED")
DONE_FOR_DAY("DONE_FOR_DAY")
STOPPED("STOPPED")
SUSPENDED("SUSPENDED")
CALCULATED("CALCULATED")
OTHER("OTHER")
String symbol

Trading symbol

TimeInForce timeInForce

Time in force instruction

One of the following:
DAY("DAY")
GOOD_TILL_CANCEL("GOOD_TILL_CANCEL")
IMMEDIATE_OR_CANCEL("IMMEDIATE_OR_CANCEL")
FILL_OR_KILL("FILL_OR_KILL")
GOOD_TILL_DATE("GOOD_TILL_DATE")
AT_THE_OPENING("AT_THE_OPENING")
AT_THE_CLOSE("AT_THE_CLOSE")
GOOD_TILL_CROSSING("GOOD_TILL_CROSSING")
GOOD_THROUGH_CROSSING("GOOD_THROUGH_CROSSING")
AT_CROSSING("AT_CROSSING")
OTHER("OTHER")
LocalDateTime updatedAt

Timestamp of the most recent update (UTC)

formatdate-time
String venue

MIC code of the venue where the order is routed

Optional<String> averageFillPrice

Average fill price across all executions When a null/undefined value is observed, it indicates that there is no available data.

Optional<List<String>> details

Contains execution, rejection or cancellation details, if any

Optional<LocalDateTime> expiresAt

Timestamp when the order will expire (UTC). Present when time_in_force is GOOD_TILL_DATE. When a null/undefined value is observed, it indicates it does not apply.

formatdate-time
Optional<Boolean> extendedHours

Whether the order is eligible for extended-hours trading.

Optional<String> limitOffset

Limit offset for trailing stop-limit orders (signed) When a null/undefined value is observed, it indicates it does not apply.

Optional<String> limitPrice

Limit price (for LIMIT and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.

Optional<QueueState> queueState

Parent order queue state, present when the order is awaiting release or released. When a null/undefined value is observed, it indicates it does not apply.

One of the following:
AWAITING_RELEASE("AWAITING_RELEASE")
RELEASED("RELEASED")
Optional<LocalDateTime> releasesAt

Scheduled release time for orders awaiting release. When a null/undefined value is observed, it indicates it does not apply.

formatdate-time
Optional<String> stopPrice

Stop price (for STOP and STOP_LIMIT orders) When a null/undefined value is observed, it indicates it does not apply.

Optional<String> trailingLimitPx

Current trailing limit price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.

Optional<String> trailingOffset

Trailing offset amount for trailing orders When a null/undefined value is observed, it indicates it does not apply.

Optional<TrailingOffsetType> trailingOffsetType

Trailing offset type for trailing orders When a null/undefined value is observed, it indicates it does not apply.

One of the following:
PRICE("PRICE")
BPS("BPS")
Optional<String> trailingStopPx

Current trailing stop price computed by the trailing strategy When a null/undefined value is observed, it indicates it does not apply.

Optional<String> trailingWatermarkPx

Trailing watermark price for trailing orders When a null/undefined value is observed, it indicates it does not apply.

Optional<LocalDateTime> trailingWatermarkTs

Trailing watermark timestamp for trailing orders When a null/undefined value is observed, it indicates it does not apply.

formatdate-time
Optional<String> underlyingInstrumentId

Instrument ID of the option’s underlying instrument. Populated only for options orders. A null means one of two things: the order is not an option, so the field does not apply; or the order is an option whose underlier has not yet been resolved. When a null/undefined value is observed, it indicates it does not apply.

formatuuid

Submit Orders

package com.clearstreet.api.example;

import com.clearstreet.api.client.ClearStreetClient;
import com.clearstreet.api.client.okhttp.ClearStreetOkHttpClient;
import com.clearstreet.api.models.v1.orders.NewOrderRequest;
import com.clearstreet.api.models.v1.orders.OrderSubmitOrdersParams;
import com.clearstreet.api.models.v1.orders.OrderSubmitOrdersResponse;
import com.clearstreet.api.models.v1.orders.RequestOrderType;
import com.clearstreet.api.models.v1.orders.RequestTimeInForce;
import com.clearstreet.api.models.v1.orders.Side;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        ClearStreetClient client = ClearStreetOkHttpClient.builder()
            .fromEnv()
            .apiKey("My API Key")
            .build();

        OrderSubmitOrdersParams params = OrderSubmitOrdersParams.builder()
            .accountId(0L)
            .addOrder(NewOrderRequest.builder()
                .orderType(RequestOrderType.LIMIT)
                .quantity("1")
                .side(Side.BUY)
                .timeInForce(RequestTimeInForce.DAY)
                .build())
            .build();
        OrderSubmitOrdersResponse response = client.v1().orders().submitOrders(params);
    }
}
{
  "data": [
    {
      "account_id": 19816,
      "client_order_id": "my-ref-id-20251003-001",
      "created_at": "2025-10-03T14:01:15.000000000Z",
      "filled_quantity": "0",
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab",
      "instrument_type": "COMMON_STOCK",
      "leaves_quantity": "1",
      "order_type": "MARKET",
      "quantity": "1",
      "side": "BUY",
      "status": "PENDING_NEW",
      "symbol": "TSLA",
      "time_in_force": "DAY",
      "updated_at": "2025-10-03T14:01:15.000000000Z",
      "venue": "XNAS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "ea0b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
  }
}
{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: [0].?: expected `,` or `}` at line 11 column 3"
  },
  "metadata": {
    "request_id": "8cb2657f-828e-4af5-b7d0-5cc6b7354bc2"
  }
}
{
  "error": {
    "code": 400,
    "details": [
      {
        "description": "Buying Power: required > available",
        "subject": "order:019dba52-6611-7b53-9bc9-18c410e5ebb8",
        "type": "BUYING_POWER"
      },
      {
        "domain": "com.clearstreet.oems.risk",
        "metadata": {
          "account_id": "100001",
          "account_type": "margin_reg_t",
          "available": "11004.5000",
          "multiplier": "2",
          "order_id": "019dba52-6611-7b53-9bc9-18c410e5ebb8",
          "required_equity": "30000",
          "required_options": "0",
          "required_total": "30000",
          "side": "Buy",
          "symbol": "AAPL"
        },
        "reason": "BUYING_POWER"
      }
    ],
    "message": "Risk check failed"
  },
  "metadata": {
    "request_id": "00bf689a-f53d-47b7-8b73-f0e69d2e89b6"
  }
}
{
  "error": {
    "code": 400,
    "details": [
      {
        "description": "Self-Match: would cross own orders",
        "subject": "order:019dba51-a906-7133-aacc-ea4fc05058d8",
        "type": "SELF_MATCH"
      },
      {
        "domain": "com.clearstreet.oems.risk",
        "metadata": {
          "account_id": "100001",
          "order_id": "019dba51-a906-7133-aacc-ea4fc05058d8",
          "price": "$200",
          "side": "Sell",
          "symbol": "AAPL"
        },
        "reason": "SELF_MATCH"
      }
    ],
    "message": "Risk check failed"
  },
  "metadata": {
    "request_id": "21b77c52-2386-40a4-8955-8fa1127ff424"
  }
}
{
  "error": {
    "code": 403,
    "message": "The caller does not have permission to execute the specified operation"
  },
  "metadata": {
    "request_id": "5518f0c6-58ff-4b4a-81a5-701556d41206"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: [0]: missing field `order_type` at line 26 column 1"
  },
  "metadata": {
    "request_id": "1b2c02c3-92a1-4432-8638-e71038c105c3"
  }
}
Returns Examples
{
  "data": [
    {
      "account_id": 19816,
      "client_order_id": "my-ref-id-20251003-001",
      "created_at": "2025-10-03T14:01:15.000000000Z",
      "filled_quantity": "0",
      "id": "0195f6d0-a1b2-7c3d-8e4f-5a6b7c8d9e01",
      "instrument_id": "d4d5d6d7-e4e5-f4f5-a4a5-a6a7a8a9aaab",
      "instrument_type": "COMMON_STOCK",
      "leaves_quantity": "1",
      "order_type": "MARKET",
      "quantity": "1",
      "side": "BUY",
      "status": "PENDING_NEW",
      "symbol": "TSLA",
      "time_in_force": "DAY",
      "updated_at": "2025-10-03T14:01:15.000000000Z",
      "venue": "XNAS"
    }
  ],
  "error": null,
  "metadata": {
    "request_id": "ea0b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d"
  }
}
{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: [0].?: expected `,` or `}` at line 11 column 3"
  },
  "metadata": {
    "request_id": "8cb2657f-828e-4af5-b7d0-5cc6b7354bc2"
  }
}
{
  "error": {
    "code": 400,
    "details": [
      {
        "description": "Buying Power: required > available",
        "subject": "order:019dba52-6611-7b53-9bc9-18c410e5ebb8",
        "type": "BUYING_POWER"
      },
      {
        "domain": "com.clearstreet.oems.risk",
        "metadata": {
          "account_id": "100001",
          "account_type": "margin_reg_t",
          "available": "11004.5000",
          "multiplier": "2",
          "order_id": "019dba52-6611-7b53-9bc9-18c410e5ebb8",
          "required_equity": "30000",
          "required_options": "0",
          "required_total": "30000",
          "side": "Buy",
          "symbol": "AAPL"
        },
        "reason": "BUYING_POWER"
      }
    ],
    "message": "Risk check failed"
  },
  "metadata": {
    "request_id": "00bf689a-f53d-47b7-8b73-f0e69d2e89b6"
  }
}
{
  "error": {
    "code": 400,
    "details": [
      {
        "description": "Self-Match: would cross own orders",
        "subject": "order:019dba51-a906-7133-aacc-ea4fc05058d8",
        "type": "SELF_MATCH"
      },
      {
        "domain": "com.clearstreet.oems.risk",
        "metadata": {
          "account_id": "100001",
          "order_id": "019dba51-a906-7133-aacc-ea4fc05058d8",
          "price": "$200",
          "side": "Sell",
          "symbol": "AAPL"
        },
        "reason": "SELF_MATCH"
      }
    ],
    "message": "Risk check failed"
  },
  "metadata": {
    "request_id": "21b77c52-2386-40a4-8955-8fa1127ff424"
  }
}
{
  "error": {
    "code": 403,
    "message": "The caller does not have permission to execute the specified operation"
  },
  "metadata": {
    "request_id": "5518f0c6-58ff-4b4a-81a5-701556d41206"
  }
}
{
  "error": {
    "code": 422,
    "message": "Failed to deserialize the JSON body into the target type: [0]: missing field `order_type` at line 26 column 1"
  },
  "metadata": {
    "request_id": "1b2c02c3-92a1-4432-8638-e71038c105c3"
  }
}