API Overview
The Developer API is a suite of REST and WebSocket endpoints that lets you:
- Integrate trading workflows (placing, modifying, and cancelling orders).
- Fetch market data (real-time quotes, historical candlesticks, etc.).
- Access and manage account details (positions, balances, etc.).
Key Features
- Security & Authentication: Token-based auth ensures secure data exchanges.
- Real-Time Events: WebSocket channels provide immediate updates on market moves and order statuses.
- Developer-Centric: Standardised JSON responses, consistent error structures, and detailed reference docs.
This API forms the backbone for building custom trading applications, algorithmic strategies, or specialised dashboards—empowering developers to craft unique user experiences around robust brokerage infrastructure.
Request & Response
Firstock APIs generally communicate via JSON-encoded messages over HTTPS (for REST) or WSS (for WebSockets). Understanding how requests and responses are structured is crucial for smooth integrations.
Request Structure
- HTTP Method: Typically POST for data-altering operations (order placement, modifications) and GET or POST for data retrieval (varies by endpoint).
- Headers:
- Content-Type: application/json
- Additional headers if required (e.g., authentication tokens).
- Body: Usually a JSON object containing fields like userId, jKey, plus endpoint-specific parameters (tradingSymbol, exchange, etc.).
Response Format
- status: success or failed.
- message: A short, human-readable note about the outcome (e.g., "Order placed successfully").
- data (on success): Includes payload relevant to the call, such as quotes, order details, or expiry lists.
- error (on failure): If status = "failed", an error object details which field or parameter caused the issue.
Reference: For a deeper look at real examples, see the official Request & Response documentation.
Rate Limit
To ensure service stability and fair usage, there is a rate limit of 10 requests per second per user/account. If your client application exceeds this threshold, you may receive a code = "429" (Too Many Requests) error response.
Best Practices for Rate Limit
- Throttling: Implement client-side logic to queue or delay requests if you’re nearing the 10-per-second threshold.
- Batching: Use multi-quote or multi-scrip endpoints where available, reducing separate calls.
- Backoff Strategy: On a 429 response, wait briefly before retrying to avoid subsequent throttling.
Keeping within 10 requests per second ensures you don’t trigger rate-limit errors and helps maintain a reliable experience for all users.
Versioning
Firstock employs a versioning strategy that delivers new features, performance upgrades, and security enhancements with minimal disruption to existing integrations. Each iteration is typically labeled (e.g., V3, V4, or the new Developer v1 approach).
Key Versioning Principles
- Backward Compatibility: Most older endpoints remain functional, reducing major refactor needs when upgrading.
- Incremental Changes: Performance improvements and new endpoints appear in the latest version (e.g., Developer v1).
- Minimal Breaking Changes: Breaking changes are clearly documented, with recommended migration paths.
Why Upgrade
- Faster Data Throughput: New releases often bring improved architecture for lower latency.
- Enhanced Security: Updated encryption, token flows, or session handling.
- Modern Features: WebSocket expansions, new order types, or advanced analytics endpoints.
For a detailed timeline of changes and upgrading guidelines, see the Versioning doc.
Conclusion
The Developer API is a powerful gateway for integrating advanced trading functionalities into your applications. By adhering to request/response standards, respecting the 10 requests/second rate limit, and staying aware of versioning best practices, you can create stable, high-performance trading solutions. For more information on error handling or advanced features, see the official Exception & Error Handling doc or explore specialised endpoints in the reference documentation.
