# AI & Agents Integration
Welcome to the AI & Agent Integration guide. Large Language Models (LLMs) and autonomous AI agents are the new developers. The Index Alpha API is designed from the ground up to be **fully AI-friendly**.
Whether you are building custom AI agents with frameworks like LangChain, running local desktop coding assistants like Cursor and GitHub Copilot, or configuring custom ChatGPT Actions / Claude Projects, we provide first-class tools and schemas to make integration seamless.
***
1\. Built-in LLM Documentation (`llms.txt`) [#1-built-in-llm-documentation-llmstxt]
We support the emerging **`llms.txt` standard**, providing clean, context-optimized, and LLM-friendly documentation endpoints. If you are instructing an AI agent or search tool to learn about our API, simply point them to these URLs:
***
2\. Copyable OpenAPI 3.0 Specification [#2-copyable-openapi-30-specification]
To integrate Index Alpha with modern agentic platforms like **ChatGPT Actions**, **Claude Projects Custom Tools**, or agent frameworks (such as CrewAI, AutoGen, and Vercel AI SDK), copy this OpenAPI 3.0 schema:
```yaml
openapi: 3.0.3
info:
title: Index Alpha API
description: Premium Indonesian Stock Exchange (IDX) broker summary analytics API.
version: 1.0.0
servers:
- url: https://api.indexalpha.id/
paths:
/stocks/broker-summary:
get:
summary: Retrieve 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 June 2025.
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 (must be June 2025 or later)
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: investor
in: query
required: true
description: Type of investor to aggregate.
schema:
type: string
enum: [all, f, d, or]
responses:
'200':
description: Successful response containing broker summary data.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: array
items:
type: object
properties:
code:
type: string
description: Broker code (e.g., SQ, AK, CC)
buy_freq:
type: integer
description: Number of buy transactions
buy_volume:
type: integer
description: Total share volume purchased
buy_value:
type: number
description: Total transaction value of purchases (in IDR)
sell_freq:
type: integer
description: Number of sell transactions
sell_volume:
type: integer
description: Total share volume sold
sell_value:
type: number
description: Total transaction value of sales (in IDR)
buy_avg:
type: number
description: Weighted average buy price
sell_avg:
type: number
description: Weighted average sell price
error:
type: string
nullable: true
'401':
description: Unauthorized. Missing or invalid Bearer token.
'429':
description: Too Many Requests. Rate limit or monthly quota exceeded.
/usage:
get:
summary: Check Usage & Limits
description: Monitor your active monthly call usage, current remaining quota, and reset date.
responses:
'200':
description: Successful response containing usage metrics.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
api_key:
type: string
description: Masked version of the active API key
monthly_limit:
type: integer
description: Total monthly quota allowed
current_usage:
type: integer
description: Number of API calls consumed this period
remaining:
type: integer
description: Number of API calls remaining in active quota
reset_date:
type: string
format: date-time
description: The timestamp when the quota resets
error:
type: string
nullable: true
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
security:
- bearerAuth: []
```
```json
{
"openapi": "3.0.3",
"info": {
"title": "Index Alpha API",
"description": "Premium Indonesian Stock Exchange (IDX) broker summary analytics API.",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.indexalpha.id/"
}
],
"paths": {
"/stocks/broker-summary": {
"get": {
"summary": "Retrieve 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 June 2025.",
"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 (must be June 2025 or later)",
"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": "investor",
"in": "query",
"required": true,
"description": "Type of investor to aggregate.",
"schema": {
"type": "string",
"enum": ["all", "f", "d", "or"]
}
}
],
"responses": {
"200": {
"description": "Successful response containing broker summary data.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Broker code (e.g., SQ, AK, CC)"
},
"buy_freq": {
"type": "integer",
"description": "Number of buy transactions"
},
"buy_volume": {
"type": "integer",
"description": "Total share volume purchased"
},
"buy_value": {
"type": "number",
"description": "Total transaction value of purchases (in IDR)"
},
"sell_freq": {
"type": "integer",
"description": "Number of sell transactions"
},
"sell_volume": {
"type": "integer",
"description": "Total share volume sold"
},
"sell_value": {
"type": "number",
"description": "Total transaction value of sales (in IDR)"
},
"buy_avg": {
"type": "number",
"description": "Weighted average buy price"
},
"sell_avg": {
"type": "number",
"description": "Weighted average sell price"
}
}
}
},
"error": {
"type": "string",
"nullable": true
}
}
}
}
},
"401": {
"description": "Unauthorized. Missing or invalid Bearer token."
},
"429": {
"description": "Too Many Requests. Rate limit or monthly quota exceeded."
}
}
},
"/usage": {
"get": {
"summary": "Check Usage & Limits",
"description": "Monitor your active monthly call usage, current remaining quota, and reset date.",
"responses": {
"200": {
"description": "Successful response containing usage metrics.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean"
},
"data": {
"type": "object",
"properties": {
"api_key": {
"type": "string",
"description": "Masked version of the active API key"
},
"monthly_limit": {
"type": "integer",
"description": "Total monthly quota allowed"
},
"current_usage": {
"type": "integer",
"description": "Number of API calls consumed this period"
},
"remaining": {
"type": "integer",
"description": "Number of API calls remaining in active quota"
},
"reset_date": {
"type": "string",
"format": "date-time",
"description": "The timestamp when the quota resets"
}
}
},
"error": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"401": {
"description": "Unauthorized. Missing or invalid Bearer token."
},
"429": {
"description": "Too Many Requests. Rate limit or monthly quota exceeded."
}
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
},
"security": [
{
"bearerAuth": []
}
]
}
```
***
3\. Cursor Rules & Copilot Instructions [#3-cursor-rules--copilot-instructions]
If you use AI-powered IDEs like **Cursor**, **Windsurf**, or **VS Code Copilot**, copy the following ruleset and save it to `.cursorrules` or `.github/copilot-instructions.md` in your project root.
This ensures that whenever you ask the AI to generate stock tracking, trading analysis, or broker accumulation components, it writes flawless, type-safe code compatible with Index Alpha:
````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 `
## 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 (June 2025 or later)
- `to` (string, required, YYYY-MM-DD): End date
- `investor` (string, required): One of `all`, `f` (foreign), `d` (domestic), `or`
- **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. 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`.
## Code Conventions (TypeScript)
Use the following strict types when building integrations:
```typescript
export interface BrokerSummaryRecord {
code: string;
buy_freq: number;
buy_volume: number;
buy_value: number;
sell_freq: number;
sell_volume: number;
sell_value: number;
buy_avg: number;
sell_avg: number;
}
export interface ApiResponse {
success: boolean;
data: T;
error: string | null;
}
export interface UsageData {
api_key: string;
monthly_limit: number;
current_usage: number;
remaining: number;
reset_date: string;
}
```
## Critical Integration Tips
- **Trading Schedule**: Broker summaries only provide Regular Market records. The metrics are refreshed once daily at 12:00 GMT (19:00 Jakarta / WIB time) on active trading days.
- **Error & Quota Handling**:
- Catch `401 Unauthorized` for key validation issues.
- Catch `429 Too Many Requests` when limits are reached. Free tier is strictly limited to 10 requests per minute and 5 per day. Check remaining quota via `/usage`.
- **Performance**: Cache broker summary results for a specific ticker + date range. The data is historical and static after the daily refresh, meaning there is no need to make repeated API calls for the same parameters.
````
***
4\. Standard LLM Tool Call Formats (JSON Schema) [#4-standard-llm-tool-call-formats-json-schema]
When integrating Index Alpha directly into codebases using the **OpenAI Node/Python SDKs**, **LangChain**, or **Vercel AI SDK**, you can pass these exact tool definitions directly to the model:
```json
[
{
"type": "function",
"function": {
"name": "get_broker_summary",
"description": "Retrieves the aggregated daily activity and transaction summaries for stock brokers on a specific Indonesian Stock Exchange (IDX) stock ticker for a date range.",
"parameters": {
"type": "object",
"properties": {
"ticker": {
"type": "string",
"description": "The stock ticker symbol (e.g., BBCA, TLKM, ASII)."
},
"from": {
"type": "string",
"description": "Start date in YYYY-MM-DD format. Data begins from June 2025."
},
"to": {
"type": "string",
"description": "End date in YYYY-MM-DD format."
},
"investor": {
"type": "string",
"enum": ["all", "f", "d", "or"],
"description": "Filter by investor type: 'all', 'f' (foreign), 'd' (domestic), or 'or'."
}
},
"required": ["ticker", "from", "to", "investor"]
}
}
},
{
"type": "function",
"function": {
"name": "get_api_usage",
"description": "Checks the active API key monthly call limits, current usage, and remaining quota for the Index Alpha API.",
"parameters": {
"type": "object",
"properties": {}
}
}
}
]
```
Here is how you execute these tools in your backend when the model triggers a function call:
```typescript
import axios from 'axios';
const INDEX_ALPHA_API_KEY = process.env.INDEX_ALPHA_API_KEY;
const client = axios.create({
baseURL: 'https://api.indexalpha.id',
headers: {
'Authorization': `Bearer ${INDEX_ALPHA_API_KEY}`,
'Accept': 'application/json',
}
});
export async function handleToolCall(name: string, args: any) {
switch (name) {
case 'get_broker_summary':
const { ticker, from, to, investor } = args;
const summaryRes = await client.get('/stocks/broker-summary', {
params: { ticker, from, to, investor }
});
return summaryRes.data;
case 'get_api_usage':
const usageRes = await client.get('/usage');
return usageRes.data;
default:
throw new Error(`Unknown tool: ${name}`);
}
}
```
***
5\. Expose as a Model Context Protocol (MCP) Server [#5-expose-as-a-model-context-protocol-mcp-server]
**Model Context Protocol (MCP)** is the open standard designed by Anthropic for exposing tools and resources directly to LLM clients (like Claude Desktop, Cursor, or IDE extensions).
By running a local MCP server, an AI assistant can seamlessly query IDX broker summaries in real time to answer analytical user prompts.
Here is a ready-to-run, single-file Node.js MCP Server implementation using the official SDK.
Step 1: Create the Server File [#step-1-create-the-server-file]
Create a file named `index-alpha-mcp.js` and install the dependency:
```bash
npm install @modelcontextprotocol/sdk
```
Save this code inside `index-alpha-mcp.js`:
```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: {},
},
}
);
// Register Tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "get_broker_summary",
description: "Fetch Indonesian Stock Exchange (IDX) broker daily accumulations and transaction activity for a ticker.",
inputSchema: {
type: "object",
properties: {
ticker: { type: "string", description: "Stock symbol (e.g. BBCA, TLKM)" },
from: { type: "string", description: "Start date YYYY-MM-DD (historical starting June 2025)" },
to: { type: "string", description: "End date YYYY-MM-DD" },
investor: { type: "string", enum: ["all", "f", "d", "or"], description: "Investor group filter" },
},
required: ["ticker", "from", "to", "investor"],
},
},
{
name: "get_usage_limits",
description: "Check active Index Alpha API quota usage and remaining limits.",
inputSchema: { type: "object", properties: {} },
},
],
};
});
// Handle Tool Calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
if (name === "get_broker_summary") {
const url = `https://api.indexalpha.id/stocks/broker-summary?ticker=${args.ticker}&from=${args.from}&to=${args.to}&investor=${args.investor}`;
const response = await fetch(url, {
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Accept": "application/json"
}
});
const data = await response.json();
return {
content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
};
} else if (name === "get_usage_limits") {
const response = await fetch("https://api.indexalpha.id/usage", {
headers: {
"Authorization": `Bearer ${API_KEY}`,
"Accept": "application/json"
}
});
const data = await response.json();
return {
content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
};
} else {
throw new Error(`Tool not found: ${name}`);
}
} catch (error) {
return {
isError: true,
content: [{ type: "text", text: error.message }],
};
}
});
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Index Alpha MCP Server running on stdio");
}
main().catch((err) => {
console.error("Fatal error:", err);
process.exit(1);
});
```
Step 2: Configure Your LLM Client (e.g. Claude Desktop) [#step-2-configure-your-llm-client-eg-claude-desktop]
To use the server with Claude Desktop, add it to your configuration file (typically at `AppData\Roaming\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"index-alpha": {
"command": "node",
"args": ["/path/to/index-alpha-mcp.js"],
"env": {
"INDEX_ALPHA_API_KEY": "YOUR_ACTUAL_API_KEY"
}
}
}
}
```
Restart Claude Desktop, and your assistant will be able to query live broker summary data directly in conversation!
# Authentication
All requests to the Index Alpha API require a Bearer Token. This must be sent in the `Authorization` request header.
Authorization Header [#authorization-header]
Include your token in the header of every request as follows:
```http
Authorization: Bearer
```
Keep your API Token secure. If you believe your token has been compromised, replace it with a new one immediately.
Base URL [#base-url]
The base URL for all API requests is `https://api.indexalpha.id/`
# API Endpoints
1\. Broker Summary [#1-broker-summary]
Retrieve aggregated daily activity for brokers on a specific stock ticker.
**Endpoint:** `GET /stocks/broker-summary`
**Data Scope & Schedule:** This endpoint only provides data for the **Regular Market**. Records are updated every trading day at **12:00 GMT (19:00 Asia/Jakarta)**. Historical data is currently available starting from **June 2025**.
Query Parameters [#query-parameters]
| Parameter | Type | Required | Description |
| :--------- | :----- | :------- | :-------------------------------------------------------------------- |
| `ticker` | String | Yes | Stock ticker symbol (e.g., `BBCA`, `TLKM`) |
| `from` | Date | Yes | Start date in `YYYY-MM-DD` format |
| `to` | Date | Yes | End date in `YYYY-MM-DD` format |
| `investor` | Enum | Yes | Type of investor. One of: `all`, `f` (foreign), `or`, `d` (domestic). |
Example Request [#example-request]
```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 '
```
Response Format [#response-format]
```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
},
{
"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
}
```
***
2\. Check Usage & Limits [#2-check-usage--limits]
Monitor your monthly call usage and remaining quota.
**Endpoint:** `GET /usage`
Example Request [#example-request-1]
```bash
curl -X 'GET' \
'https://api.indexalpha.id/usage' \
-H 'accept: application/json' \
-H 'Authorization: Bearer '
```
Response Format [#response-format-1]
```json
{
"success": true,
"data": {
"api_key": "ia_l...H_Qv",
"monthly_limit": 25000,
"current_usage": 3,
"remaining": 24997,
"reset_date": "2026-04-01T00:00:00"
},
"error": null
}
```
# Errors & Support
Error Codes [#error-codes]
| Status Code | Description |
| :-------------------------- | :------------------------------------------------------ |
| `200 OK` | Request successful. |
| `401 Unauthorized` | API token is missing. |
| `403 Forbidden` | API token is invalid, expired, or does not have access. |
| `429 Too Many Requests` | You have reached the rate limit or monthly quota. |
| `500 Internal Server Error` | An error occurred on our side. |
Support [#support]
For technical issues or to request a higher usage limit, please contact the Index Alpha Team.
# Introduction
Welcome to the Index Alpha API. This documentation provides everything you need to integrate our premium **stock broker summary** analytics into your applications.
The Index Alpha API is a high-performance, RESTful service providing detailed access to **broker summary** data and activity.
Key Features [#key-features]
* **Broker Summary Analytics**: Get detailed insights into broker net accumulations, total values, and average transaction prices.
* **Secure by Design**: Industrial-grade authentication using Bearer tokens and rate limiting.
* **Reliable Data**: Consistent, up-to-date information ensured by robust backend tracking.
Getting Started [#getting-started]
To start using the API, you'll need an API token. Once you have your token, you can proceed to the [Authentication](/docs/authentication) section to learn how to make your first request.
# Limits & Quotas
To ensure fair usage and service stability, the Index Alpha API enforces the following limits:
Rate Limit [#rate-limit]
Rate limits depend on your current plan:
* **Free Plan**: 10 requests per minute.
* **Starter Plan**: 120 requests per minute.
* **Professional Plan**: 300 requests per minute.
* **Enterprise Plan**: Custom rate limits based on your agreement.
If you exceed these limits, the API returns a `429 Too Many Requests` error. The response headers (`X-RateLimit-*`) provide real-time status of your remaining window.
Monthly Quota [#monthly-quota]
Each API key is assigned a monthly limit across all keys in your account:
* **Free Plan**: 5 requests per day.
* **Starter Plan**: 25,000 requests per month.
* **Professional Plan**: 75,000 requests per month.
* **Enterprise Plan**: Custom usage limits based on your agreement.
* **Check Usage**: Use the [`/usage`](/docs/endpoints#2-check-usage--limits) endpoint to track your current status.
* **Reset**: Quotas reset at the end of your active subscription period.
Plan Upgrades [#plan-upgrades]
When you upgrade from Starter to Professional, your Starter quota is replaced by a fresh Professional quota. Your previous Starter usage does not carry over into the new Professional usage period.
Your API keys stay active and are updated to the Professional plan limits automatically.
Upgrade Example [#upgrade-example]
Starting package:
```text
Plan: Starter
Price paid: Rp200,000
Rate limit: 120 requests per minute
Quota: 25,000 requests
Period: May 1, 00:00 to May 31, 00:00
Usage before upgrade: 20,000 / 25,000 requests
Remaining quota before upgrade: 5,000 requests
Remaining time before upgrade: 15 days
```
Upgrade event:
```text
Upgrade time: May 16, 00:00
New plan: Professional
Professional price paid on upgrade: Rp350,000
```
After upgrade:
```text
Plan: Professional
Rate limit: 300 requests per minute
Quota: 75,000 requests
Usage after upgrade: 0 / 75,000 requests
Remaining quota after upgrade: 75,000 requests
Period start: May 16, 00:00
Period end: June 23, 13:42
```
Explanation:
You pay the full Professional price and receive a fresh Professional quota. The unused 5,000 Starter requests do not stack on top of Professional, and the 20,000 used Starter requests do not reduce your Professional quota.
The unused Starter time is handled separately. It is converted into extra Professional time, then added to the new 30-day Professional period.
```text
Unused Starter value: 15 / 30 * Rp200,000 = Rp100,000
Extra Professional time: Rp100,000 / Rp350,000 * 30 = 8.5714 days
Total Professional period: 30 days + 8.5714 days = 38.5714 days
```
Downgrades are not allowed during an active subscription period.
Custom Plans [#custom-plans]
Custom plans are private offers assigned to your account. If you receive a custom offer, it appears on the pricing page after you sign in.
If your custom offer is recurring, the next payment offer is created automatically after you pay. It appears on the pricing page immediately, so you can purchase it early to extend your validity period without waiting for the active custom period to end.
For example, a recurring 30-day custom offer works like this:
```text
May 2: You pay Custom 100K for 30 days.
May 2 to June 1: Your Custom 100K subscription is active.
May 2: The next Custom 100K payment offer appears automatically.
May 10: You pay the next offer early.
June 1 to July 1: The early payment extends your Custom 100K validity for the next 30-day period.
```