Skip to main content

User API: Closing Open Bot Trades

Last updated November 18, 2026

This article is the reference for closing open bot trades through the User API: one trade, every open trade of one bot, or every open trade of a strategy, of a broker account or of your whole account. A close does what the Close button on tradeSteward does: it marks each trade to be closed, and the trading engine places the closing orders on its next cycle.

Every path is under https://api.tradesteward.com/rest/v1, every request carries Authorization: Bearer <token> and, for a body, Content-Type: application/json. Every answer is the JSON envelope from Your First Request; the examples show only data.

Permission: trades.close (Close open bot trades). API clients only, off by default, needs Trader Unlimited. Waits for your approval unless you turn that off for the client.

Rules that apply to every close

Who can close trades

Only your own code can close trades, through an API client over REST. A connected AI app is never offered this permission, and no MCP tool closes a trade. On a plan below Trader Unlimited the request answers 403 entitlement_required, with where to upgrade, as the other requests that change live trading do (see Creating, Changing and Switching Bots).

What a close does, and what it does not

  • A close marks each open trade to be closed in full. A 200 means the close was requested, not that an order was placed or filled. Read the trade's bot to follow it.
  • Opening orders that are still working are not cancelled, and a bot that is on can open a new trade later. To stop new trades, turn the bot off or pause trading first.
  • Trades can be closed only while the market is open. Outside market hours the request answers 409 market_closed, and nothing waits for your approval.
  • A close requested just before the trading engine stops managing trades for the day may be acted on at the next open.
  • Only the trades this client can see are closed: those in the broker accounts it may use and, when it is limited to the bots it created, the trades of those bots. Any other trade is left alone and is not listed in the answer.

Idempotency key

Every close needs an Idempotency-Key header: a unique value you choose, 1 to 128 letters, digits, dots, underscores or hyphens. Without it the request answers 428 idempotency_key_required and closes nothing. The same key sent again with the same request returns the first answer, listing only the trades this client can still see, and never closes anything a second time. A close refused before anything was changed frees its key, so the same request can be sent again with it.

Approval

By default a close waits for your approval. The answer is then 202 with status pending_confirmation, actionId and expiresAt; nothing has changed yet. You approve or reject it on the tradeSteward website, or in the tradeSteward app where app approval is available, and the approval page lists each trade and what approving will do to it. If a new trade opens in the same scope before you approve, or the market is closed, nothing is approved and the request keeps waiting: reload the page to see the new trades, then approve, so you never approve a list you were not shown. Your code reads the outcome from GET /pending-actions/{actionId}: once the close has run, its result holds the same scope, requested and trades as a 200 (the first 500 trades), with counts per status and tradesTruncated. An approved close that could not run ends failed with a resultCode that says why, for example permission_denied, not_found or service_unavailable, or ends expired. It ends failed with market_closed or close_set_changed only when the market closed or a trade opened in the scope in the instant between your approval and the close itself. With approval turned off for the client, the close runs at once and answers 200. See Approvals.

What each trade's status means

A 200 answer lists each open trade of the scope with a status:

  • requested: the trade is now marked to be closed.
  • already_closing: a close was already asked for and the trading engine has not placed its order yet, or a stop, a time exit or another exit is closing the trade. Nothing was changed.
  • held: the trade cannot be closed right now, and nothing was changed. reason says why.
  • not_open: the trade closed while the request ran.
  • failed: only in the result of an approved close. The close could not be sent, so nothing was changed for any trade, and you can ask for it again.

The reasons a trade is held:

  • user_halted: tradeSteward has halted trading on your account.
  • plan_inactive: your plan does not run bots right now.
  • broker_disconnected: the broker of the trade's account is not connected. Link it again, then close the trade.
  • account_unavailable: the trade's broker account cannot be found or read.
  • account_halted: bots are halted on the trade's broker account.
  • unsupported_account: the trade's broker account cannot place orders through tradeSteward.
  • exit_order_working: an order that closes or reduces the trade is working at the broker, or a reduce is about to be placed. A close you already sent shows this once the trading engine has placed its order, and needs nothing more. Otherwise wait for the order to fill or be cancelled, then close again if the trade is still open.

What it returns on 200: scope, requested (how many trades were marked) and trades, one entry per trade with tradeId, botId, accountNum, status and, when held, reason.

200
{"scope": {"kind": "bot", "botId": "aB3xK9mN2q"}, "requested": 1, "trades": [
  {"tradeId": "48213", "botId": "aB3xK9mN2q", "accountNum": "12345678", "status": "requested"},
  {"tradeId": "48230", "botId": "aB3xK9mN2q", "accountNum": "12345678", "status": "held", "reason": "exit_order_working"}]}

Refusals of every close: 428 idempotency_key_required; 409 idempotency_conflict; 403 permission_denied; 403 entitlement_required below Trader Unlimited; 404 not_found (nothing this client can see has that id); 409 market_closed; 409 pending_action_exists (a close of the same scope already waits for your approval); 429 rate_limited; 503 writes_disabled (changes through the API are switched off for a moment); 503 service_unavailable (try again shortly).

Closing trades

POST /bots/trades/{tradeId}/close Close one trade

Closes one open trade. tradeId is the id of a trade from the bot trade reads. A trade that is already closed answers 409 not_open. It takes no body. Operation id: closeTrade.

NameTypeRequiredMeaning
tradeId (path)stringYesThe trade to close.
Idempotency-Key (header)stringYesSee Idempotency key.

POST /bots/{botId}/trades/close Close a bot's open trades

Closes every open trade of one bot. For a Multi-Entry bot, its own id closes the open trades of every entry this client can see; an entry's own id closes only that entry's trades. A bot with no open trade is not refused: nothing is closed. A deleted bot's open trades can be closed by trade, by strategy, by account or all, but not by bot: its id answers 404 not_found. It takes no body. Operation id: closeBotTrades.

NameTypeRequiredMeaning
botId (path)stringYesThe bot whose open trades to close.
Idempotency-Key (header)stringYesSee Idempotency key.

POST /bots/trades/close Close open trades by strategy, by account or all

Closes the open bot trades of one strategy, of one broker account, or every open bot trade this client can see. The body is exactly one of these three; anything else answers 422 validation_failed. Operation id: closeTrades.

BodyCloses
{"scope": "all"}Every open bot trade this client can see.
{"scope": "strategy", "strategyId": "..."}The open trades of the bots in one strategy, from GET /strategies.
{"scope": "account", "accountNum": "..."}The open bot trades in one broker account, from GET /accounts.
POST /bots/trades/close
Idempotency-Key: close-2026-11-18-a
{"scope": "strategy", "strategyId": "S1A2B3"}

202
{"status": "pending_confirmation", "actionId": "a_3f9c1b7e2a4d6058c1e7b2", "expiresAt": "2026-11-18T16:12:40Z"}