Orders and execution
Understand how the agent proposes orders, how you approve them, and how fills flow back into your workspace.
Every order starts as a file the agent writes to your workspace — you review the diff, approve it, and Qoc sends it for execution, just like merging a commit.
The propose → approve → execute flow
When the agent decides to trade, it writes a proposed-order file into orders/proposed/. The file is human-readable TOML that names the venue, symbol, side, quantity, and order type. Nothing is sent to a broker at this stage.
You review the file — or the rendered diff in your terminal — and approve with qoc run approve or by moving the file. Approval creates a commit in workspace history (git log shows every trade decision). The committed order is then dispatched to the connector and the live venue.
Fills — full or partial — arrive over the connector's fill stream and land in inbox/. Qoc applies them to the position ledger automatically and writes a fill record to orders/filled/.
Example proposed-order file
# Proposed by agent at 2026-07-05T14:22:00Z
# Task: rebalance-equities (issue #42)
[order]
connector = "main-equities"
symbol = "AAPL"
side = "buy"
quantity = 50
type = "limit"
limit_price = 211.40
time_in_force = "day"
[rationale]
summary = "AAPL weight below target by 1.4 pct; current price within 0.3 pct of 50-day VWAP"
research_ref = "research/2026-07-05-aapl-rebalance.md"Approving an order
- 1
Review the proposed file
Open
orders/proposed/in your editor or runqoc statusto see a summary table of pending orders with their rationale. - 2
Approve or reject
Run
qoc run approve <filename>to approve a single order, orqoc run approve --allto approve every pending proposal. To reject, delete the file or runqoc run reject <filename>. - 3
Commit is created
Approval moves the file to
orders/approved/and creates a workspace commit. The commit hash becomes the order's internal reference ID. - 4
Dispatch and fill
Qoc dispatches the order to the connector. Fills arrive in
inbox/and update the position ledger. Partial fills remain open until complete, cancelled, or expired.
Order types
| Type | Behavior | Required fields |
|---|---|---|
| market | Fill at best available price immediately | connector, symbol, side, quantity |
| limit | Fill at limit_price or better | connector, symbol, side, quantity, limit_price |
| stop | Trigger a market order when stop_price is reached | connector, symbol, side, quantity, stop_price |
| stop_limit | Trigger a limit order when stop_price is reached | connector, symbol, side, quantity, stop_price, limit_price |
Partial fills and cancels
A partial fill updates the position ledger immediately for the filled quantity. The remainder stays as an open order. You can cancel the open remainder with qoc run cancel <order-id>.
Cancelled and expired orders land in orders/cancelled/ with a reason field. The workspace history retains the full lifecycle of every order.
Market orders bypass the limit-price guard
Market orders have no limit_price, so the max-slippage guard cannot evaluate them against a reference price. If you want slippage protection on every order, configure the guard to block market orders outright or require a limit fallback.
Use qoc logs to trace an order
Run qoc logs --order <id> to see the full timeline: proposed timestamp, guard evaluations, approval commit, dispatch acknowledgement, fill events, and final state.