# 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](https://firstock.in/api/docs/request-responses/) 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

1. **Throttling:** Implement client-side logic to queue or delay requests if you’re nearing the 10-per-second threshold.
2. **Batching:** Use multi-quote or multi-scrip endpoints where available, reducing separate calls.
3. **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](https://firstock.in/api/docs/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://mindorigin1.gitbook.io/mindorigin1/api-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.