A Trade Is a Lifecycle, Not an API Call
CloddsBot’s execution service sits at the point where a model-selected intention becomes an external protocol action. This chapter follows that transition through generic order fields, venue-specific translation, signing, slippage checks, retries, fills, heartbeats, and settlement. The goal is to show what an approved order actually means, and why a multi-leg opportunity across venues remains exposed to partial success even when its initial price comparison was sound.
One order interface, several protocol meanings
A common order interface is useful because the rest of CloddsBot can ask for a buy, sell, market, limit, maker, or protected operation without embedding every venue’s wire format in the agent’s conversation. The execution service receives the platform, market identifier, optional outcome token, side, price, size, order type, and venue-specific options. It then decides which adapter should handle the request and which additional checks apply.
The interface is a boundary, not a promise of sameness. On a prediction market, a price between zero and one can represent a probability-like share price and the size can mean contracts or outcome shares. A Polymarket order needs an outcome token identifier that is different from a condition or market identifier. A Kalshi request uses a ticker and a YES-referenced representation, so the client may need to transform a user’s NO-side price and buy/sell action before sending it. Opinion and Predict.fun bring their own signing and account requirements. The generic request is therefore a starting vocabulary; the venue adapter owns the translation into a valid protocol message.
That translation begins with basic validity. The service rejects non-finite prices or sizes, checks that the notional does not exceed the configured maximum, keeps prediction-market prices within the accepted range, and rejects non-positive sizes. Those checks are intentionally mundane. A model can produce a syntactically valid number that is still NaN, infinite, outside the venue’s probability range, or much larger than the operator intended. Rejecting it before a network call is part of making the action path deterministic.
Order type changes the lifecycle. A limit order states a price boundary and may remain open. A market-style operation is represented as a fill-or-kill request in the prediction-market execution layer, seeking immediate execution or cancellation. A maker order uses a resting limit order with a post-only flag so it will not take existing liquidity. A protected order checks the book before submitting and can refuse an estimated fill that would exceed a slippage limit. These are not cosmetic options. They change whether the system waits, crosses the spread, pays a taker fee, or accepts a partial opportunity.
Polymarket illustrates how much venue detail hides behind a simple “buy.” The client fetches and caches a token’s tick size, then checks that the requested price is a valid increment. If the order is post-only, it compares the requested price with the current best ask or bid and rejects a price that would cross the spread. It can detect whether the token belongs to a negative-risk market, which affects the exchange address and fee treatment. When a private key is available, the client builds an EIP-712 signed order; without it, it can fall back to a simplified authenticated payload that may not work with the real CLOB.
The phrase “signed order” deserves a precise interpretation.