How an AI agent reads order books with real money

AI agents read order books by subscribing to normalized market data feeds through a single API, parsing bids and asks into a standard format they can reason about, then generating orders sized in plain US dollars that the API translates into venue-specific contracts. The agent never holds or withdraws funds; it operates within scoped keys and budget caps set by the owner, so reading the book and placing real money trades happens under hard limits that cannot be bypassed. This walkthrough covers each step from data connection through execution, with attention to how safety controls remain active while the agent is live.

How does an AI agent connect to an order book?

The connection starts with an authorized key. The owner creates a scoped key through the Felix API that grants the agent permission to read market data and place orders, but not to withdraw funds or alter account settings. The agent then connects either through MCP tools inside an AI editor like Claude or Cursor, or through direct REST calls. In both cases, the agent opens a session to the unified API rather than managing separate sockets for a stock broker, a crypto venue, a perps venue, an options venue, and a prediction market. The API maintains data connections to each underlying venue. When the agent requests a book, the API returns a normalized snapshot or stream. During development and testing, the owner can keep the key in paper trading mode. In this mode, the agent reads real market data but its orders are simulated against the live book. Only after the owner explicitly upgrades the key to live status does the agent begin placing real money trades. This means the agent can practice reading books and reacting to spreads without financial exposure. The transition from paper to live is a deliberate owner action, not a configuration change the agent can make itself. The agent does not need to manage authentication handshakes with each venue. It presents one key to one API. The API handles the identity and session management with the downstream venues. This reduces the complexity of the agent's logic. It can focus on strategy rather than on maintaining multiple websocket connections with different message formats.

What does the agent actually read from the book?

An order book is a list of bids and asks sorted by price. When the agent queries a symbol, it receives the best bid, the best ask, the depth at each price level, and sometimes the recent trade history. The agent reads this as structured text or JSON, depending on the interface. For a large language model acting through MCP, the tool response typically presents the book in a readable table format that the model can parse. The agent needs to understand the spread, which is the difference between the highest bid and the lowest ask. It also reads depth, which tells it how much volume rests at prices away from the midpoint. This matters for sizing. If the agent intends to buy five thousand dollars worth of an asset and the book shows only a few hundred dollars of ask depth near the best price, the agent may anticipate slippage. It does not need to compute lot sizes or contract multipliers because the API accepts orders in plain US dollars. It is important to note that the agent is reading a snapshot or a stream, not a guarantee. Prices change between the read and the order. The agent cannot lock a price simply by reading it. This is true for every market type. The book is a signal, not a promise.

How is order book data normalized across five market types?

Felix exposes one schema for five market types. The agent does not need separate logic to parse a stock broker's level two feed, a crypto venue's depth channel, a perps venue's funding rate inclusive book, an options venue's chain, or a prediction market's order ladder. The API maps each into a common structure.

• ·Stocks: The agent sees share-denominated books translated into dollar depth. A bid for one hundred shares at fifty dollars is presented as a five thousand dollar bid level.
• ·Crypto: Spot markets are read the same way, with the API handling base and quote currency math so the agent thinks in dollars.
• ·Perpetual futures: The book shows the dollar value of the position, not the notional contract count. The agent does not need to track margin currency or funding rate formulas to read the book, though it may query funding rates separately if its strategy requires.
• ·Options: The API flattens the option chain into individual books per strike and expiration. The agent reads them as independent symbols with bid, ask, and depth in dollars.
• ·Prediction markets: Binary and scalar markets are presented with bid and ask percentages or dollar values, normalized so the agent can compare them directly against other asset classes.

This normalization means an agent can run a single strategy logic across multiple market types without rewriting its parser. The API also normalizes order sizing. When the agent sends an order for one thousand dollars, the API computes the exact number of shares, contracts, or units required at that venue. The agent never needs to know that a perps venue uses a one dollar per point contract while an options venue uses a one hundred dollar multiplier.

How does the agent decide when to place a real money order?

The decision logic lives in the agent's strategy, which the owner defines through prompts or code. The agent reads the normalized book, compares the current prices against its criteria, and decides whether to send an order. The criteria might be as simple as buying when the spread tightens below a threshold, or as complex as multi-factor models that weigh depth, recent fills, and correlation with other books. Once the agent decides to act, it constructs an intent. The intent contains the symbol, the side (buy or sell), and the dollar amount. It does not contain venue-specific parameters like margin type, time in force codes, or contract counts. The agent may also specify a maximum acceptable slippage in dollars, which the API translates into the venue's native order type. Before the order reaches any venue, the API enforces the owner's safety settings. It checks the request against spend caps and drawdown limits that were configured when the key was created. If the order would exceed the daily budget, the per-trade cap, or the open position limit, the API rejects it and returns an error to the agent. This check happens on every single order, so even if the agent's strategy has a bug or its reading of the book is wrong, the financial exposure remains bounded. The owner can also set an exit plan. If the agent's reading of the book triggers a stop condition, or if the market moves against the position, the API can flatten the position and revoke the key. This is not a venue feature; it is a control layer that sits between the agent and the market.

What does the execution path look like?

After the safety check passes, the API translates the dollar-denominated intent into a venue-native order. It computes the exact number of shares, contracts, or units using the current price and the contract specifications for that market. It then routes the order to the appropriate venue. The venue executes the order against its book and returns a fill report. The API normalizes the fill report back into dollars. The agent learns how much of its order filled, at what average price, and what dollar amount of exposure it now holds. If the order is only partially filled, the agent sees the remaining unfilled dollar amount. It can then decide whether to wait, cancel, or resubmit. The exact request schema is in the docs; the shape looks like this:

curl -X POST $FELIX_API_URL/v1/orders \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"EXAMPLE-XYZ","side":"buy","dollar_amount":500,"max_slippage_usd":5}'

The API responds with a normalized fill object. The agent reads this response and updates its internal state. If the agent is running through MCP, the tool output presents the fill in plain text so the model can reason about the next step. Funds remain in the owner's wallet throughout. The API is non-custodial by construction. The agent can spend within the approved budget, but it can never withdraw funds to an external address. Withdrawal addresses are owner-approved only. You can read more about how this works in how a single API keeps AI trading agents safe across every market and in our self-custody guide for algorithmic traders.

How do safety controls stay active while the agent reads and trades?

Safety is not a one-time setup. It is a continuous filter. While the agent is connected and reading books, the scoped key enforces several constraints in real time. First, the budget cap is a rolling limit. If the agent has already spent its allocated daily or weekly budget, subsequent orders are blocked even if the book shows an attractive setup. Second, position limits prevent the agent from accumulating more exposure than allowed in a single symbol or across the entire portfolio. Third, the panic or kill switch can be triggered by the owner at any time. When activated, the API flattens all open positions and revokes the key, cutting the agent off from further reading or trading. Before moving an agent from paper to live, the owner should audit the trading agent guardrails. The audit verifies that the scoped key has the correct permissions, that the budget cap is set to an amount the owner can afford to lose, and that the exit plan is configured. It is also worth reviewing how the safety model for MCP trading tools works from first principles to understand why the controls are embedded in the API layer rather than in the agent's logic. Even with these controls, trading can lose money, including everything. The safety limits cap the speed and magnitude of loss, but they do not eliminate market risk. A agent that reads the book incorrectly can still place losing trades within its budget. The controls exist to prevent ruin, not to guarantee profit.