What developers get wrong about using one API for every market

Developers often assume that a single API for stocks, crypto, perpetual futures, options, and prediction markets implies a single mental model for all of them. In practice, the interface is unified but the execution semantics, settlement mechanics, and risk profiles remain distinct. Treating one API as a universal abstraction leads to logic errors where agents assume fungible behavior across markets that actually differ in leverage, settlement time, and margin rules. The result is not just a bug, but a category of mistakes that paper tests may miss and live markets will punish.

Do all markets execute the same way under one API?

A unified API surface means you can send an order to a stock broker, a crypto venue, a perps venue, an options venue, or a prediction market using the same authentication, the same dollar-based sizing, and the same response format. That uniformity is real, and it removes a great deal of integration boilerplate. However, it does not mean that a stock buy and a perp buy are the same operation under the hood.

When you buy a stock, you are exchanging cash for an equity position that settles into your account. When you buy a perpetual future, you are entering a margined contract that tracks an underlying price, pays or receives funding periodically, and can be liquidated if your margin buffer drops too low. When you buy an option, you are purchasing a derivative with a fixed expiration, a strike price, and nonlinear sensitivity to time and volatility. When you buy shares in a prediction market, you are taking a binary position on an event outcome with a defined resolution date and fee structure. The API normalizes the order message, but it does not normalize the physics of the instrument.

Developers who miss this distinction often write generic position logic. For example, they might treat all holdings as simple long exposures that can be held indefinitely. A stock position can be held as long as the company is listed. A perp position accrues funding every hour or every day. An option position decays in value as it approaches expiration. A prediction market position is worthless after the event resolves. If your agent assumes that buying always means holding a linear asset, it will miscalculate risk, misreport returns, and potentially fail to act before a contract expires or a margin call hits.

Suppose an agent sends a $500 buy order to a stock broker and a $500 buy order to a perps venue. The API accepts both with the same JSON shape. The stock purchase is fully paid and sits in the account. The perp purchase is a leveraged notional position that may require only a fraction of that $500 as margin, leaving the rest exposed to funding and liquidation risk. The agent that does not track market type alongside position size will think it owns two equivalent $500 assets. It does not.

Is dollar-based sizing enough to abstract away venue math?

Felix sizes orders in plain US dollars, and the API translates those dollars into the contract math required by each venue. This is a genuine convenience. A developer can reason in dollars instead of lot sizes, multipliers, base currency units, or share counts. The problem arises when developers treat that translation as a complete elimination of venue-specific math.

Dollar sizing solves the input problem, not the exposure problem. A $100 order into a stock is roughly $100 of equity exposure. A $100 order into an option controls a much larger notional exposure, and the value of that option can go to zero on expiration. A $100 order into a perp at 10x leverage represents $1000 of notional exposure, and the loss can exceed the initial $100 if the position is not properly margined. A $100 order into a prediction market is actually a bet that pays a binary outcome, not a continuous investment.

The API takes care of the conversion so the venue understands the order. It does not take care of the agent's understanding of what was actually bought. The developer still needs to know that an option has a delta, that a perp has a funding rate, and that a prediction market has a resolution fee. If the agent's portfolio logic treats all positions as fungible dollar entries, it will build a risk model that is internally consistent and externally wrong.

This is especially dangerous when agents rebalance across markets. Imagine an agent that decides to rotate $500 from a stock position into a crypto spot position. It sells the stock, sees a $500 cash entry, and buys crypto. But the stock sale may not settle immediately, meaning the cash is not yet available to spend. The API reported the order as filled, but the backend settlement timing differs. The agent that does not account for settlement lag may attempt to spend cash that is still in flight. Routing orders across five market types handles the mechanical translation, but the agent must still track the semantic reality of what it owns.

Does one API eliminate the need to understand settlement and custody?

Felix is non-custodial by construction. Funds remain in a wallet the owner controls, the agent can spend within scoped limits, and withdrawal addresses are owner-approved only. This architecture is consistent across all five market types. However, non-custodial does not mean uniform settlement.

Settlement is the process by which a trade becomes final and ownership transfers. In a stock trade, settlement involves a broker and a clearing entity, and the cash and shares exchange hands according to a schedule. In a crypto spot trade, settlement is typically on-chain and depends on block confirmations. In a perpetual future, there is no delivery of the underlying asset; the position is marked to market and settled in cash via funding payments and unrealized profit and loss. In an option, settlement can involve physical delivery of the underlying or a cash difference, depending on the terms and whether the option is exercised. In a prediction market, settlement happens when the event resolves and the venue distributes payouts based on the outcome.

A developer might look at the unified API and assume that a filled order means the money has moved and the new asset is immediately available. That assumption holds for some crypto spot trades but fails for stocks, where settlement delay creates a gap between execution and availability. It fails for perps, where there is no asset to settle, only a continuous stream of cash flows. It fails for options, where exercise is a separate action from closing a position.

If an agent is programmed to sweep all available cash into new positions at the end of each trading loop, it may inadvertently double-spend unsettled funds. If it is programmed to hedge a stock position by buying an option, it may not realize that the hedge settles on a different timeline than the underlying. How AI agents trade across markets without taking custody of your funds explains the wallet architecture, but the agent code must still respect the settlement logic of each market it touches.

Is it safe to treat the API as a black box?

A black box is a system whose internal workings are opaque to the user. One API for five markets is not a black box, and treating it as one is a reliable way to introduce silent failures. The API is a thin, consistent translation layer over a set of heterogeneous backends. The heterogeneity does not disappear just because the HTTP headers are the same.

Developers need to know the mapping between their generic order and the specific market behavior that follows. A kill switch that flattens all positions is a good example. In a stock, flattening means submitting a sell order. In a perp, it means submitting a close order. In an option, it may mean selling the contract, but if the option is American-style and the agent is short, flattening may require buying it back, or it may involve assignment risk that cannot be killed instantly. In a prediction market, flattening means selling the position, but liquidity may be too thin to exit immediately before resolution. The API will route the order, but the developer must configure the kill switch logic to understand what flattening actually means for each instrument.

Safety controls like budget caps and position limits also need market-aware logic. A $1,000 budget cap might allow one options spread or fifty stock shares. A position limit of five units might mean five shares of stock or five contracts, but a single perp contract can carry the notional risk of many shares. A drawdown limit that works for unleveraged stocks may be meaningless for a leveraged perp that can lose its margin in minutes.

Imagine an agent that applies a uniform 2% stop-loss rule across every position in its portfolio. For a stock, this is a conventional risk management rule. For a perp with 10x leverage, a 2% adverse move in the underlying is a 20% loss on the position, and the stop may not execute in time if the market gaps. For a far out-of-the-money option, a 2% move in the underlying might not change the option price at all, or it might drop the price by 50%. The same rule applied blindly across markets is not risk management. It is a random number generator.

What should developers test before taking a multi-market agent live?

Paper trading is available for testing, and it is a useful first step. It is not a substitute for understanding the differences between market types. Paper environments simulate fills and track positions, but they may not fully replicate funding rate accrual, option decay, prediction market resolution mechanics, or the settlement delays found in live markets. Why paper trading misleads beginners who build AI agents covers the broader problem, but the specific risk for multi-market developers is that paper mode may paper over the very market distinctions that matter most.

Before going live, developers should validate the following:

1. 01Confirm that the agent stores market type as a first-class attribute on every position, not just symbol and dollar value.
2. 02Verify that the kill switch and exit plan logic branches correctly for each market type, including edge cases like option expiration and perp funding.
3. 03Test that dollar sizing maps to the intended notional exposure by checking the venue response and comparing it to the expected position size.
4. 04Ensure the agent reads and reacts to market-specific metadata such as funding rates, open interest, expiration dates, and event resolution windows.
5. 05Run a simulated settlement audit: trace a stock sale through the expected cash availability delay and confirm the agent does not treat the proceeds as spendable before settlement completes.

The exact request schema is in the docs; the shape looks like this:

{
  "api_key": "YOUR_KEY",
  "market_type": "perp",
  "side": "buy",
  "dollar_amount": 500,
  "symbol": "EXAMPLE-PERP"
}

This illustrative payload shows how a developer sends the same fields regardless of market, but the agent code that generates this payload must still know it is dealing with a perp. The API does not remove that responsibility. It only makes the integration layer cleaner.

Finally, start with a small budget and scoped keys that limit the agent to a single market type until its behavior is verified. Only after the agent handles one market correctly should it receive a key that spans multiple market types. The convenience of one API is meant to reduce plumbing, not to remove the need for domain knowledge. Trading can lose money, including everything, and the unified interface does not make the underlying risks any less real.