AI & Agents Integration
Learn how to connect Large Language Models, AI Agents, and Coding Assistants to the Index Alpha API.
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)
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:
/llms.txt
Get a high-level, structured markdown summary of the entire Index Alpha API, perfect for priming LLM system contexts.
/llms-full.txt
Get the full API documentation, schemas, limits, and examples in a single, continuous markdown file.
2. Copyable OpenAPI 3.0 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:
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: []{
"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
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:
# 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 (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<T> {
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)
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:
[
{
"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:
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
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
Create a file named index-alpha-mcp.js and install the dependency:
npm install @modelcontextprotocol/sdkSave this code inside index-alpha-mcp.js:
#!/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)
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):
{
"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!