alpaca-mcp-server

Official

Overview Schema Source Related Servers Discussions Admin

replace_order_by_id

Modify an open order's parameters, such as quantity or limit price, by providing the order ID and at least one updated field. Adjust existing orders without canceling and resubmitting.

Instructions

Replaces an existing open order with updated parameters. At least one optional field must be provided.

Input Schema

TableJSON Schema

Name	Required	Description
`qty`	No	number of shares to trade. You can only patch full shares for now. Qty of equity fractional orders are not allowed to change. Non-IPO notional orders cannot be replaced at all - no fields (qty, limit_price, stop_price, etc.) can be modified; cancel and resubmit instead.
`trail`	No	the new value of the trail_price or trail_percent value (works only for type="trailing_stop")
`notional`	No	New notional (dollar amount) for the order. Only valid for IPO indications of interest (`asset_class: "ipo"`); will be rejected for any other asset class. Mutually exclusive with `qty` on the same replace request.
`order_id`	Yes	order id
`stop_price`	No	required if original order type is limit or stop_limit
`limit_price`	No	Required if original order's `type` field was `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.
`time_in_force`	No	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. Only available with API v2. - 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. Only available with API v2. 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. Only available with API v2.
`client_order_id`	No	A unique identifier for the new order. Automatically generated if not sent. (<= 128 characters)
`advanced_instructions`	No	Advanced instructions for Elite Smart Router: https://docs.alpaca.markets/docs/alpaca-elite-smart-router

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv2.3.2Sep 18, 2026

addedInput schema / properties / advanced_instructions / examples

Added value: +[
+  {
+    "algorithm": "DMA",
+    "destination": "NYSE",
+    "display_qty": "100"
+  },
+  {
+    "algorithm": "TWAP",
+    "end_time": "2025-07-21T15:30:00-04:00",
+    "max_percentage": "0.314",
+    "start_time": "2025-07-21T09:30:00-04:00"
+  },
+  {
+    "algorithm": "VWAP",
+    "end_time": "2025-07-21T15:30:00-04:00",
+    "max_percentage": "0.314",
+    "start_time": "2025-07-21T09:30:00-04:00"
+  }
+]

changedInput schema / properties / advanced_instructions / properties / destination / enum

Previous value: -[
-  "NYSE",
-  "NASDAQ",
-  "ARCA"
-]New value: +[
+  "NYSE",
+  "NASDAQ",
+  "ARCA",
+  "IEX",
+  "MEMX"
+]

removedInput schema / properties / advanced_instructions / x-examples

Removed value: -{
-  "example-1": {
-    "algorithm": "DMA",
-    "destination": "NYSE",
-    "display_qty": 100
-  },
-  "example-2": {
-    "algorithm": "TWAP",
-    "end_time": "2025-07-21T15:30:00-04:00",
-    "max_percentage": 0.314,
-    "start_time": "2025-07-21T09:30:00-04:00"
-  },
-  "example-3": {
-    "algorithm": "VWAP",
-    "end_time": "2025-07-21T15:30:00-04:00",
-    "max_percentage": 0.314,
-    "start_time": "2025-07-21T09:30:00-04:00"
-  }
-}

addedInput schema / properties / notional

Added value: +{
+  "description": "New notional (dollar amount) for the order. Only valid for IPO indications of interest (`asset_class: \"ipo\"`); will be rejected for any other asset class.\nMutually exclusive with `qty` on the same replace request.",
+  "example": "750",
+  "type": "string"
+}

changedInput schema / properties / qty / description

Previous value: -"number of shares to trade.\n\nYou can only patch full shares for now.\n\nQty of equity fractional/notional orders are not allowed to change."New value: +"number of shares to trade.\n\nYou can only patch full shares for now.\n\nQty of equity fractional orders are not allowed to change. Non-IPO notional orders cannot be replaced at all - no fields (qty, limit_price, stop_price, etc.) can be modified; cancel and resubmit instead."

changedInput schema / properties / time_in_force / description

Previous value: -"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:\n- Equity trading: day, gtc, opg, cls, ioc, fok.\n- Options trading: day.\n- Crypto trading: gtc, ioc.\n\nBelow are the descriptions of each TIF:\n- day:\n  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.\n\n- gtc:\n  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.\n\n- opg:\n  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.\n\n- cls:\n  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. Only available with API v2.\n\n- ioc:\n  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. Only available with API v2. 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.\n\n- fok:\n  A Fill or Kill (FOK) order is only executed if the entire order quantity can be filled, otherwise the order is canceled. Only available with API v2."New value: +"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:\n- Equity trading: day, gtc, opg, cls, ioc, fok.\n- Options trading: day.\n- Crypto trading: gtc, ioc.\n\nBelow are the descriptions of each TIF:\n- day:\n  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.\n\n- gtc:\n  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.\n\n- opg:\n  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.\n\n- cls:\n  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. Only available with API v2.\n\n- ioc:\n  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. Only available with API v2. 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.\n\n- fok:\n  A Fill or Kill (FOK) order is only executed if the entire order quantity can be filled, otherwise the order is canceled. Only available with API v2."

changedInput schema / properties / trail / description

Previous value: -"the new value of the trail_price or trail_percent value (works only for type=“trailing_stop”)"New value: +"the new value of the trail_price or trail_percent value (works only for type=\"trailing_stop\")"

Addedv2.0.0Apr 15, 2026

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and the 'at least one optional field' constraint; it does not disclose that replacing may cancel the old order, that certain order types (e.g., non-IPO notional) cannot be replaced at all, or what side effects or errors to expect. Key behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences with zero filler: the action is front-loaded, and the key constraint is stated immediately. Every word earns its place, making it an exemplary concise definition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a complex tool with 9 parameters, nested objects, and asset-class-specific rules (e.g., IPO notional, trailing stops, mleg notations). The description does not mention critical restrictions like 'non-IPO notional orders cannot be replaced' or that limit_price/stop_price may be required based on the original order type. While the output schema and rich parameter descriptions cover some details, the main description is insufficient for such a nuanced mutation operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful cross-parameter semantics by stating 'At least one optional field must be provided', a constraint not encoded in the schema's required/optional structure. This helps agents avoid sending a no-op request, justifying a score above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Replaces') and a clear resource ('existing open order'), immediately differentiating it from order creation or cancellation tools among the siblings. However, it does not explicitly name or contrast with sibling alternatives like 'place_stock_order' or 'cancel_order_by_id', so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'existing open order' implies the tool is for modifying already-placed orders rather than creating or canceling them, but there is no explicit guidance on when to use this versus alternatives such as placing a new order or canceling and resubmitting. No exclusions, prerequisites, or alternative tool references are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server