How to size orders in dollars when building a trading agent

Dollar-based order sizing lets developers send orders in plain US dollars instead of calculating shares, contracts, lots, or base currency units. The API translates the dollar amount into the venue-specific quantity required for execution. This removes a major source of arithmetic errors and makes agent strategies easier to read and audit. Trading can lose money, including everything, so simplifying order entry does not reduce market risk; it only reduces operational risk.

Why do contract sizes cause errors for agents?

Every market expresses quantity differently. A stock broker works in shares. A crypto spot venue works in base currency units or quote currency units. A perps venue uses contracts that reference a multiplier, often hidden in the interface but critical in the API. An options venue uses contracts that represent one hundred shares of the underlying. A prediction market uses shares that pay out between zero and one dollar. When an agent operates across several of these, it must carry a lookup table of multipliers, minimum order sizes, tick increments, and notional formulas. That is a lot of state to keep correct in a prompt or in a lightweight script.

The most common mistake is confusing notional value with unit count. Suppose an agent decides to allocate one thousand dollars to a trade. If it sends one thousand to a stock venue, it might be interpreted as one thousand shares. If the share price is one hundred and fifty dollars, the order notional becomes one hundred and fifty thousand dollars. On an options venue, one thousand contracts might control one hundred thousand shares. In reverse, an agent that correctly computes ten shares might accidentally send ten contracts to a perps venue, creating a position ten or one hundred times larger than intended. These errors happen because the mental model of the trade is in dollars, but the execution layer is in units.

Large language models are especially weak at persistent numeric state. They can hallucinate multipliers, forget tick sizes, or misplace decimals when asked to convert a dollar target into a unit count in the same prompt. Moving that conversion out of the agent and into the API means the agent never needs to know the multiplier. It states the intent in dollars, and the infrastructure handles the rest. This is not just a convenience; it is a structural guardrail against a class of bugs that can cause immediate and oversized losses.

How does the API convert dollars into venue units?

When a developer sends an order with a dollar notional, the API queries the current market data for that symbol, including the last traded price, the contract multiplier, and the minimum lot size. It then computes the equivalent number of units that most closely matches the requested dollar amount without exceeding it, or according to the venue's rounding policy. The API performs this conversion atomically with the order request so that the price used in the calculation is the same price used in the execution path. This avoids race conditions where the agent pre-computes a share count at one price and the market moves before the order arrives.

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

{
  "market_type": "perps",
  "symbol": "EXAMPLE-PERP",
  "side": "buy",
  "dollar_notional": 500.00
}

The API returns the computed unit count, the expected notional, and any rounding or rejection details before the order reaches the venue. If the dollar amount is below the venue minimum, the API rejects the request immediately with a clear error message, so the agent does not waste a round trip. Developers can log both the requested dollar value and the actual unit count for audit purposes. This transparency helps when debugging why an order for five hundred dollars resulted in four hundred and eighty dollars of exposure, a common outcome when the share price does not divide evenly.

What happens when a dollar amount does not divide evenly?

Exact division is rare. If a stock trades at forty three dollars per share and the agent requests one hundred dollars, the API cannot buy two point three shares on a venue that only supports whole shares. The API rounds down to two shares, which is roughly eighty six dollars, and reports the delta. If the venue supports fractional shares, the API may submit two point three shares exactly. The developer should not assume that the filled notional will match the requested dollar amount. Slippage, rounding, and minimum lot rules all create deviations.

Partial fills add another layer. An order for one thousand dollars might fill six hundred dollars on the first execution and then sit open until the remaining four hundred dollars execute, or until it is cancelled. The agent must track filled notional separately from requested notional. Relying on the request value as a proxy for position size is a common mistake. The agent should read the fill summary from the API after each execution event and update its internal ledger. If the agent is using a framework that abstracts fills into dollar events, it should still verify the unit counts underneath to avoid drift across multiple partial fills.

Some venues also have notional minimums that are not obvious from the unit count alone. A perps venue might require a minimum order of ten dollars in notional value even if the contract size is tiny. The API knows these thresholds and rejects undersized orders before submission. The agent should handle these rejections gracefully, either by skipping the signal or by aggregating small signals into a larger order that meets the minimum. Aggregation logic is the agent's responsibility, but the API provides the boundary data needed to make that decision.

How should developers integrate dollar sizing with safety controls?

Dollar sizing is an input format, not a risk control. The owner still needs spend caps and drawdown limits configured on the key. The API enforces these caps in the same conversion step. If an agent requests a trade that would breach the daily spend cap, the API rejects it before any unit conversion happens. This means the safety layer is independent of the sizing layer. An agent cannot bypass a cap by switching from unit sizing to dollar sizing.

Developers should also follow the practical checklist for non-custodial MCP when connecting agents. Scoped keys mean that even if the agent logic is flawed, the maximum damage is bounded by the cap. The panic switch and exit plan flatten positions and revoke access regardless of whether the original orders were sized in dollars or units. When testing, developers should verify that the agent respects rejection messages from the API. If the agent retries aggressively after a cap rejection, it can burn through API rate limits without trading, but it should never trade through the cap.

It is worth stating again that trading can lose money, including everything. Dollar sizing reduces the chance that an agent will accidentally request one hundred times the intended exposure because of a unit error. It does not protect against bad predictions, adverse market moves, or flawed strategy logic. The safety controls exist to limit the speed and scale of losses, not to prevent them entirely. Developers should treat dollar sizing as part of a defense-in-depth approach that includes prompt constraints, hard limits, and human oversight.

What market-specific quirks should developers handle?

Each market type introduces its own edge cases when converting from dollars to units. The API normalizes the input, but the developer still needs to understand the output.

• ·Stocks. Some venues support fractional shares and others do not. On whole share venues, rounding down is standard, which means small dollar orders can round to zero shares. The API rejects these rather than submitting a zero share order. Developers should set a minimum dollar threshold in the agent logic to avoid noise.
• ·Crypto spot. The price is volatile. A dollar notional computed five seconds ago may represent a different unit count by the time the order reaches the book. The API uses the latest price at submission, but slippage can still alter the filled notional. Agents should expect variance and not treat a dollar target as a guarantee of exact exposure.
• ·Perpetual futures. Contracts have multipliers. The dollar amount maps to notional exposure, not to margin. A five hundred dollar order on a perps venue creates five hundred dollars of directional exposure. The margin required depends on the venue's leverage rules and the collateral in the wallet. The agent should not confuse notional with margin when tracking available buying power.
• ·Options. One contract typically represents one hundred shares. If the underlying is trading at two hundred dollars, a single contract is twenty thousand dollars of notional. A five hundred dollar order will round down to zero contracts and be rejected. Agents trading options need to check the underlying price and the contract multiplier before assuming a dollar amount is viable. This is one of the most frequent causes of rejection in multi-asset agents.
• ·Prediction markets. Shares are priced between zero and one dollar. A one hundred dollar order buys one hundred shares if the price is one dollar, but two hundred shares if the price is fifty cents. The notional at risk is still one hundred dollars, but the payout structure is binary. The agent should track the number of shares won or lost, not just the entry notional, because the resolution value determines the final profit or loss.

Understanding these differences prevents the agent from generating a high volume of rejected orders, which can delay signals and complicate logs.

How can developers test dollar sizing before going live?

Felix offers paper trading for exactly this purpose. In paper mode, the conversion logic runs through the same code path as live trading, but executions are simulated against a mock order book. Developers can observe how a one hundred dollar order translates into shares or contracts without risking capital. This is the right place to test rounding behavior, rejection handling, and partial fill logic.

Before authorizing a live key, the developer should confirm that the agent responds correctly to every API response type: accepted, rounded, rejected for minimum size, and rejected for cap breach. Only the owner can authorize live trading, and the authorization step is separate from the API key creation. Developers should start with small dollar amounts in live mode and compare the unit counts to paper results. For a broader safety overview, see how to build a trading agent that handles real money safely.