GetTracesByOrder¶

Reads traces directly from trades.db. No historical trace cache is used. Available as a TCP/Moleculer command; no HTTP path is registered.

Access¶

Sessions: SESSION_MANAGER, SESSION_ADMIN, SESSION_DEALER. Requires current staff backoffice/trade visibility permissions, except for super-admin scope. Token metadata identifies the staff member; permissions are resolved by the existing manager access service.

For non-super-admin staff, the stored trace brand/group and the current account scope must both be visible. A deleted order remains readable through its persisted trace identity while the account is still accessible. Missing accounts or missing stored scope are visible only to super-admins. Missing and out-of-scope orders both return 404. An accessible existing order with no captured history returns an empty page.

Request fields¶

Field	Type	Required	Meaning
`order`	integer	Yes	Positive order ticket.
`after_id`	int64	No	Exclusive trace cursor, minimum 0, default 0.
`limit`	integer	No	Page size, 1–500, default 100.

{"order": 1186, "after_id": 0, "limit": 100}

Response fields¶

The following is the response payload (inside data when the transport uses a status/data envelope). Rows are objects, not positional structure/rows arrays.

Field	Type	Meaning
`order`	integer	Requested ticket.
`after_id`	int64	Requested cursor.
`limit`	integer	Effective page size.
`count`	integer	Number of items in this page, not lifetime total.
`next_after_id`	int64	Last returned ID; unchanged for an empty page.
`has_more`	boolean	Another row existed in the read snapshot.
`items`	array	Complete `TraceTradeRecord` objects, ascending `id`.

Every item has all of these fields:

Field	Type	Meaning
`id`	int64	SQLite-generated persistence sequence; not a trade version.
`schema_version`	integer	Snapshot/record format version, currently 1.
`event_id`	string	Unique event UUID, used to deduplicate write retries.
`operation_id`	string	Correlates captured acceptance and execution; batch orders can share an operation.
`request_id`	string	Optional originating request correlation string, maximum 256 characters; empty if absent.
`occurred_at_ms`	int64	Unix milliseconds when the transition was captured.
`recorded_at_ms`	int64	Unix milliseconds of the successful insertion attempt.
`brand`	string	Account brand resolved at persistence time; may be empty if unavailable.
`group`	string	Account group resolved at persistence time; may be empty if unavailable.
`login`	integer	Account login.
`order`	integer	Order ticket.
`related_order`	integer	Parent ticket for a partial-close child; otherwise 0. Parent queries do not automatically include child rows.
`symbol`	string	Instrument name; may be empty for finance records.
`actor_type`	integer	Authenticated `SESSION_*` value: user 0, manager 1, dealer 2, admin 3, system 4, FIX 5, customer 9. Unknown is -1.
`actor_id`	string	Authenticated actor identifier; empty for unknown/system origin.
`actor_name`	string	Authenticated display name if available, otherwise empty.
`channel`	string	`http`, `tcp`, `moleculer`, `fix`, `system`, or empty when unknown.
`command`	string	Originating router command, or empty for unattributed/internal work.
`action`	integer	Action enum below.
`stage`	integer	Stage enum below.
`reason`	integer	Trade opening reason (`TR_REASON_`), not* the current actor.
`activation`	integer	`ACTIVATION_*`: none 0, SL 1, TP 2, pending 3, SO 4, cancel 5; rollback variants are negative.
`result_code`	integer	`RET_*` result, not HTTP status; normally 0. A close/delete/partial-close outcome mismatch uses generic `RET_ERROR` when no specific execution code is available.
`changes_json`	string	JSON-encoded object with `before` and `after` allowlisted snapshots, each an object or null. Acceptance snapshots describe requested state, not successful execution.
`context_json`	string	JSON-encoded reserved context object, currently `"{}"`.

Snapshot keys: integer order, login, cmd, state, volume, parent_order, closed_volume, partial_close_volume, open_time, close_time, expiration, reason, activation, magic, digits, gw_volume, gw_open_price, gw_close_price; numeric open_price, close_price, sl, tp, profit, commission, commission_agent, storage, taxes, margin_initial; string symbol, comment, gw_order, gw_source, gw_uuid. Times inside snapshots are Unix seconds. Field semantics follow TradeRecord. api_data, credentials and arbitrary request bodies are excluded. These are full allowlisted snapshots, not only changed keys.

Action values (TRADE_TRACE_ACTION_*): OPEN 0, MODIFY 1, PARTIAL_CLOSE 2, CLOSE 3, REOPEN 4, CANCEL_PENDING 5, ACTIVATE_PENDING 6, EXPIRE_PENDING 7, DELETE 8, HISTORY_CORRECTION 9, COMMISSION 10, SWAP 11.

Stage values (TRADE_TRACE_STAGE_*): ACCEPTED 0, APPLIED 1, REJECTED 2, FAILED 3. FAILED is reserved for explicit future failure integrations and is not inferred from a timeout. REJECTED currently covers open-admission rejections and detected close/delete/partial-close outcome mismatches. Validation and permission denials before admission remain in the operational journal, not this table.

Complete response example¶

{
  "order": 1186,
  "after_id": 0,
  "limit": 100,
  "count": 1,
  "next_after_id": 41,
  "has_more": false,
  "items": [{
    "id": 41,
    "schema_version": 1,
    "event_id": "c1151bb0-16b9-4c66-8dc7-e01fddc3263d",
    "operation_id": "54125e62-42d9-452a-b942-9b15e0c2c518",
    "request_id": "",
    "occurred_at_ms": 1790686171000,
    "recorded_at_ms": 1790686171005,
    "brand": "zalu",
    "group": "TEST_MATRIX_5",
    "login": 100012,
    "order": 1186,
    "related_order": 0,
    "symbol": "EURUSD",
    "actor_type": 1,
    "actor_id": "1",
    "actor_name": "",
    "channel": "tcp",
    "command": "MngOpenTrade",
    "action": 0,
    "stage": 0,
    "reason": 2,
    "activation": 0,
    "result_code": 0,
    "changes_json": "{\"before\":null,\"after\":{\"order\":1186,\"login\":100012,\"cmd\":0,\"state\":1,\"volume\":30,\"parent_order\":0,\"closed_volume\":0,\"partial_close_volume\":0,\"open_time\":1790686171,\"close_time\":0,\"expiration\":0,\"reason\":2,\"activation\":0,\"open_price\":1.1002,\"close_price\":1.1,\"sl\":0,\"tp\":0,\"profit\":-6,\"commission\":0,\"commission_agent\":0,\"storage\":0,\"taxes\":0,\"margin_initial\":330.06,\"magic\":0,\"digits\":5,\"gw_volume\":0,\"gw_open_price\":0,\"gw_close_price\":0,\"symbol\":\"EURUSD\",\"comment\":\"\",\"gw_order\":\"\",\"gw_source\":\"\",\"gw_uuid\":\"\"}}",
    "context_json": "{}"
  }]
}

Persistence and operational limits¶

Trace persistence is asynchronous: execution acknowledgement does not imply that a trace is already readable. Poll using the same cursor. Applied trace writes and their captured trade payloads share a SQLite transaction; audit events are not coalesced with later events. Ordinary floating-profit updates do not create traces. Internal/plugin/dealer paths without propagated context can have unknown actors; do not reinterpret them as system actions.

Fresh databases and existing installations create traces through bootstrap/additive migration. Old trade history is not backfilled. Local backup includes the table. Restoring an older database restores its audit timeline and re-creates the table if missing; later events are not retained elsewhere. Reset cursors after restore because IDs can be reused on the restored timeline. Order deletion does not cascade to traces. No trace update/delete API exists.

This is not an external tamper-proof ledger. It uses the existing asynchronous writer, finite retry policy and WAL synchronous=NORMAL; crashes or exhausted retries can lose uncommitted records. Reads fail while the writer is marked degraded. Restart clears that runtime flag but does not reconstruct missing records.

Errors¶

Error payload is {"error":"CODE"}; existing access-validation errors can additionally include message.

400 INVALID_DATA: invalid order, cursor or limit.
401/403: existing authentication/staff-permission checks.
404 TRACE_ORDER_NOT_FOUND: nonexistent or inaccessible order/history.
500 TRACE_READ_FAILED: SQLite read failure or degraded writer.