What Belongs in an AI Trading Agent Decision Log?
Learn the essential elements to record in an AI trading agent decision log, from intent and data provenance to risk limits and error handling.
Produced with automation, then checked by deterministic quality rules and an independent source-grounded review before publication.
- 01The log must record the agent’s intended action, the data source, and any applied risk limits.
- 02Every order state transition, including timestamps and error codes, should be persisted for later reconciliation.
- 03Owner‑signed policy limits and agent‑key scopes must be captured to explain why a trade was allowed or blocked.
- 04Market data provenance - source, timestamp, freshness, and warnings - is a mandatory log component.
- 05Emergency‑stop events and key revocations need explicit entries separate from normal order flow.
An AI trading agent decision log records the full reasoning chain behind each trade decision. It includes the agent’s intent, the market data that informed the choice, and any risk controls that were applied. By persisting this information, operators gain a clear audit trail and can reconcile outcomes when timeouts or errors occur. The log also serves as the primary source for post‑trade analysis and compliance review. For related context, see How to give an AI agent a trading account.
Why is a Decision Log Critical for AI Trading?
Without a structured log, the opaque nature of machine‑driven decisions makes troubleshooting and accountability extremely difficult. A comprehensive log enables operators to verify that the agent respected owner‑signed limits, to detect data quality issues, and to understand the sequence of state changes that led to a filled order. It also provides the evidence needed for internal reviews and external audits.
What Core Elements Must Be Captured?
- The agent intent: a concise description of the desired trade (e.g., buy 10 BTC at market).
- The market data snapshot: source identifier, timestamp, freshness metric, and any warnings about data quality.
- The applied risk limits: order‑size caps, daily notional caps, loss thresholds, and expiry settings that were in effect at decision time.
- The order state timeline: each transition (created, pending, filled, cancelled, error) with precise timestamps and error codes if applicable.
- The authorization context: which agent key was used, its scope, and any owner‑signed policy that governed the action.
How Should Errors and Timeouts Be Logged?
Errors must be recorded with explicit error codes and descriptive messages, not merely as generic failures. A timeout does not prove an order failed; the log should note the timeout event and retain the last known order state so that later reconciliation can determine the true outcome. Durable mutation identifiers (e.g., a unique order ID) help link related log entries across system components.
When Should an Emergency Stop Appear in the Log?
An emergency stop is a distinct event that cancels managed activity and revokes the calling key. The log entry should record the stop command, the initiating authority, and the exact time. It must also note that existing positions and token allowances are not automatically closed; separate owner actions are required and should be logged separately.
How Do You Ensure the Log Remains Trustworthy?
- Store logs in an immutable, append‑only storage system to prevent tampering.
- Include cryptographic hashes of the market data snapshot and the order payload for later verification.
- Regularly reconcile logged order states with the authoritative runtime status endpoint (Felix documentation).
- Implement role‑based access so only authorized personnel can modify or delete log entries.
A well‑designed decision log is the single most effective tool for turning a black‑box AI trader into a transparent, auditable system.
Frequently asked questions
The agent key is scoped to specific trading actions and limits, while the owner key holds full control, including withdrawals. The log must record which key authorized each step.
Only the data snapshot that directly influences a decision needs to be logged, along with its source, timestamp, and any quality warnings.
Risk limits should be reviewed whenever policies are updated and periodically as part of routine operational audits. See [How Often Should AI Trading‑Agent Permissions Be Reviewed?](/blog/review-ai-trading-agent-permissions-frequency) for guidance.
No. Back‑tests are read‑only analyses that do not affect live state. The decision log records actual live decisions and outcomes, which complement but do not replace back‑testing.
Withdrawals require a separate owner‑signed intent and are not covered by the trade‑scoped agent key. Those actions should be logged in a dedicated withdrawal audit trail.
Sources and verification
Product claims in this article were checked against these first-party references. Runtime status remains authoritative for current availability.
- Felix documentationfirst party
- Felix machine referencefirst party
Build with Felix now.
Felix infrastructure is live through MCP and the API. The full trading app launches September 17.
Market hours shape the context of every quote, influencing its freshness, liquidity, and price formation. This article explains why timing matters and how to interpret quotes responsibly.
An AI trading agent must handle order cancellations and replacements with clear controls, error handling, and verification. This guide explains the safe workflow, required checks, and how to manage uncertainty.