Devin Hartcastle
Nearly every setup of this kind starts with a successful login and a test order. That proves the credentials work.
It says little about whether an agent can recover from a timeout, recognise a partial fill, or stop trading when account data goes stale. A broker API for unattended trading needs a tested contract between the agent and the broker, including the awkward states that appear after an order leaves the process.
Use the first 30 days to establish that contract before sizing up. Keep the strategy simple during implementation. The early work is about platform behaviour, state tracking and controls, not finding a profitable signal.
Days 1 to 5: map the broker contract
List the capabilities the agent will actually use
Read the API documentation and build a capability matrix for the account type and instruments in scope. Do not assume that a feature in a mobile app exists in the API, or that a sandbox behaves like a live account. Record the endpoint, permissions, response fields, limits and known gaps for each operation.
- Account state: balances, buying power, margin, positions and open orders.
- Market data: streaming or polling, timestamp format, supported venues, entitlement requirements and stale-data signals.
- Order entry: supported order types, time-in-force values, fractional quantities, short sales and replace or cancel behaviour.
- Operational limits: request quotas, order rate limits, session expiry, maintenance windows and status-page alerts.
For each field, mark whether it is authoritative, delayed or absent. Buying power and available funds are not interchangeable. A position snapshot may lag the fill stream. These details change which source the agent trusts for its pre-trade checks and reconciliation.
Choose measurable service assumptions
Write down expected latency and data freshness for the intended strategy. A five-minute signal may tolerate a one-second quote delay; a strategy reacting to fast price changes may not.
Set a stale-data threshold, a maximum order notional and a maximum unconfirmed-order count. Treat all as configuration with explicit units, not numbers scattered through code.
Typical ranges across broker APIs vary by account, product and market. They are planning estimates, not guarantees. Confirm the actual values in the relevant broker documentation. A broker API platform comparison can also help frame which behaviours to verify rather than infer from marketing pages.
Days 6 to 12: build the execution adapter
Model order state independently of the response
Use a durable order record keyed by an internal client order ID. Store the intended instrument, side, quantity, limit price, strategy decision ID, submission time and broker order ID.
A successful HTTP response is an acknowledgement, not proof of a fill. Update the record from order events and periodic snapshots, and preserve every transition for later diagnosis.
A practical state model includes pending submission, acknowledged, partially filled, filled, cancel pending, cancelled, rejected and unknown. The unknown state matters: a timeout can occur after the broker accepted the request but before the agent received the response.
On timeout, query by client order ID or reconcile open orders before retrying. Blind resubmission can create duplicate exposure.
Build safe handling for failures
Separate transport errors from business rejections. A 429 response calls for backoff and a reduced request rate. A rejected order needs its broker reason captured and interpreted.
A connection reset leaves the outcome uncertain until the order is queried. Use bounded retries with jitter for safe reads; make order submission idempotent where the API supports a client ID, and otherwise resolve uncertainty through reconciliation.
Implement these controls before the first live test:
- Persist intent before sending an order, then persist the broker response or unresolved outcome.
- Use one owner for each account's order stream, with a recovery process that can rebuild state after restart.
- Reserve rate-limit capacity for cancels and risk-reducing orders instead of spending the full quota on polling.
- Fail closed if positions, buying power or market data exceed configured freshness limits.
Test clock handling as well. Convert broker timestamps to a consistent UTC representation, retain the original value and measure clock drift on the host. A few seconds of skew can make a recent order appear missing during reconciliation.
Days 13 to 21: test execution and limits
Run the same order scenarios against the sandbox or a paper environment, then compare responses with the documented contract. Paper trading is useful for checking the agent's logic, but usually does not reproduce queue priority, market impact, borrow availability or every rejection condition. Keep a list of differences and encode the ones that affect risk into tests.
The figures below are typical market ranges for planning and test design. Actual broker limits and timings can sit outside them, so read account-specific documentation and measure the environment directly.
| API surface | Typical range | Agent design target | Test to run |
|---|---|---|---|
| REST request quota | 5 to 60 requests per second | Use no more than 70% of the published limit in normal operation | Throttle, then verify recovery after 429 responses |
| Order rate limit | 1 to 10 orders per second | Reserve capacity for cancels and risk reduction | Submit bursts and confirm rejections do not loop |
| Order acknowledgement | 100 milliseconds to 2 seconds | Set a timeout based on measured latency and reconcile on expiry | Drop the response after submission and check for duplicates |
| Order event delivery | 100 milliseconds to 5 seconds | Compare events with periodic order snapshots | Delay, reorder and omit events during replay |
| Streaming heartbeat | 1 to 30 seconds | Declare data stale after a strategy-specific interval | Disconnect the stream and verify trading halts |
Run scenario tests that include:
- Partial fill followed by cancel, with the remaining quantity correctly calculated.
- Duplicate submission after a simulated timeout, with only one live order present.
- Rejected order due to buying power, invalid price increment or unavailable instrument.
- Restart while an order is open, followed by reconciliation of positions and order state.
- Rate-limit response during a market move, with cancels still prioritised.
Compare requested quantity, filled quantity, average fill price, fees and timestamps. If paper results are used to assess execution, label assumptions about spread, slippage and fill probability. Agentic Trading Index offers agentic paper trading from $9.99 a month for testing order logic, but no paper environment removes the need to verify live broker behaviour.
Days 22 to 30: stage deployment and recovery
Start with a constrained live account or the smallest practical order size. Keep the strategy's risk budget separate from broker limits. A broker may accept an order that breaches the agent's own exposure rules, so enforce limits before submission and check them again after fills.
Set deployment gates that can be checked in logs and dashboards:
- Reconciliation completes after startup and on a fixed schedule, with zero unexplained position differences.
- Every submitted order reaches a known state or raises an alert within a defined interval, such as 10 seconds.
- Stale data, repeated rejections, excessive exposure or a broken event stream stop new orders.
- A kill control blocks new entries and leaves a documented path to cancel open orders or reduce exposure.
For the final week, rehearse a broker outage, expired credentials, a process restart and a delayed fill report. Record who or what owns each recovery action, even if no person is watching continuously.
Keep raw request IDs, broker messages and state transitions long enough to reconstruct an incident. Review rate limits and permissions again before increasing size.
Most broker APIs were designed for software that waits for a person to notice the exception.
Frequently Asked Questions
What should a broker API support for automated trading?
It should expose account and position data, order entry and updates, cancel operations, clear rejection reasons and usable rate-limit information. For unattended trading, it also needs a way to reconcile orders after timeouts or restarts.
How long does broker API integration take?
A basic integration can be built in days, but solid unattended operation usually needs several weeks of testing. A 30-day plan allows time to map the contract, implement state recovery, test failure cases and stage deployment.
Can a paper trading API validate live execution?
It can test order logic, state handling and some risk controls. It may not reproduce queue priority, market impact, borrow availability or all live rejection conditions, so paper results should not be treated as proof of live fills.
