### Upgrade example: Starter 3M to Professional 3M

Source: https://indexalpha.id/docs/limits

Three-step upgrade example: starting package, upgrade event calculation, and resulting plan after upgrade. Shows how the unused value of the current period is credited toward the new plan's price and that the quota and period restart at the new duration.

```text
Plan: Starter 3M
Price paid: Rp500,000
Period: Jan 1 → Apr 1 (90 days)
Remaining days at upgrade: 45
Quota: 25,000 per 30-day cycle
```

```text
Upgrade to: Professional 3M
Price: Rp875,000 / 90 days
Daily rate Starter 3M: 500,000 / 90 = Rp5,556
Unused Starter value:  5,556 × 45 ≈ Rp250,000
Charge:                875,000 − 250,000 ≈ Rp625,000 (rounded down to the nearest Rp1,000)
```

```text
Plan: Professional 3M
Rate limit: 300 req/min
Quota: 100,000 per 30-day cycle (fresh)
period: fresh 90 days from today
```

--------------------------------

### Install MCP SDK and create index-alpha-mcp.js server

Source: https://indexalpha.id/docs/ai-integration

Install the MCP SDK and create the server file. The server requires the INDEX_ALPHA_API_KEY environment variable; it exits with an error if missing.

```bash
npm install @modelcontextprotocol/sdk
```

```javascript
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import fetch from "node-fetch";

const API_KEY = process.env.INDEX_ALPHA_API_KEY;
if (!API_KEY) {
  console.error("Error: INDEX_ALPHA_API_KEY environment variable is required.");
  process.exit(1);
}

const server = new Server(
  {
    name: "index-alpha-mcp-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
```

--------------------------------

### Example GET response: broker-summary JSON structure

Source: https://indexalpha.id/docs/quickstart

This shows the JSON structure returned by the first GET request to /stocks/broker-summary. The success field is true on success, error is null, and data contains one row per broker. buy_value and sell_value are in IDR, volume is in shares, and buy_avg and sell_avg are weighted average prices.

```json
{
  "success": true,
  "data": [
    {
      "code": "SQ",
      "buy_freq": 4044,
      "buy_volume": 26837300,
      "buy_value": 185357180000,
      "sell_freq": 586,
      "sell_volume": 1499300,
      "sell_value": 10374017500,
      "buy_avg": 6906.70,
      "sell_avg": 6919.24
    }
  ],
  "error": null
}
```

--------------------------------

### GET /usage Request

Source: https://indexalpha.id/docs/endpoints

Request to monitor monthly call usage and remaining quota.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/usage' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

--------------------------------

### Broker Summary Example Request

Source: https://indexalpha.id/docs/endpoints

Retrieves aggregated broker activity for ticker BBCA on a single day (2026-03-26) for all investors. Requires a valid API token in the Authorization header.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2026-03-26&to=2026-03-26&investor=all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

--------------------------------

### Fetch broker summary with curl

Source: https://indexalpha.id/docs/client-examples

A basic GET request to the broker-summary endpoint using curl. Replace <YOUR_API_KEY> with your actual API key.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2026-03-26&to=2026-03-26&investor=all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

--------------------------------

### GET /usage Response Format

Source: https://indexalpha.id/docs/endpoints

The response provides key-level and account-level usage statistics.

```json
{
	"success": true,
	"data": {
		"api_key": "ia_l...H_Qv",
		"key": {
			"key_id": "uuid-of-your-key",
			"key_name": "Default Key",
			"current_usage": 3,
			"monthly_limit": 25000,
			"remaining": 24997
		},
		"account": {
			"plan": "Starter",
			"current_usage": 42,
			"monthly_limit": 25000,
			"remaining": 24958,
			"period_end": "2026-08-29T00:00:00",
			"is_active": true
		}
	},
	"error": null
}
```

--------------------------------

### Batch Broker Summary Request

Source: https://indexalpha.id/docs/endpoints

Example cURL request to retrieve broker summaries for BBCA, BBRI, and TLKM tickers.

```bash
curl -X 'POST' \
  'https://api.indexalpha.id/stocks/broker-summary/batch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "tickers": ["BBCA", "BBRI", "TLKM"],
    "from": "2026-03-26",
    "to": "2026-03-26",
    "investor": "all",
    "market": "RG"
  }'
```

--------------------------------

### GET /stocks/ohlcv Request

Source: https://indexalpha.id/docs/endpoints

Example cURL request to retrieve daily OHLCV data for a specific ticker and date range, requiring an API token for authorization.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/ohlcv?ticker=BBCA&from=2026-09-01&to=2026-09-07' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

--------------------------------

### GET /stocks/broker-summary

Source: https://indexalpha.id/docs/ai-integration

Retrieves daily broker transaction summaries for a stock ticker.

```APIDOC
## GET /stocks/broker-summary

### Description
Retrieves daily broker transaction summaries for a stock ticker.

### Method
GET

### Endpoint
/stocks/broker-summary

### Parameters
#### Query Parameters
- **ticker** (string) - Required - Stock ticker symbol (e.g., `BBCA`, `TLKM`)
- **from** (string) - Required - Start date in YYYY-MM-DD format (2025-01-01 or later)
- **to** (string) - Required - End date in YYYY-MM-DD format
- **investor** (string) - Required - One of `all`, `f` (foreign), `d` (domestic)

### Response
#### Success Response (200)
- **code** (string) - Broker initials
- **buy_freq** (number) - Buy frequency
- **buy_volume** (number) - Buy volume
- **buy_value** (number) - Buy value
- **sell_freq** (number) - Sell frequency
- **sell_volume** (number) - Sell volume
- **sell_value** (number) - Sell value
- **buy_avg** (number) - Weighted average buy price
- **sell_avg** (number) - Weighted average sell price

#### Response Example
```json
[
  {
    "code": "string",
    "buy_freq": 0,
    "buy_volume": 0,
    "buy_value": 0,
    "sell_freq": 0,
    "sell_volume": 0,
    "sell_value": 0,
    "buy_avg": 0,
    "sell_avg": 0
  }
]
```
```

--------------------------------

### GET /usage

Source: https://indexalpha.id/docs/endpoints

Monitors your monthly call usage and remaining quota. Returns key-level and account-level usage information.

```APIDOC
## GET /usage

### Description
Monitors your monthly call usage and remaining quota. Returns key-level and account-level usage information.

### Method
GET

### Endpoint
/usage

### Parameters
#### Query Parameters
None.

### Request Example
```
curl -X 'GET' \
  'https://api.indexalpha.id/usage' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains usage details.
  - **api_key** (string) - The API key identifier.
  - **key** (object) - Key-level usage information.
    - **key_id** (string) - UUID of the key.
    - **key_name** (string) - Name of the key.
    - **current_usage** (integer) - Current usage count for the key.
    - **monthly_limit** (integer) - Monthly limit for the key.
    - **remaining** (integer) - Remaining quota for the key.
  - **account** (object) - Account-level usage information.
    - **plan** (string) - Subscribed plan name.
    - **current_usage** (integer) - Current usage count for the account.
    - **monthly_limit** (integer) - Monthly limit for the account.
    - **remaining** (integer) - Remaining quota for the account.
    - **period_end** (string) - End date of the current billing period.
    - **is_active** (boolean) - Whether the plan is active.
- **error** (null) - Error message, if any.

#### Response Example
```
{
	"success": true,
	"data": {
		"api_key": "ia_l...H_Qv",
		"key": {
			"key_id": "uuid-of-your-key",
			"key_name": "Default Key",
			"current_usage": 3,
			"monthly_limit": 25000,
			"remaining": 24997
		},
		"account": {
			"plan": "Starter",
			"current_usage": 42,
			"monthly_limit": 25000,
			"remaining": 24958,
			"period_end": "2026-08-29T00:00:00",
			"is_active": true
		}
	},
	"error": null
}
```
```

--------------------------------

### Make a first API request with curl: GET broker-summary

Source: https://indexalpha.id/docs/quickstart

Use this curl command to retrieve broker summary data for a single ticker (BBCA) for a given date range and investor type. Replace <your_api_key> with your bearer token for authentication. The from and to parameters are set to the same day, returning one day of aggregated data.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2026-03-26&to=2026-03-26&investor=all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_key>'
```

--------------------------------

### GET /foreign-flow Request

Source: https://indexalpha.id/docs/endpoints

Example cURL request to retrieve aggregated foreign flow for a specific ticker.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/foreign-flow?ticker=BBCA&from=2026-07-01&to=2026-07-28' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

--------------------------------

### GET /usage

Source: https://indexalpha.id/docs/ai-integration

Returns API quota status. Highly recommended to run periodically to avoid rate limits or exhaustion.

```APIDOC
## GET /usage

### Description
Returns API quota status. Highly recommended to run periodically to avoid rate limits or exhaustion.

### Method
GET

### Endpoint
/usage

### Parameters
None

### Response
#### Success Response (200)
- **monthly_limit** (number) - Monthly API call limit
- **current_usage** (number) - Current API usage
- **remaining** (number) - Remaining API calls
- **reset_date** (string) - Date when the quota resets

#### Response Example
```json
{
  "monthly_limit": 0,
  "current_usage": 0,
  "remaining": 0,
  "reset_date": "string"
}
```
```

--------------------------------

### Broker Summary NG Market Example

Source: https://indexalpha.id/docs/endpoints

Retrieves broker summary for ticker BBCA on 2025-01-02 in the Negotiated Market (NG) by adding the market=NG query parameter.

```bash
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2025-01-02&to=2025-01-02&investor=all&market=NG' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

--------------------------------

### Batch request with curl: POST broker-summary batch

Source: https://indexalpha.id/docs/quickstart

Use this curl command to send a batch request to POST /stocks/broker-summary/batch. Each ticker in the batch consumes one unit of quota; for example, a batch of 50 tickers costs 50 units. The response maps each ticker to an array of broker rows.

```bash
curl -X 'POST' \
  'https://api.indexalpha.id/stocks/broker-summary/batch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_api_key>' \
  -d '{
    "tickers": ["BBCA", "BBRI", "TLKM"],
    "from": "2026-03-26",
    "to": "2026-03-26",
    "investor": "all",
    "market": "RG"
  }'
```

--------------------------------

### GET /stocks/broker-summary

Source: https://indexalpha.id/docs/ai-integration

Retrieve aggregated daily activity for brokers on a specific stock ticker. Records are updated every trading day at 12:00 GMT (19:00 Jakarta time). Historical data is available starting from 2025-01-01.

```APIDOC
## GET /stocks/broker-summary

### Description
Retrieve aggregated daily activity for brokers on a specific stock ticker. Records are updated every trading day at 12:00 GMT (19:00 Jakarta time). Historical data is available starting from 2025-01-01.

### Method
GET

### Endpoint
https://api.indexalpha.id/stocks/broker-summary

### Parameters
#### Query Parameters
- **ticker** (string) - Required - Stock ticker symbol (e.g., BBCA, TLKM)
- **from** (string, date) - Required - Start date in YYYY-MM-DD format (2025-01-01 or later)
- **to** (string, date) - Required - End date in YYYY-MM-DD format
- **investor** (string) - Required - Type of investor to aggregate. Allowed values: all, f, d

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - Array of broker summary objects.
  - **code** (string) - Broker code (e.g., SQ, AK, CC)
  - **buy_freq** (integer) - Number of buy transactions
  - **buy_volume** (integer) - Total share volume purchased
  - **buy_value** (number) - Total transaction value of purchases (in IDR)
  - **sell_freq** (integer) - Number of sell transactions
  - **sell_volume** (integer) - Total share volume sold
  - **sell_value** (number) - Total transaction value of sales (in IDR)
  - **buy_avg** (number) - Weighted average buy price
  - **sell_avg** (number) - Weighted average sell price
- **error** (string, nullable) - Error message if any.

#### Error Response (400)
Bad Request. Invalid parameters (e.g., dates before coverage start or a range longer than 366 days).

#### Error Response (401)
Unauthorized. Authentication required.
```

--------------------------------

### POST /foreign-flow/batch Request

Source: https://indexalpha.id/docs/endpoints

Example cURL request to retrieve aggregated foreign flow for multiple tickers in one call.

```bash
curl -X 'POST' \
  'https://api.indexalpha.id/foreign-flow/batch' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_api_token>' \
  -d '{
    "tickers": ["BBCA", "BBRI", "TLKM"],
    "from": "2026-07-01",
    "to": "2026-07-28",
    "market": "ALL"
  }'
```

--------------------------------

### Handle MCP tool calls with CallToolRequestSchema

Source: https://indexalpha.id/docs/ai-integration

Starts the handler for incoming tool calls using the CallToolRequestSchema. It destructures the tool name and arguments from the request parameters, but the snippet is incomplete and does not show the rest of the handler logic.

```javascript
// Handle Tool Calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

```

--------------------------------

### GET /news Response Format

Source: https://indexalpha.id/docs/endpoints

The response maps source names to an array of articles. Only sources with at least one article are included.

```json
{
	"success": true,
	"data": {
		"CNBC-Indonesia": [
			{
				"source": "CNBC-Indonesia",
				"title": "IHSG Ditutup Menguat",
				"description": "Indeks Harga Saham Gabungan ditutup menguat…",
				"link": "https://www.cnbcindonesia.com/market/…",
				"image_url": "https://…",
				"guid": "…",
				"published_date": "2026-09-02T07:30:49Z"
			}
		],
		"Stockwatch": [
			{
				"source": "Stockwatch",
				"title": "…",
				"description": "…",
				"link": "https://stockwatch.id/…",
				"image_url": "",
				"guid": null,
				"published_date": "2026-09-02T06:00:00Z"
			}
		]
	},
	"error": null
}
```

--------------------------------

### GET /news

Source: https://indexalpha.id/docs/endpoints

Fetches the latest articles from Indonesian market news RSS feeds, grouped by source. Articles are fetched from publisher RSS feeds at request time and held only in a short 30-second cache.

```APIDOC
## GET /news

### Description
Fetches the latest articles from Indonesian market news RSS feeds, grouped by source. Articles are fetched from publisher RSS feeds at request time and held only in a short 30-second cache.

### Method
GET

### Endpoint
/news

### Parameters
#### Query Parameters
None.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Maps each source name to a newest-first array of articles.
  - **source** (string) - Source name (e.g. `CNBC-Indonesia`, `Stockwatch`).
  - **title** (string) - Article headline (HTML stripped).
  - **description** (string) - Summary text (HTML stripped).
  - **link** (string) - URL to the full article.
  - **image_url** (string) - Thumbnail/hero image URL, or `""` when none.
  - **guid** (string / null) - Feed unique identifier when the feed provides one.
  - **published_date** (string / null) - ISO-8601 UTC timestamp, or `null` when unparseable.
- **error** (null) - Error message, if any.

#### Response Example
```
{
	"success": true,
	"data": {
		"CNBC-Indonesia": [
			{
				"source": "CNBC-Indonesia",
				"title": "IHSG Ditutup Menguat",
				"description": "Indeks Harga Saham Gabungan ditutup menguat…",
				"link": "https://www.cnbcindonesia.com/market/…",
				"image_url": "https://…",
				"guid": "…",
				"published_date": "2026-09-02T07:30:49Z"
			}
		],
		"Stockwatch": [
			{
				"source": "Stockwatch",
				"title": "…",
				"description": "…",
				"link": "https://stockwatch.id/…",
				"image_url": "",
				"guid": null,
				"published_date": "2026-09-02T06:00:00Z"
			}
		]
	},
	"error": null
}
```
```

--------------------------------

### GET /foreign-flow Response

Source: https://indexalpha.id/docs/endpoints

The JSON response format for a successful foreign flow query.

```json
{
	"success": true,
	"data": {
		"foreign_buy": 125000000000,
		"foreign_sell": 83000000000,
		"net_foreign": 42000000000
	},
	"error": null
}
```

--------------------------------

### GET /stocks/ohlcv

Source: https://indexalpha.id/docs/endpoints

Retrieves daily open, high, low, close, and volume bars for a stock ticker. Prices are not adjusted for stock splits, and missing trading dates are omitted.

```APIDOC
## GET /stocks/ohlcv

### Description
Retrieve daily open, high, low, close and volume bars for a stock ticker. Prices and volume are not adjusted for stock splits, and missing trading dates are omitted.

### Method
GET

### Endpoint
/stocks/ohlcv

### Parameters
#### Query Parameters
- **ticker** (String) - Required - Stock ticker symbol (e.g., `BBCA`, `DSSA`)
- **from** (Date) - Required - Start date in `YYYY-MM-DD` format
- **to** (Date) - Required - End date in `YYYY-MM-DD` format (max 366-day span)

### Request Example
```
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/ohlcv?ticker=BBCA&from=2026-09-01&to=2026-09-07' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (array) - Array of OHLCV objects
  - **date** (string) - Trading date in `YYYY-MM-DD` format
  - **open** (number) - Opening price
  - **high** (number) - Highest price
  - **low** (number) - Lowest price
  - **close** (number) - Closing price
  - **volume** (integer) - Trading volume
- **error** (null) - Error message, null if successful

#### Response Example
```
{
	"success": true,
	"data": [
		{
			"date": "2026-09-07",
			"open": 7800,
			"high": 7925,
			"low": 7750,
			"close": 7850,
			"volume": 123456700
		}
	],
	"error": null
}
```
```

--------------------------------

### GET /stocks/broker-summary

Source: https://indexalpha.id/docs/endpoints

Retrieves aggregated daily activity for brokers on a specific stock ticker. Date ranges are aggregated, not per-day, and foreign flow returns a single total for the range. Request single days (from=to) for daily records.

```APIDOC
## GET /stocks/broker-summary

### Description
Retrieve aggregated daily activity for brokers on a specific stock ticker. Date ranges are aggregated, not per-day. A request for `from=2025-01-01` to `to=2025-01-31` returns one row per broker for the whole month (totals across the range), not 30 separate daily rows. Foreign flow returns a single total for the range. Request single days (`from` = `to`) if you need daily records.

### Method
GET

### Endpoint
/stocks/broker-summary

### Parameters
#### Query Parameters
- **ticker** (String) - Required - Stock ticker symbol (e.g., `BBCA`, `TLKM`)
- **from** (Date) - Required - Start date in `YYYY-MM-DD` format
- **to** (Date) - Required - End date in `YYYY-MM-DD` format
- **investor** (Enum) - Required - Type of investor. One of: `all` (all investors), `f` (foreign), `d` (domestic).
- **market** (Enum) - Optional - Market segment: `RG` (Regular, default), `NG` (Negotiated), `ALL` (both). NG available from 2025-01-01.

### Request Example
```
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2026-03-26&to=2026-03-26&investor=all' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - Array of broker summary objects.
  - **code** (string) - Broker code.
  - **buy_freq** (integer) - Buy frequency.
  - **buy_volume** (integer) - Buy volume.
  - **buy_value** (integer) - Buy value.
  - **sell_freq** (integer) - Sell frequency.
  - **sell_volume** (integer) - Sell volume.
  - **sell_value** (integer) - Sell value.
  - **buy_avg** (number) - Average buy price.
  - **sell_avg** (number) - Average sell price.
- **error** (null) - Error message, null if no error.

#### Response Example
```
{
	"success": true,
	"data": [
		{
			"code": "SQ",
			"buy_freq": 4044,
			"buy_volume": 26837300,
			"buy_value": 185357180000,
			"sell_freq": 586,
			"sell_volume": 1499300,
			"sell_value": 10374017500,
			"buy_avg": 6906.7,
			"sell_avg": 6919.24
		},
		{
			"code": "AK",
			"buy_freq": 4355,
			"buy_volume": 16591800,
			"buy_value": 114517012500,
			"sell_freq": 5542,
			"sell_volume": 19340600,
			"sell_value": 133580562500,
			"buy_avg": 6902.02,
			"sell_avg": 6906.74
		}
	],
	"error": null
}
```

### NG Market Example
```
curl -X 'GET' \
  'https://api.indexalpha.id/stocks/broker-summary?ticker=BBCA&from=2025-01-02&to=2025-01-02&investor=all&market=NG' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```
```

--------------------------------

### GET /stocks/ohlcv Response Format

Source: https://indexalpha.id/docs/endpoints

The JSON response structure for the OHLCV endpoint, containing a success flag, the data array with daily price and volume metrics, and an error field.

```json
{
	"success": true,
	"data": [
		{
			"date": "2026-09-07",
			"open": 7800,
			"high": 7925,
			"low": 7750,
			"close": 7850,
			"volume": 123456700
		}
	],
	"error": null
}
```

--------------------------------

### Renewal example: Professional plan

Source: https://indexalpha.id/docs/limits

Shows the effect of renewing a Professional plan 10 days before the period ends: the period extends by 30 days while the quota remains unchanged and resets at the cycle boundary. Use this to understand that renewal does not refill quota.

```text
Plan:                   Professional
Price paid:            Rp350,000
Renewal on:            day 20 of the current 30-day cycle
What changes:          periodEnd extends by 30 days
Quota:                 unchanged - still 100,000, resets at the cycle boundary
```

--------------------------------

### OpenAPI 3.0 Specification for IndexAlpha API

Source: https://indexalpha.id/docs/ai-integration

OpenAPI 3.0 specification for the IndexAlpha API. Defines the /foreign-flow GET endpoint and the /foreign-flow/batch POST endpoint, including request parameters, request body schema, and response schemas. Includes error responses for bad requests, unauthorized access, quota exhaustion, validation errors, rate limiting, and internal errors.

```json
{
  "openapi": "3.0.0",
  "info": {
    "title": "IndexAlpha API",
    "version": "1.0.0",
    "description": "API for stock market data including foreign flow and stock summary."
  },
  "paths": {
    "/foreign-flow": {
      "get": {
        "summary": "Get Foreign Flow",
        "description": "Returns aggregated foreign buy, sell, and net trading activity for a stock ticker over a date range. Aggregated across all foreign brokers.",
        "parameters": [
          {
            "name": "ticker",
            "in": "query",
            "required": true,
            "description": "Stock ticker symbol (e.g., BBCA, TLKM)",
            "schema": { "type": "string" }
          },
          {
            "name": "from",
            "in": "query",
            "required": true,
            "description": "Start date in YYYY-MM-DD format",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "description": "End date in YYYY-MM-DD format",
            "schema": { "type": "string", "format": "date" }
          },
          {
            "name": "market",
            "in": "query",
            "required": false,
            "description": "Market segment (RG, NG, ALL). Default ALL.",
            "schema": { "type": "string", "enum": ["ALL", "RG", "NG"] }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response containing foreign flow data.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "foreign_buy": { "type": "integer", "description": "Total foreign buy transaction value (IDR)" },
                        "foreign_sell": { "type": "integer", "description": "Total foreign sell transaction value (IDR)" },
                        "net_foreign": { "type": "integer", "description": "Net foreign flow (foreign_buy - foreign_sell)" }
                      }
                    },
                    "error": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad Request. Invalid parameters (e.g., dates before coverage start or a range longer than 366 days)." },
          "401": { "description": "Unauthorized. Missing or invalid Bearer token." },
          "403": { "description": "Forbidden. Monthly or daily quota exhausted." },
          "422": { "description": "Validation error on the request parameters." },
          "429": { "description": "Too Many Requests. Rate limit exceeded." },
          "500": { "description": "Internal server error." }
        }
      }
    },
    "/foreign-flow/batch": {
      "post": {
        "summary": "Batch Foreign Flow",
        "description": "Retrieve aggregated foreign flow for multiple stock tickers in a single request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tickers": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "List of stock tickers (e.g. [\"BBCA\", \"TLKM\"]). Min 1, Max 50."
                  },
                  "from": { "type": "string", "format": "date", "description": "Start date in YYYY-MM-DD format" },
                  "to": { "type": "string", "format": "date", "description": "End date in YYYY-MM-DD format" },
                  "market": { "type": "string", "enum": ["ALL", "RG", "NG"], "description": "Market segment (default ALL)" }
                },
                "required": ["tickers", "from", "to"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response containing foreign flow data for each ticker.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean" },
                    "data": {
                      "type": "object",
                      "properties": {
                        "foreign_buy": { "type": "integer", "description": "Total foreign buy transaction value (IDR)" },
                        "foreign_sell": { "type": "integer", "description": "Total foreign sell transaction value (IDR)" },
                        "net_foreign": { "type": "integer", "description": "Net foreign flow (foreign_buy - foreign_sell)" }
                      }
                    },
                    "error": { "type": "string", "nullable": true }
                  }
                }
              }
            }
          },
          "400": { "description": "Bad Request. Invalid parameters (e.g., dates before coverage start or a range longer than 366 days)." },
          "401": { "description": "Unauthorized. Missing or invalid Bearer token." },
          "403": { "description": "Forbidden. Monthly or daily quota exhausted." },
          "422": { "description": "Validation error on the request parameters." },
          "429": { "description": "Too Many Requests. Rate limit exceeded." },
          "500": { "description": "Internal server error." }
        }
      }
    }
  }
}
```

--------------------------------

### Fetch broker summary with Python

Source: https://indexalpha.id/docs/client-examples

Uses the requests library to fetch and iterate over broker summary data. The script includes error handling via raise_for_status().

```python
import requests

API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://api.indexalpha.id"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"ticker": "BBCA", "from": "2026-03-26", "to": "2026-03-26", "investor": "all"}

resp = requests.get(f"{BASE_URL}/stocks/broker-summary", headers=headers, params=params)
resp.raise_for_status()
data = resp.json()["data"]

for row in data:
    print(row["code"], row["buy_value"], row["sell_value"])
```

--------------------------------

### Claude Desktop Configuration

Source: https://indexalpha.id/docs/mcp-remote-connection

Add the Index Alpha server to your claude_desktop_config.json file to enable integration.

```json
{
  "mcpServers": {
    "index-alpha": {
      "url": "https://api.indexalpha.id/mcp",
      "transport": "streamable-http"
    }
  }
}
```

--------------------------------

### Index Alpha API Integration Guidelines (Cursor/Copilot ruleset)

Source: https://indexalpha.id/docs/ai-integration

Ruleset to save as `.cursorrules` or `.github/copilot-instructions.md` in the project root. It instructs AI assistants to generate type-safe code compatible with Index Alpha, covering API base URL, Bearer token authorization, endpoint parameters, and TypeScript type conventions.

```markdown
# Index Alpha API Integration Guidelines

You are an expert developer building an integration with the Index Alpha API, which provides premium Indonesian Stock Exchange (IDX) broker summary analytics.

## API Architecture Reference
- Base URL: `https://api.indexalpha.id/`
- Authorization: Bearer Token required on all requests in the header: `Authorization: Bearer <token>`

## Available Endpoints

### 1. Retrieve Broker Summary (`GET /stocks/broker-summary`)
Returns daily broker transaction summaries for a stock ticker.
- **Parameters:**
  - `ticker` (string, required): Stock ticker symbol (e.g., `BBCA`, `TLKM`)
  - `from` (string, required, YYYY-MM-DD): Start date (2025-01-01 or later)
  - `to` (string, required, YYYY-MM-DD): End date
  - `investor` (string, required): One of `all`, `f` (foreign), `d` (domestic)
- **Output:** Returns an array of broker records with:
  - `code` (broker initials), `buy_freq`, `buy_volume`, `buy_value`, `sell_freq`, `sell_volume`, `sell_value`, `buy_avg` (weighted price), `sell_avg`

### 2. Batch Broker Summary (`POST /stocks/broker-summary/batch`)
Returns aggregated broker activity for multiple stock tickers.
- **Body:**
  - `tickers` (array[string], required): Stock tickers (e.g., `["BBCA", "TLKM"]`)
  - `from` (string, required, YYYY-MM-DD): Start date
  - `to` (string, required, YYYY-MM-DD): End date
  - `investor` (string, optional): One of `all`, `f`, `d`
  - `market` (string, optional): One of `RG`, `NG`, `ALL`

### 3. Foreign Flow (`GET /foreign-flow`)
Returns aggregated foreign buy, sell, and net trading activity for a stock ticker.
- **Parameters:**
  - `ticker` (string, required): Stock ticker symbol (e.g., `BBCA`, `TLKM`)
  - `from` (string, required, YYYY-MM-DD): Start date
  - `to` (string, required, YYYY-MM-DD): End date
  - `market` (string, optional): One of `ALL`, `RG`, `NG` (default `ALL`)

### 4. Batch Foreign Flow (`POST /foreign-flow/batch`)
Returns aggregated foreign flow for multiple stock tickers.
- **Body:**
  - `tickers` (array[string], required): Stock tickers (e.g., `["BBCA", "TLKM"]`)
  - `from` (string, required, YYYY-MM-DD): Start date
  - `to` (string, required, YYYY-MM-DD): End date
  - `market` (string, optional): One of `ALL`, `RG`, `NG`

### 5. Check Usage and Quotas (`GET /usage`)
Returns API quota status. Highly recommended to run periodically to avoid rate limits or exhaustion.
- **Output:** Returns `monthly_limit`, `current_usage`, `remaining`, `reset_date`.

### 6. Market News (`GET /news`)
Fetches the latest articles from Indonesian market news RSS feeds, grouped by source.
- **Parameters:** none
- **Output:** Returns an object mapping each source name to a newest-first array of articles with `source`, `title`, `description`, `link`, `image_url`, `guid`, `published_date`.

## Code Conventions (TypeScript)

Use the following strict types when building integrations:
```

--------------------------------

### GET /foreign-flow

Source: https://indexalpha.id/docs/ai-integration

Retrieve foreign buy/sell and net foreign flow for a single stock ticker over a date range.

```APIDOC
## GET /foreign-flow

### Description
Retrieve foreign buy/sell and net foreign flow for a single stock ticker over a date range.

### Method
GET

### Endpoint
/foreign-flow

### Parameters
#### Query Parameters
- **ticker** (string) - Required - Stock ticker symbol (e.g., BBCA)
- **from** (string, date) - Required - Start date in YYYY-MM-DD format
- **to** (string, date) - Required - End date in YYYY-MM-DD format
- **market** (string, enum: ALL, RG, NG) - Optional - Market segment (default ALL)

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains foreign flow data
  - **foreign_buy** (integer) - Total foreign buy transaction value (IDR)
  - **foreign_sell** (integer) - Total foreign sell transaction value (IDR)
  - **net_foreign** (integer) - Net foreign flow (foreign_buy - foreign_sell)
- **error** (string, nullable) - Error message if any

#### Response Example
{
  "success": true,
  "data": {
    "foreign_buy": 1000000,
    "foreign_sell": 500000,
    "net_foreign": 500000
  },
  "error": null
}

#### Error Responses
- **400** - Bad Request. Invalid parameters (e.g., dates before coverage start or a range longer than 366 days).
- **401** - Unauthorized. Missing or invalid Bearer token.
- **403** - Forbidden. Monthly or daily quota exhausted.
- **422** - Validation error on the request parameters.
- **429** - Too Many Requests. Rate limit exceeded.
- **500** - Internal server error.
```

--------------------------------

### Batch fetch tickers with Pandas

Source: https://indexalpha.id/docs/client-examples

Demonstrates how to perform a POST request to the batch endpoint and consolidate multiple ticker responses into a single Pandas DataFrame.

```python
import pandas as pd
import requests

API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://api.indexalpha.id"
headers = {"Authorization": f"Bearer {API_KEY}"}

payload = {
    "tickers": ["BBCA", "BBRI", "TLKM"],
    "from": "2026-03-26",
    "to": "2026-03-26",
    "investor": "all",
    "market": "RG",
}
resp = requests.post(f"{BASE_URL}/stocks/broker-summary/batch", json=payload, headers=headers)
resp.raise_for_status()

frames = []
for ticker, rows in resp.json()["data"].items():
    frame = pd.DataFrame(rows)
    frame.insert(0, "ticker", ticker)
    frames.append(frame)

df = pd.concat(frames, ignore_index=True)
print(df.head())
```

--------------------------------

### Fetch broker summary with Pandas

Source: https://indexalpha.id/docs/client-examples

Retrieves broker summary data and loads it directly into a Pandas DataFrame for analysis.

```python
import pandas as pd
import requests

API_KEY = "<YOUR_API_KEY>"
BASE_URL = "https://api.indexalpha.id"

headers = {"Authorization": f"Bearer {API_KEY}"}
params = {"ticker": "BBCA", "from": "2026-03-26", "to": "2026-03-26", "investor": "all"}

resp = requests.get(f"{BASE_URL}/stocks/broker-summary", headers=headers, params=params)
resp.raise_for_status()

df = pd.DataFrame(resp.json()["data"])
print(df.head())
```

--------------------------------

### GET /foreign-flow

Source: https://indexalpha.id/docs/endpoints

Retrieve aggregated foreign buy, sell, and net trading activity for a single stock ticker across all foreign brokers. Supports query parameters for ticker, date range, and market segment.

```APIDOC
## GET /foreign-flow

### Description
Retrieve aggregated foreign buy, sell, and net trading activity for a stock ticker across all foreign brokers. A multi-day range returns a single aggregated total, not per-day values.

### Method
GET

### Endpoint
/foreign-flow

### Parameters
#### Query Parameters
- **ticker** (String) - Required - Stock ticker symbol (e.g., `BBCA`, `TLKM`)
- **from** (Date) - Required - Start date in `YYYY-MM-DD` format
- **to** (Date) - Required - End date in `YYYY-MM-DD` format
- **market** (Enum) - Optional - Market segment: `RG` (Regular), `NG` (Negotiated), `ALL` (both, default). NG available from 2025-01-01.

### Request Example
```
curl -X 'GET' \
  'https://api.indexalpha.id/foreign-flow?ticker=BBCA&from=2026-07-01&to=2026-07-28' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <your_api_token>'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (object) - Contains foreign flow data
  - **foreign_buy** (number) - Total foreign buy value
  - **foreign_sell** (number) - Total foreign sell value
  - **net_foreign** (number) - Net foreign flow (buy - sell)
- **error** (null) - Error message, null if no error

#### Response Example
```
{
	"success": true,
	"data": {
		"foreign_buy": 125000000000,
		"foreign_sell": 83000000000,
		"net_foreign": 42000000000
	},
	"error": null
}
```
```

--------------------------------

### Claude Code CLI Commands

Source: https://indexalpha.id/docs/mcp-remote-connection

Commands to add the Index Alpha MCP server and verify the connection in the terminal.

```bash
claude mcp add index-alpha https://api.indexalpha.id/mcp
```

```bash
claude mcp list
```