Getting Started
What Is an API-First Trading Platform?
Photo by Luca Bravo on Unsplash
Most retail trading platforms were built for a specific user: a person clicking buttons. The API was added later, usually as a feature for power users — an afterthought bolted onto infrastructure designed for manual operation. The result is an API that exposes a subset of what the GUI can do, has rate limits optimized for human-speed interaction, and requires workarounds for anything resembling real automation.
An API-first trading platform is one where the API is the primary interface. The GUI, if one exists, is built on top of the same API that external code uses. Every capability available to the interface is available to code, with the same reliability and without the friction of an adapter layer.
For systematic traders, the difference is not cosmetic. It determines which strategies are even possible to run.
What API-First Means in Practice
An API-first design principle means the platform's core functionality is exposed as a programmable interface before a graphical one is built. The engineering team writes code against the API before the design team builds a visual layer. Everything accessible to the GUI is accessible to code.
In trading platform terms, this means:
- Order submission and management — market orders, limit orders, stop-loss, bracket orders — all fully programmable without workarounds
- Account state — buying power, positions, open orders, filled orders — available as structured data, not scraped from HTML
- Market data — real-time quotes, historical bars, order book snapshots — available via authenticated endpoints with documented rate limits designed for programmatic access
- Event streaming — order fill notifications, position updates, account changes — delivered via websocket or server-sent events, not requiring polling
The architecture flows cleanly when the API is the foundation:
With a GUI-first platform, your code hits an adapter layer between the API and the execution engine — introducing gaps, rate limits designed for humans, and missing order types.
Why GUI-First Platforms Break Systematic Strategies
The failure modes of GUI-first platforms become visible only after you try to automate them seriously.
| GUI-First Platform | API-First Platform | |
|---|---|---|
| Rate limits | Designed for human-speed (20–50 orders/day) | Designed for programmatic workloads |
| Order types | Complex types in GUI only, absent or broken in API | Full parity — anything the GUI does, the API does |
| State consistency | Two state layers — GUI and engine can diverge | Single source of truth, GUI reads from API |
| WebSocket | UI refresh mechanism, not reliable message delivery | Reliable delivery with heartbeat and reconnect docs |
| Paper trading | Separate environment, different endpoints | Same endpoints as live — code runs unchanged |
State inconsistency deserves specific attention. GUI-first platforms often maintain two layers of state: the visual state shown to the user and the underlying state in the trading engine. For a human using the GUI, they usually agree. For code calling the API while the GUI is also active, edge cases produce inconsistencies. An automated strategy that assumes the API is the source of truth encounters unexpected behavior when the GUI's state management interferes.
None of these problems are insurmountable. Developers work around them. But workarounds introduce complexity, reduce reliability, and shift engineering effort from strategy logic to infrastructure management.
What API-First Trading Enables
When the platform is designed API-first, the structural constraints above largely disappear. The capabilities developers need are present by design, not by accident.
Paper trading with the same API is the critical capability for testing a strategy before live deployment. Code written for paper trading runs on live trading without modification. This removes an entire class of deployment bugs that appear when paper and live environments behave differently.
Alpaca is the primary API-first retail trading platform at production scale. Its design reflects this philosophy: the Python SDK wraps a REST API that has no corresponding GUI for most of its functionality. The API is the product.
The Developer Advantage
The practical implication of API-first architecture is that systematic strategies are first-class use cases, not edge cases.
A systematic trader using an API-first platform spends engineering effort on strategy logic: signal generation, risk management, position sizing, exit conditions. The infrastructure works as documented. Rate limits are designed for the workload. State is consistent. Event delivery is reliable.
A systematic trader working around a GUI-first platform spends engineering effort on infrastructure: building retry logic for rate-limited endpoints, polling for state updates that should be pushed, working around missing order types, handling state inconsistencies. The strategy logic exists, but it's buried under layers of defensive code that exist because the platform wasn't designed for this use case.
The compounding effect over time is significant. A developer with a reliable API-first foundation iterates on strategy logic. A developer fighting infrastructure limitations iterates slowly and ships defensive code rather than strategy improvements.
What does "rate limiting" actually mean for a trading bot?
Rate limiting caps how many API requests your code can make in a given time window. A limit of 200 requests per minute means your bot can query account state, submit orders, and fetch prices a combined 200 times per minute. A systematic strategy running 15 securities with 1-minute signal updates needs roughly 15–30 requests per signal cycle, plus order management overhead. On a platform with a 30-request-per-minute limit (designed for a human checking a few positions), that strategy hits the ceiling immediately. On an API-first platform with limits designed for automation, 200–500 requests per minute is a baseline expectation, not a premium tier.
What makes WebSocket delivery "reliable" for automated systems?
A WebSocket is a persistent connection that pushes events to your code as they happen — order fills, price updates, account changes. GUI-first platforms often implement WebSocket as a UI refresh layer: if the connection drops, the user refreshes the page. For an automated system, a dropped WebSocket with no reconnection protocol means missed fill notifications and stale position state. A production-grade WebSocket implementation documents: heartbeat interval (how often the server confirms the connection is alive), reconnection behavior (what your client should do when the connection drops), message sequencing (how to detect gaps in the event stream), and backpressure (what happens when your consumer is slower than the feed). Alpaca's WebSocket documentation covers all four. Most GUI-first platform APIs document none of them.
The Oyamori Approach
Oyamori's execution layer is built on Alpaca's API-first infrastructure. The choice is deliberate: systematic strategy deployment requires the reliability and completeness that API-first architecture provides. Order management, position tracking, risk parameter enforcement, and event-driven execution all depend on the API behaving consistently and completely.
The CLI workflow reflects this. Every operation — deploying a strategy, adjusting parameters, reviewing execution logs — is accessible programmatically. Nothing requires a GUI interaction. The platform is designed for operators who want to automate, inspect, and control their trading infrastructure through code.
API-first is not a marketing designation. It is an architectural decision that either limits or enables systematic trading at the execution layer. For systematic traders, it is the prerequisite everything else depends on.