1
Take some off
Close part of a position places a market order for
qty and cancels nothing — the resting
orders stay exactly where they are.qty must not exceed the open position. An over-sized close is rejected with
close_exceeds_position rather than silently clamped, because clamping would turn “close 3”
into “close everything” on a position that moved between your read and your write. If you meant
everything, flatten.It places an order, so it is claimed like one: clientOrderId is the idempotency key and a
duplicate answers 409.2
Get flat on one instrument
Flatten cancels the instrument’s working orders, then closes its position at market. The two
steps run in that order so a resting order can never re-open the position the close just
flattened.This is the guide rail for every demo and the last step of every test run.
3
Get flat on everything
Flatten the account closes every position and cancels every working order on the account.Irreversible — confirm before you call it. Scope it with
broker and account: it targets
exactly the one resolved account, never every connected account at once. With no connected
broker it answers 400.4
Turn the position around
Reverse cancels the position’s working orders, then opens the opposite position. It is one
operation under one idempotency key, and it runs server-side because a client-side
cancel-and-place pair could crash in between and leave the trader flat or without exits.The reversal is a market order for twice the position quantity. The response reports the new
side and qty, the fill, and cancelledOrders — how many working orders the sweep took
down.Which one is right
- Scaling out of a winner? Close part. It leaves your stop and target resting, so the rest of the position stays protected.
- Done with this trade? Flatten the instrument. It clears the resting orders first, so nothing puts you back in.
- Done for the day, or something is wrong? Flatten the account.
- Wrong side of the market? Reverse. Doing it as cancel-then-close-then-enter yourself is three chances to end up half-done.
What the risk lock does here
A risk-locked account answers423 to the partial close and to reverse — both place an order that
can re-shape exposure. Neither flatten route lists a 423, and the reason is in the risk monitor
itself: when a control fires, the monitor flattens the account and locks trading until the period
resets.
Where to go deeper
- Manage working orders — replacing and cancelling by broker order id.
- Track fills and P&L — what the close left behind, in the ledgers.
- Set risk controls — the controls that flatten and lock an account for you.
- Errors —
409,423, and the rest of the refusal shapes.