TradeZero MCP Tool Reference
Reference for all 21 tools on TradeZero MCP (Model Context Protocol). OAuth setup is in the TradeZero MCP setup guide. Each tool is marked read-only or write so your client can require approval before account changes. This page documents parameters, access levels, and the create_order schema.
21 tools - 14 reads, 7 writes (6 destructive; locate_quote is a write but free until accept).
What you can do
Available
- Accounts, balances, P&L, positions, cash history
- Today's orders - place, read, cancel
- Equities, options, multi-leg spreads
- Short locates (live writes; reads on any account)
The hosted MCP server does not stream quotes, options chains, or charts. If an assistant cites a price, it did not come from TradeZero - supply your own limit on orders.
How to read these tables
| Marker | Meaning |
|---|---|
| Read | Data only |
| Write | Places, cancels, or commits on your account |
| Approval: Recommended | Fine to allow; prompts cost nothing |
| Approval: Required | Do not enable "always allow" |
Writes are listed in Tools that can move money. MCP clients prompt on tool calls by default, including reads. Agent modes can skip prompts - do not grant blanket approval on write operations.
Calling conventions
Wire rules that apply across TradeZero MCP tools. Miss these and you get 400, empty history, or a silent queue ack.
| Topic | Rule |
|---|---|
| Required-but-null fields | Send the key with null when you want the default. Omitting the key fails validation. |
| Enums | Case-sensitive. Send Buy, Limit, Mleg - not lowercase. Route metadata may list MLEG; create_order still expects Mleg. |
| Quantities | orderQuantity and locate quantity must be whole integers. |
| Field names | Exact spelling. account vs accountId and quoteReqId vs quoteReqID reject when wrong. Extra keys on create_order are ignored. |
quoteReqId | Fresh id on locate_quote and sell_locate. Reuse that same id on accept_locate / cancel_locate. Duplicates return R114. |
| Locate acks | *Sent: true means queued, not done. Confirm in get_locate_history (responses use quoteReqID). |
| Order fields | Request body uses stopPrice; responses echo priceStop. A successful create_order is acceptance, not a fill - read orderStatus. |
| After writes | Poll in 1–2 seconds. Rate limits apply. |
Lost create_order response | Check get_todays_orders. Do not reuse the same clientOrderId. |
Short locates
locate_quote, accept_locate, cancel_locate, and sell_locate need a live account. Reads work on paper too.
Details: Short Locates.
Try Is BB easy to borrow right now? · Quote me 500 shares of BB and show the cost of each offer. · What's still in my locate inventory today?
| Tool | What it does | Access | Approval |
|---|---|---|---|
is_easy_to_borrow | ETB check | Read | Recommended |
get_locate_inventory | Active inventory today | Read | Recommended |
get_locate_history | Day history with statuses | Read | Recommended |
locate_quote | Request quote | Write | Required |
accept_locate | Accept quote (fee) | Write | Required |
cancel_locate | Cancel quote or pending sell-back | Write | Required |
sell_locate | Sell unused inventory | Write | Required |
Reads: accountId (+ symbol on ETB). Writes:
| Tool | Account field | quoteReqId | Also required |
|---|---|---|---|
locate_quote | account | Fresh | symbol, quantity |
accept_locate | accountId | Same as quote | - |
cancel_locate | accountId | Same as row | - |
sell_locate | account | Fresh | symbol, quantity, locateType |
locateType on sell-back: Unknown, Locate, IntraDay, PreBorrow, SingleUse.
locateStatus | Meaning | Next step |
|---|---|---|
65 | Offered | Accept or cancel within ~30s |
50 | Filled | Check inventory |
52 | Canceled | Re-quote if needed |
56 | Rejected | Read text |
67 | Expired | Re-quote |
48 | Sell-back queued | Status codes |
Accounts and P&L
Try Show me my buying power and tell me whether I'm on paper or live. · How is my portfolio's P&L looking today? · Which TradeZero accounts can I trade?
| Tool | What it does | Access | Approval |
|---|---|---|---|
list_accounts | All tradable accounts - start here for accountId | Read | Recommended |
get_account | One-account snapshot (buying power, option level, tradingSuspended) | Read | Recommended |
get_account_pnl | Account + per-position P&L | Read | Recommended |
list_accounts - no args. get_account / get_account_pnl - accountId (string).
Useful list_accounts fields: accountType, buyingPower, tradingSuspended, optLevel, fractional. Rejections from suspended accounts or insufficient option level show in create_order text - see Order Rejections.
Positions
Try What positions am I holding right now? · Show me closed trades from today with realized P&L.
| Tool | What it does | Access | Approval |
|---|---|---|---|
get_positions | Open lots (no unrealized P&L - use get_account_pnl) | Read | Recommended |
get_closed_positions | Closed lifecycles + realized P&L | Read | Recommended |
Both require accountId. Open positionId is a string; closed is a number. One row per lot - ignore zero-qty rows when summing.
Orders
Try What open orders do I have right now? · Cancel my open AAPL order. · Place a limit buy for 100 shares of AAPL at $180. · Explain why my last order was rejected.
| Tool | What it does | Access | Approval |
|---|---|---|---|
get_routes | Routes, order types, TIFs | Read | Recommended |
get_todays_orders | Today's order book (all statuses) + working multi-day GTCs | Read | Recommended |
get_order | One order - pass clientOrderId as orderId | Read | Recommended |
get_historical_orders | Fill history from startDate, up to ~1 week | Read | Recommended |
get_historical_orders_paginated | Same, paginated (~1 year); filters in queryString | Read | Recommended |
create_order | Place equity, option, or spread | Write | Required |
cancel_order | Cancel by clientOrderId | Write | Required |
cancel_all_orders | Cancel all working (optional symbol filter) | Write | Required |
Arguments: reads need accountId; get_order also takes orderId (= clientOrderId); history tools also take startDate (paginated adds optional queryString). Writes: cancel_order needs accountId + clientOrderId; cancel_all_orders needs accountId and symbol (null = all symbols). After the open-auction cutoff, AtTheOpening orders cannot be cancelled - see AtTheOpening (OPG).
cancel_all_orderssymbol: null cancels every working order on the account. Use a ticker to scope, or cancel one at a time.
Which orders tool to use
- Session book / live blotter:
get_todays_orders/get_order - Fill archives:
get_historical_orders(~1 week) orget_historical_orders_paginated(~1 year) - same fill-level shape as REST historical orders - Before live placement: call
get_routesand copy the route name exactly (SMART/CTDL/ARCAequities,SMARTOoptions,SMARTMspreads; paper:PAPER/PAPERM)
Route metadata can list order types that create_order rejects - placeable set is Market / Limit / Stop / StopLimit only (Route metadata vs place-order). Side + openClose together set buy/sell/short/cover - not side alone.
create_order
Try Buy to open one AAPL call - I will give you the OCC symbol and a $2.50 limit. · Build a vertical spread on AAPL and show me the legs before you submit.
All fields required; null when unused.
| Field | Type | Send |
|---|---|---|
accountId | string | From list_accounts |
symbol | string | Ticker, compact OCC, or underlying for Mleg |
side | string | null | Buy/Sell; null for Mleg |
orderType | string | Market, Limit, Stop, StopLimit |
securityType | string | Stock, Option, Mleg |
timeInForce | string | Must match route - equity SMART rules on Order types, times in force, and session hours |
orderQuantity | integer | Whole shares / spread units |
openClose | string | null | Open/Close; null for Mleg |
limitPrice | number | null | Limit / StopLimit / Mleg net price |
stopPrice | number | null | Stop types → response priceStop |
route | string | null | From get_routes; send on live |
clientOrderId | string | null | Your id for cancel/lookup; fresh per order |
legsJson | string | null | JSON array string for Mleg only |
Single-leg options: compact OCC on symbol; see Options. Multi-leg: legsJson → REST legs[]; illustrative example:
{"securityType":"Mleg","symbol":"AAPL","side":null,"openClose":null,"orderType":"Limit","limitPrice":2.5,"orderQuantity":1,"timeInForce":"Day","route":"SMARTM","legsJson":"[{\"symbol\":\"AAPL991231C00100000\",\"side\":\"Buy\",\"openClose\":\"Open\",\"ratio\":1},{\"symbol\":\"AAPL991231C00200000\",\"side\":\"Sell\",\"openClose\":\"Open\",\"ratio\":1}]"}
Order responses
Poll get_order until terminal. Flow: list_accounts → get_routes → create_order → get_order.
orderStatus | Terminal | Notes |
|---|---|---|
PendingNew, PartiallyFilled, New, PendingCancel | No | Poll |
Filled | Yes | Use priceAvg |
Canceled, Rejected | Yes | Read text (R-codes) |
Other (Expired, Replaced, DoneForDay) | Treat as non-terminal until stable |
Key fields: clientOrderId, orderStatus, text, orderType, tradedSymbol (prefer over symbol on fills), executed, leavesQuantity, priceAvg, limitPrice, priceStop, canceledQuantity.
Do not cancel a Rejected order (R130). Market responses can show limitPrice - trust orderType.
Cash
Try Show me cash transactions from this month. · How much did I pay in locate fees this week?
| Tool | What it does | Access | Approval |
|---|---|---|---|
get_cash_transactions | Paginated ledger (up to 1 year) | Read | Recommended |
accountId, startDate, plus numberOfDays, limit, offset (all required - pass null for defaults 30 / 100 / 0).
Tools that can move money
| Tool | Effect |
|---|---|
create_order | Order to market |
cancel_order | Withdraw one order |
cancel_all_orders | Withdraw all working (optional symbol) |
locate_quote | Quote only - no fee |
accept_locate | Locate fee |
cancel_locate | Cancel quote / sell-back |
sell_locate | Credit unused inventory |