Direct answer
When evaluating an Order API, focus on what the API actually does to orders, how you can confirm outcomes, and where behavior may differ from your expectations. Keep the checklist objective: separate stable mechanics (request/response structure, lifecycle semantics) from variable conditions (market movement, costs, execution quality, and local rules). Because outcomes depend on external factors, treat examples as assumptions, not predictions.
How an Order API works (mechanism and definition)
An Order API is a program interface used to submit, modify, and cancel trade orders and to retrieve information about their lifecycle status. In practice, you typically work with:
- Order request: the data you send (e.g., order type, side, quantity, time-in-force, and any required identifiers).
- Execution and acknowledgement: the responses you receive (acceptance, rejection, or errors).
- Order state updates: how the provider reports changes over time (open, partially filled, filled, cancelled, expired, rejected).
- Reconciliation identifiers: fields that let you match your intent to provider-reported results (such as client order IDs and provider order IDs, if supported).
A key evaluation step is to translate the documentation into an explicit state model for your system: which statuses exist, how transitions happen, and what guarantees (if any) the API provides around ordering, retries, and updates. Stable mechanics are those you can reason about from the spec; variable conditions are everything that can change between request and confirmation.
Due-diligence checklist (afvinkpunten)
Use the items below to build a repeatable verification process.
1) Input and semantics (what you send)
- Confirm required fields and data constraints (allowed order types, minimum/maximum sizes, valid time-in-force values).
- Document how the API interprets units and rounding rules. State your own assumptions for quantity, precision, and how “base” vs “quote” amounts are handled.
2) Idempotency and duplicate protection (prevents state mismatches)
- Check whether the API supports idempotent requests or a documented strategy for retries after timeouts.
- Verify how duplicates are handled when the same request is sent again (same client ID vs new request). This matters because retry logic is common in automated systems.
3) Order lifecycle and reconciliation (evidence or document)
- Verify the complete order lifecycle: which statuses can occur, and how transitions are reported.
- Confirm the fields you need for reconciliation (order IDs, timestamps, quantities filled, remaining quantity, and reasons for rejection).
- Define your “done” criteria (e.g., you consider an order closed when you receive a terminal state such as filled/cancelled/rejected/expired—based on the provider’s documented semantics).
4) Updates and delivery model (what you can observe)
- Determine whether status information comes via polling, streaming/webhooks, or both.
- If updates are asynchronous, check for guarantees about event ordering and event completeness. Your reconciliation logic should handle missing or delayed updates as an explicit scenario.
5) Costs and execution assumptions (what can change)
- Identify which costs and execution effects can change outcomes between request and final status: fees, spreads, slippage, partial fills, and latency.
- When illustrating an example, state assumptions (e.g., “assume fees are X and fills occur in one execution”) and then note that real conditions can diverge.
6) Failure modes (rode vlaggen)
Look for and test these common failure modes:
- Rejected orders (validation errors, insufficient permissions, or invalid parameters).
- Timeouts and transient errors (your client may retry while the provider may already have processed the request).
- Partial fills (order becomes partially executed, requiring logic for “remaining” quantity).
- Inconsistent state (your system sees one status source while the other source lags).
If the documentation does not clearly specify how these behave, treat that as a red flag and plan for conservative reconciliation and monitoring.
Limitations and risks (what can go wrong)
Order execution and order state outcomes depend on market conditions and provider behavior, which are not fully controllable. Historical relationships do not guarantee future results, and even careful specifications can fail under stress (high volatility, network issues, or provider-side maintenance). Material limitations to explicitly acknowledge include:
- Uncertainty between intent and execution: acknowledgement does not necessarily mean final execution.
- Non-atomic outcomes: partial fills and subsequent cancels can create multiple states for a single instruction.
- Observability gaps: delays or missed updates may cause your system to misinterpret the current status.