Sign in

v1

latestOpenAPI 3.0.02026-07-26166415635.8 KB
Trading

Create an Order for an Account

Creating an order for your end customer. Each trading request must pass in the account_id in the URL.

  • Note that when submitting crypto orders, market, limit and stop_limit orders are supported while the supported time_in_force values are gtc, and ioc.
  • For equities and crypto we accept fractional orders as well with either notional or qty provided.
  • Note that submitting an options order is only available for partners who have been enabled for Options BETA.
  • In case of Fixed Income, only market and limit order types with day time_in_force are supported, and order replacement is not supported. Note that submitting Fixed Income orders is only available for partners who have been enabled for Fixed Income.
  • Note that submitting DMA orders (using advanced_instructions with algorithm: DMA) is only available for partners/correspondents who have been enabled for DMA.
  • For IPO indications of interest (asset_class: "ipo"), the symbol is the offering reference returned by GET /v1/ipos (e.g. FI111225). IPO orders are notional-only (notional required, qty must be omitted), buy-side, market type, and gtc time_in_force. Indications of interest can be replaced or canceled while the offering is open via PATCH /v1/trading/accounts/{account_id}/orders/{order_id} and DELETE /v1/trading/accounts/{account_id}/orders/{order_id}.
post/v1/trading/accounts/{account_id}/orders

Request body

client_order_idstring

A unique identifier for the order. Automatically generated if not sent. (<= 128 characters)

commissionstring decimal

The commission you want to collect from the user.

commission_bpsstring decimal

deprecated: Please use the commission_type = bps instead and set the desired bps value in the commission field. The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission.

commission_type'notional' | 'qty' | 'bps'

An enum to select how to interpret the value provided in the commission field.

  • notional: Charge commission on a per order basis. (When the commission_type field is omitted from the order request, this is used as the default).

  • qty: Charge commission on a per qty/contract basis, pro rated.

  • bps: The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission. Commission value in bps can have up to two decimal places.

extended_hoursboolean

Defaults to false. If true, order will be eligible for execution in the pre-market, after-hours, and overnight sessions. Only works with type limit and time_in_force set to either day or gtc.

instructionsstring
limit_pricestring decimal

Required if type is limit or stop_limit.

  • In case of mleg, the limit_price parameter is expressed with the following notation:
    • A positive value indicates a debit, representing a cost or payment to be made.
    • A negative value signifies a credit, reflecting an amount to be received.
  • In case of Fied Income, the price is expressed in percentage of par value (face value). Price is always clean price, meaning it does not include accrued interest.
notionalstring decimal

Dollar amount to trade. Cannot work with qty. Only market and limit orders supported with time_in_force = day; Only limit orders for extended hours.

order_class'simple' | 'bracket' | 'oco' | 'oto' | 'mleg' | ''

The order classes supported by Alpaca vary based on the order's security type. The following provides a comprehensive breakdown of the supported order classes for each category:

  • Equity trading: simple (or ""), oco, oto, bracket.
  • Options trading:
    • simple (or "")
    • mleg (required for multi-leg complex option strategies)
  • Crypto trading: simple (or "").
position_intent'buy_to_open' | 'buy_to_close' | 'sell_to_open' | 'sell_to_close'

Represents the desired position strategy.

qtystring decimal
  • For equities, the number of shares to trade. Can be fractionable for only market and day order types.
  • Required for mleg order class, represents the number of units to trade of this strategy.
  • For Fixed Income securities, qty represents the order size in par value (face value). For example, to place an order for 1 bond with a face value of $1,000, provide a qty of 1000.
side'buy' | 'sell' | 'buy_minus' | 'sell_plus' | 'sell_short' | 'sell_short_exempt' | 'undisclosed' | 'cross' | 'cross_short'

Represents what side of the transaction an order was on. Required for all order classes except for mleg.

sourcestring
stop_pricestring decimal

Required if type is stop or stop_limit

subtagstring
swap_fee_bpsstring decimal
symbolstring

Symbol or asset ID to identify the asset to trade. Required for all order classes except for mleg.

time_in_force'day' | 'gtc' | 'opg' | 'cls' | 'ioc' | 'fok' required

The Time-In-Force values supported by Alpaca vary based on the order's security type. Here is a breakdown of the supported TIFs for each specific security type:

  • Equity trading: day, gtc, opg, cls, ioc, fok.
  • Options trading: day.
  • Crypto trading: gtc, ioc.

Below are the descriptions of each TIF:

  • day: A day order is eligible for execution only on the day it is live. By default, the order is only valid during Regular Trading Hours (9:30am - 4:00pm ET). If unfilled after the closing auction, it is automatically canceled. If submitted after the close, it is queued and submitted the following trading day. However, if marked as eligible for extended hours, the order can also execute during supported extended hours.

  • gtc: The order is good until canceled. Non-marketable GTC limit orders are subject to price adjustments to offset corporate actions affecting the issue. We do not currently support Do Not Reduce (DNR) orders to opt out of such price adjustments.

  • opg: Use this TIF with a market/limit order type to submit "market on open" (MOO) and "limit on open" (LOO) orders. This order is eligible to execute only in the market opening auction. Any unfilled orders after the open will be cancelled. OPG orders submitted after 9:28am but before 7:00pm ET will be rejected. OPG orders submitted after 7:00pm will be queued and routed to the following day's opening auction. On open/on close orders are routed to the primary exchange. Such orders do not necessarily execute exactly at 9:30am / 4:00pm ET but execute per the exchange's auction rules.

  • cls: Use this TIF with a market/limit order type to submit "market on close" (MOC) and "limit on close" (LOC) orders. This order is eligible to execute only in the market closing auction. Any unfilled orders after the close will be cancelled. CLS orders submitted after 3:50pm but before 7:00pm ET will be rejected. CLS orders submitted after 7:00pm will be queued and routed to the following day's closing auction.

  • ioc: An Immediate Or Cancel (IOC) order requires all or part of the order to be executed immediately. Any unfilled portion of the order is canceled. Most market makers who receive IOC orders will attempt to fill the order on a principal basis only, and cancel any unfilled balance. On occasion, this can result in the entire order being cancelled if the market maker does not have any existing inventory of the security in question.

  • fok: A Fill or Kill (FOK) order is only executed if the entire order quantity can be filled, otherwise the order is canceled.

trail_percentstring decimal

If type is trailing_stop, then one of trail_price or trail_percent is required

trail_pricestring decimal

If type is trailing_stop, then one of trail_price or trail_percent is required

type'market' | 'limit' | 'stop' | 'stop_limit' | 'trailing_stop' required

The order types supported by Alpaca vary based on the order's security type. The following provides a comprehensive breakdown of the supported order types for each category:

  • Equity trading: market, limit, stop, stop_limit, trailing_stop.
  • Options trading: market, limit.
  • Options Multileg trading: market, limit.
  • Crypto trading: market, limit, stop_limit.

Example request

{
  "advanced_instructions": {
    "algorithm": "DMA",
    "destination": "IEX",
    "display_qty": "100"
  },
  "client_order_id": "eb9e2aaa-f71a-4f51-b5b4-52a6c565dad4",
  "commission": "1.0",
  "commission_bps": "10",
  "commission_type": "qty",
  "legs": [
    {
      "position_intent": "buy_to_open",
      "ratio_qty": "1",
      "side": "buy"
    }
  ],
  "limit_price": "3.14",
  "notional": "3",
  "position_intent": "buy_to_open",
  "qty": "4.124",
  "side": "buy",
  "stop_loss": {
    "limit_price": "3.14",
    "stop_price": "3.14"
  },
  "stop_price": "3.14",
  "symbol": "AAPL",
  "take_profit": {
    "limit_price": "3.14"
  },
  "time_in_force": "gtc",
  "trail_percent": "5.0",
  "trail_price": "3.14",
  "type": "market"
}

Response

OK

asset_class'us_equity' | 'us_option' | 'crypto' | 'ipo'

This represents the category to which the asset belongs to. It serves to identify the nature of the financial instrument, with options including "us_equity" for U.S. equities, "us_option" for U.S. options, "crypto" for cryptocurrencies, and "ipo" for IPO indications of interest. This asset_class: ipo value is distinct from the assets API attributes: ["ipo"] flag.

asset_idstring uuid

The asset ID (For options this represents the option contract ID)

cancel_requested_atstring date-time nullable

Time when cancellation or bust was requested (if applicable)

canceled_atstring date-time nullable

Can be null

client_order_idstring

Client unique order ID

commissionstring decimal

The dollar value commission for this order.

commission_bpsstring decimal

deprecated: Please use the commission_type = bps instead and set the desired bps value in the commission field. The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission.

commission_type'notional' | 'qty' | 'bps'

An enum to select how to interpret the value provided in the commission field.

  • notional: Charge commission on a per order basis. (When the commission_type field is omitted from the order request, this is used as the default).

  • qty: Charge commission on a per qty/contract basis, pro rated.

  • bps: The percent commission you want to charge the end user on the order (expressed in bps). Alpaca will convert the order to a notional amount for purposes of calculating commission. Commission value in bps can have up to two decimal places.

created_atstring date-time

Time when order was entered

expired_atstring date-time nullable

Can be null

extended_hoursboolean
failed_atstring date-time nullable

Can be null

filled_atstring date-time nullable

Time the order was filled. Can be null if not filled

filled_avg_pricestring decimal nullable

Filled average price. Can be 0 until order is processed in case order is passed outside of market hours

filled_qtystring decimal

Filled quantity

hwmstring decimal nullable

The highest (lowest) market price seen since the trailing stop order was submitted.

idstring uuid required

Order ID generated by Alpaca

limit_pricestring decimal nullable

Limit price

notionalstring decimal nullable

Ordered notional amount. If entered, qty will be null. Can take up to 2 decimal points.

order_class'simple' | 'bracket' | 'oco' | 'oto' | 'mleg' | ''

The order classes supported by Alpaca vary based on the order's security type. The following provides a comprehensive breakdown of the supported order classes for each category:

  • Equity trading: simple (or ""), oco, oto, bracket.
  • Options trading:
    • simple (or "")
    • mleg (required for multi-leg complex option strategies)
  • Crypto trading: simple (or "").
order_type'market' | 'limit' | 'stop' | 'stop_limit' | 'trailing_stop'

The order types supported by Alpaca vary based on the order's security type. The following provides a comprehensive breakdown of the supported order types for each category:

  • Equity trading: market, limit, stop, stop_limit, trailing_stop.
  • Options trading: market, limit.
  • Options Multileg trading: market, limit.
  • Crypto trading: market, limit, stop_limit.
position_intent'buy_to_open' | 'buy_to_close' | 'sell_to_open' | 'sell_to_close'

Represents the desired position strategy.

qtystring decimal nullable

Ordered quantity. If entered, notional will be null. Can take up to 2 decimal points.

replaced_atstring date-time nullable

Can be null

replaced_bystring uuid nullable

The order ID that this order was replaced by. (Can be null)

replacesstring uuid nullable

The order ID that this order replaces. (Can be null)

side'buy' | 'sell' | 'buy_minus' | 'sell_plus' | 'sell_short' | 'sell_short_exempt' | 'undisclosed' | 'cross' | 'cross_short'

Represents what side of the transaction an order was on. Required for all order classes except for mleg.

status'new' | 'partially_filled' | 'filled' | 'done_for_day' | 'canceled' | 'expired' | 'replaced' | 'pending_cancel' | 'pending_replace' | 'accepted' | 'pending_new' | 'accepted_for_bidding' | 'stopped' | 'rejected' | 'suspended' | 'calculated'
stop_pricestring decimal nullable

Stop price

submitted_atstring date-time

Time the order was submitted for execution or, if not yet submitted the created_at time. Because orders are submitted for execution asynchronous to database updates, at times this may be before the created_at time.

swap_fee_bpsstring

Fee in basis points on top swap rate charged by the correspondent on every order

swap_ratestring

Swap rate is the exchange rate (without mark-up) used to convert the price into local currency or crypto asset

symbolstring required

The asset symbol

time_in_force'day' | 'gtc' | 'opg' | 'cls' | 'ioc' | 'fok'

The Time-In-Force values supported by Alpaca vary based on the order's security type. Here is a breakdown of the supported TIFs for each specific security type:

  • Equity trading: day, gtc, opg, cls, ioc, fok.
  • Options trading: day.
  • Crypto trading: gtc, ioc.

Below are the descriptions of each TIF:

  • day: A day order is eligible for execution only on the day it is live. By default, the order is only valid during Regular Trading Hours (9:30am - 4:00pm ET). If unfilled after the closing auction, it is automatically canceled. If submitted after the close, it is queued and submitted the following trading day. However, if marked as eligible for extended hours, the order can also execute during supported extended hours.

  • gtc: The order is good until canceled. Non-marketable GTC limit orders are subject to price adjustments to offset corporate actions affecting the issue. We do not currently support Do Not Reduce (DNR) orders to opt out of such price adjustments.

  • opg: Use this TIF with a market/limit order type to submit "market on open" (MOO) and "limit on open" (LOO) orders. This order is eligible to execute only in the market opening auction. Any unfilled orders after the open will be cancelled. OPG orders submitted after 9:28am but before 7:00pm ET will be rejected. OPG orders submitted after 7:00pm will be queued and routed to the following day's opening auction. On open/on close orders are routed to the primary exchange. Such orders do not necessarily execute exactly at 9:30am / 4:00pm ET but execute per the exchange's auction rules.

  • cls: Use this TIF with a market/limit order type to submit "market on close" (MOC) and "limit on close" (LOC) orders. This order is eligible to execute only in the market closing auction. Any unfilled orders after the close will be cancelled. CLS orders submitted after 3:50pm but before 7:00pm ET will be rejected. CLS orders submitted after 7:00pm will be queued and routed to the following day's closing auction.

  • ioc: An Immediate Or Cancel (IOC) order requires all or part of the order to be executed immediately. Any unfilled portion of the order is canceled. Most market makers who receive IOC orders will attempt to fill the order on a principal basis only, and cancel any unfilled balance. On occasion, this can result in the entire order being cancelled if the market maker does not have any existing inventory of the security in question.

  • fok: A Fill or Kill (FOK) order is only executed if the entire order quantity can be filled, otherwise the order is canceled.

trail_percentstring decimal nullable

The percent value away from the high water mark for trailing stop orders.

trail_pricestring decimal nullable

The dollar value away from the high water mark for trailing stop orders.

type'market' | 'limit' | 'stop' | 'stop_limit' | 'trailing_stop'

The order types supported by Alpaca vary based on the order's security type. The following provides a comprehensive breakdown of the supported order types for each category:

  • Equity trading: market, limit, stop, stop_limit, trailing_stop.
  • Options trading: market, limit.
  • Options Multileg trading: market, limit.
  • Crypto trading: market, limit, stop_limit.
updated_atstring date-time

Time of most recent change to the order

usdobject

Nested object to encompass the USD equivalent fields for the local currency fields

Example response

{
  "asset_id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "cancel_requested_at": "2021-03-16T18:38:01.942282Z",
  "canceled_at": "2021-03-16T18:38:01.942282Z",
  "client_order_id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "commission": "3.14",
  "commission_bps": "10",
  "commission_type": "qty",
  "created_at": "2021-03-16T18:38:01.942282Z",
  "expired_at": "2021-03-16T18:38:01.942282Z",
  "extended_hours": true,
  "failed_at": "2021-03-16T18:38:01.942282Z",
  "filled_at": "2021-03-16T18:38:01.942282Z",
  "filled_avg_price": "4.2",
  "filled_qty": "4.2",
  "hwm": "3.14",
  "id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "legs": [
    {
      "asset_id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
      "canceled_at": "2021-03-16T18:38:01.942282Z",
      "client_order_id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
      "commission": "3.14",
      "commission_bps": "10",
      "commission_type": "qty",
      "created_at": "2021-03-16T18:38:01.942282Z",
      "expired_at": "2021-03-16T18:38:01.942282Z",
      "extended_hours": true,
      "failed_at": "2021-03-16T18:38:01.942282Z",
      "filled_at": "2021-03-16T18:38:01.942282Z",
      "filled_avg_price": "4.2",
      "filled_qty": "4.2",
      "hwm": "3.14",
      "id": "61e69015-8549-4bfd-b9c3-01e75843f47d",
      "limit_price": "3.14",
      "notional": "4.2",
      "order_type": "market",
      "position_intent": "buy_to_open",
      "qty": "4.2",
      "replaced_at": "2021-03-16T18:38:01.942282Z",
      "replaced_by": "61e69015-8549-4bfd-b9c3-01e75843f47d",
      "replaces": "61e69015-8549-4bfd-b9c3-01e75843f47d",
      "side": "buy",
      "status": "filled",
      "stop_price": "3.14",
      "submitted_at": "2021-03-16T18:38:01.942282Z",
      "symbol": "AALP",
      "time_in_force": "gtc",
      "trail_percent": "5.0",
      "trail_price": "3.14",
      "type": "market",
      "updated_at": "2021-03-16T18:38:01.942282Z"
    }
  ],
  "limit_price": "3.14",
  "notional": "4.2",
  "order_type": "market",
  "position_intent": "buy_to_open",
  "qty": "4.2",
  "replaced_at": "2021-03-16T18:38:01.942282Z",
  "replaced_by": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "replaces": "61e69015-8549-4bfd-b9c3-01e75843f47d",
  "side": "buy",
  "status": "filled",
  "stop_price": "3.14",
  "submitted_at": "2021-03-16T18:38:01.942282Z",
  "symbol": "AALP",
  "time_in_force": "gtc",
  "trail_percent": "5.0",
  "trail_price": "3.14",
  "type": "market",
  "updated_at": "2021-03-16T18:38:01.942282Z"
}