# Timings

## Market Timings

### Endpoint URL

This API retrieves market trading timings for a specific date across all Indian stock exchanges.

```http
Local Host   :  POST http://127.0.0.1:5000/api/v1/market/timings
Ngrok Domain :  POST https://<your-ngrok-domain>.ngrok-free.app/api/v1/market/timings
Custom Domain:  POST https://<your-custom-domain>/api/v1/market/timings
```

### Sample API Request

```json
{
    "apikey": "<your_app_apikey>",
    "date": "2025-12-18"
}
```

### Sample API Response (Normal Trading Day)

```json
{
    "status": "success",
    "data": [
        {"exchange": "NSE", "start_time": 1745984700000, "end_time": 1746007200000},
        {"exchange": "BSE", "start_time": 1745984700000, "end_time": 1746007200000},
        {"exchange": "NFO", "start_time": 1745984700000, "end_time": 1746007200000},
        {"exchange": "BFO", "start_time": 1745984700000, "end_time": 1746007200000},
        {"exchange": "MCX", "start_time": 1745983800000, "end_time": 1746037500000},
        {"exchange": "BCD", "start_time": 1745983800000, "end_time": 1746012600000},
        {"exchange": "CDS", "start_time": 1745983800000, "end_time": 1746012600000}
    ]
}
```

### Sample API Response (Holiday - Empty)

```json
{
    "status": "success",
    "data": []
}
```

### Sample API Response (Muhurat Trading - Special Session)

```json
{
    "status": "success",
    "data": [
        {"exchange": "NSE", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "BSE", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "NFO", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "BFO", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "CDS", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "BCD", "start_time": 1730469000000, "end_time": 1730473500000},
        {"exchange": "MCX", "start_time": 1730469000000, "end_time": 1730491500000}
    ]
}
```

### Sample API Response (Partial Holiday - MCX Open)

```json
{
    "status": "success",
    "data": [
        {"exchange": "MCX", "start_time": 1741964400000, "end_time": 1742018100000}
    ]
}
```

### Request Fields

| Parameter | Description                    | Mandatory/Optional | Default Value |
| --------- | ------------------------------ | ------------------ | ------------- |
| apikey    | App API key for authentication | Mandatory          | -             |
| date      | Date in YYYY-MM-DD format      | Mandatory          | -             |

### Response Fields

| Field  | Type   | Description                                        |
| ------ | ------ | -------------------------------------------------- |
| status | String | Response status: "success" or "error"              |
| data   | Array  | List of exchange timing objects (empty if holiday) |

#### Exchange Timing Object Fields

| Field       | Type    | Description                            |
| ----------- | ------- | -------------------------------------- |
| exchange    | String  | Exchange code (NSE, BSE, NFO, etc.)    |
| start\_time | Integer | Market open time (epoch milliseconds)  |
| end\_time   | Integer | Market close time (epoch milliseconds) |

### Default Market Timings (IST)

| Exchange | Start Time | End Time | Description              |
| -------- | ---------- | -------- | ------------------------ |
| NSE      | 09:15      | 15:30    | National Stock Exchange  |
| BSE      | 09:15      | 15:30    | Bombay Stock Exchange    |
| NFO      | 09:15      | 15:30    | NSE Futures & Options    |
| BFO      | 09:15      | 15:30    | BSE Futures & Options    |
| CDS      | 09:00      | 17:00    | Currency Derivatives     |
| BCD      | 09:00      | 17:00    | BSE Currency Derivatives |
| MCX      | 09:00      | 23:55    | Multi Commodity Exchange |

### Response Scenarios

| Scenario                 | Response                                   |
| ------------------------ | ------------------------------------------ |
| Normal trading day       | All 7 exchanges with default timings       |
| Weekend (Sat/Sun)        | Empty array `[]`                           |
| Full holiday             | Empty array `[]`                           |
| Partial holiday          | Only open exchanges (e.g., MCX evening)    |
| Muhurat Trading (Diwali) | All exchanges with special session timings |
| Settlement holiday       | All 7 exchanges with normal timings        |

### Example Usage

#### Get Timings for a Normal Day

```bash
curl -X POST "http://127.0.0.1:5000/api/v1/market/timings" \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your-api-key",
    "date": "2025-04-30"
  }'
```

#### Check if Market is Open on a Holiday

```bash
curl -X POST "http://127.0.0.1:5000/api/v1/market/timings" \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your-api-key",
    "date": "2025-12-25"
  }'
```

#### Check Muhurat Trading Timings

```bash
curl -X POST "http://127.0.0.1:5000/api/v1/market/timings" \
  -H "Content-Type: application/json" \
  -d '{
    "apikey": "your-api-key",
    "date": "2025-11-01"
  }'
```

### Python Example

```python
import requests
from datetime import datetime, timezone, timedelta

# IST timezone
IST = timezone(timedelta(hours=5, minutes=30))

# API endpoint
url = "http://127.0.0.1:5000/api/v1/market/timings"

# Request payload
payload = {
    "apikey": "your-api-key",
    "date": "2025-04-30"
}

# Make the request
response = requests.post(url, json=payload)

# Parse the response
if response.status_code == 200:
    data = response.json()
    if data['status'] == 'success':
        if not data['data']:
            print("Market is closed (holiday/weekend)")
        else:
            print(f"Market timings for {payload['date']}:")
            for timing in data['data']:
                start = datetime.fromtimestamp(timing['start_time']/1000, IST)
                end = datetime.fromtimestamp(timing['end_time']/1000, IST)
                print(f"  {timing['exchange']}: {start.strftime('%H:%M')} - {end.strftime('%H:%M')}")
    else:
        print(f"Error: {data['message']}")
else:
    print(f"HTTP Error: {response.status_code}")
```

### JavaScript Example

```javascript
const getMarketTimings = async (date) => {
    const url = "http://127.0.0.1:5000/api/v1/market/timings";

    const payload = {
        apikey: "your-api-key",
        date: date
    };

    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
        });

        const data = await response.json();

        if (data.status === 'success') {
            if (data.data.length === 0) {
                console.log("Market is closed (holiday/weekend)");
            } else {
                console.log(`Market timings for ${date}:`);
                data.data.forEach(timing => {
                    const start = new Date(timing.start_time);
                    const end = new Date(timing.end_time);
                    console.log(`  ${timing.exchange}: ${start.toLocaleTimeString('en-IN')} - ${end.toLocaleTimeString('en-IN')}`);
                });
            }
        } else {
            console.error(`Error: ${data.message}`);
        }
    } catch (error) {
        console.error('Request failed:', error);
    }
};

// Usage
getMarketTimings("2025-04-30");
```

### Error Response

```json
{
    "status": "error",
    "message": "Invalid date format. Use YYYY-MM-DD"
}
```

### Error Codes

| HTTP Status | Error Type   | Description                    |
| ----------- | ------------ | ------------------------------ |
| 200         | Success      | Request processed successfully |
| 400         | Bad Request  | Invalid date format            |
| 403         | Forbidden    | Invalid API key                |
| 500         | Server Error | Internal server error          |

### Error Messages

| Message                                          | Description                 |
| ------------------------------------------------ | --------------------------- |
| "Invalid date format. Use YYYY-MM-DD"            | Date not in correct format  |
| "Date must be between 2020-01-01 and 2050-12-31" | Date out of supported range |

### Notes

* Timestamps are in epoch milliseconds
* Empty `data` array indicates market is closed (holiday or weekend)
* MCX has extended evening hours (09:00-23:55) on normal trading days
* On equity holidays, MCX often has evening-only sessions
* Muhurat Trading is a special \~1 hour session on Diwali
* Settlement holidays return normal timings (trading is open)
* Data is cached for 1 hour for performance

### Common Use Cases

1. **Pre-market Checks**: Verify if market is open before placing orders
2. **Scheduling Trades**: Plan order execution based on market hours
3. **MCX Evening Trading**: Check if MCX evening session is available
4. **Muhurat Trading**: Get special session timings on Diwali
5. **Holiday Detection**: Determine if a date is a market holiday

### Rate Limits

This API endpoint is subject to rate limiting. The default rate limit is 10 requests per second per API key.


---

# 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://docs.openalgo.in/api-documentation/v1/utilities-api/timings.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.