Sectors Financial Agents

Query financial market data from the Sectors API (api.sectors.app) for IDX (Indonesia Stock Exchange) and SGX (Singapore Exchange) markets. Use when the user...

Security Scan

The skill appears to implement a coherent client for the Sectors API, but its metadata and declared requirements do not match the runtime instructions (it requires a SECTORS_API_KEY env var even though the registry metadata lists none), so the package has an incoherence users should address before trusting it.

Purpose & Capability

The skill's stated purpose (querying api.sectors.app for IDX/SGX market data) matches the included documentation and code. However, the registry metadata lists no required environment variables or primary credential while the SKILL.md and included script clearly require SECTORS_API_KEY. This discrepancy is an incoherence (the skill legitimately needs an API key but metadata does not declare it).

Instruction Scope

SKILL.md is narrowly scoped: it instructs the agent to only call https://api.sectors.app/v1, to use GET endpoints, and to read the API key from SECTORS_API_KEY. The doc suggests optional actions like adding the export line to ~/.bashrc and shows agent-specific config commands (Claude Code, OpenCode, Cursor). Those guidance steps are reasonable for setup but the suggestions to append to shell profiles are privileged actions the user should confirm before performing.

Install Mechanism

There is no install spec and no third-party downloads; the only dependency is requests (pip install requests), and the included scripts are small and readable. The setup-check script performs a single GET to the declared API endpoint. No high-risk install or remote code fetches were found.

Credentials

Runtime instructions and scripts require a single API key (SECTORS_API_KEY), which is proportionate to the skill's purpose. However, the skill metadata did not declare this required env var (registry shows 'Required env vars: none'), an inconsistency that could mislead users or automated permission checks. Also SKILL.md recommends adding the key to ~/.bashrc or agent config — storing secrets in plaintext shell profiles can be insecure; prefer platform secret storage where available.

Persistence & Privilege

The skill does not request always:true, does not request system-wide modifications, and is user-invocable. The only persistence suggestion in docs is optional advice to add an export to ~/.bashrc; that is a user action and not enforced by the skill. No evidence the skill modifies other skills or system settings.

What to consider before installing

Key issues to consider before installing: (1) The SKILL.md requires SECTORS_API_KEY but the registry metadata does not declare it — confirm the skill actually needs your API key and update or question the metadata omission. (2) The skill only calls https://api.sectors.app/v1 and includes a benign check script; still verify the domains are correct and you trust sectors.app. (3) Avoid adding API keys to ~/.bashrc if you want them kept private; use your platform's secret/env vault or agent-specific secure settings instead. (4) If you plan to run the provided scripts, inspect them locally (the check_setup.py is small and readable) and consider running them in an isolated environment. (5) If you need higher assurance, ask the publisher for a homepage/source repo (none is provided) and request corrected metadata that declares SECTORS_API_KEY as a required credential.

Sectors API

Query IDX and SGX financial market data through the Sectors REST API.

Full API docs: https://sectors.app/api

Constraints

• ONLY make HTTP requests to https://api.sectors.app/v1. Never call any other domain, database, or external service.
• All endpoints are GET requests returning JSON.
• Never hardcode or guess an API key. Always read it from the SECTORS_API_KEY environment variable.
• If SECTORS_API_KEY is not set, prompt the user to set it: export SECTORS_API_KEY="your-api-key-here" or run the setup check script at scripts/check_setup.py.

Setup

1. Set the API key

The API key must be available as the SECTORS_API_KEY environment variable.

# Option A: Set in your current shell
export SECTORS_API_KEY="your-api-key-here"

# Option B: Add to your shell profile (~/.bashrc, ~/.zshrc) for persistence
echo 'export SECTORS_API_KEY="your-api-key-here"' >> ~/.bashrc

# Option C: Use a .env file in the project root (see .env.example)

For agent-specific configuration:

• Claude Code: claude config set env SECTORS_API_KEY your-api-key-here
• OpenCode: Set in ~/.config/opencode/config.json under env
• Cursor: Settings > Features > Environment Variables

2. Install the dependency

pip install requests

3. Verify setup (optional)

python scripts/check_setup.py

Making requests

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"

headers = {"Authorization": API_KEY}
response = requests.get(f"{BASE_URL}/subsectors/", headers=headers)
data = response.json()

The Authorization header takes the raw API key. Do NOT prefix it with Bearer.

Endpoint decision table

Pick the right endpoint based on what the user needs:

Market structure

User wants	Endpoint	Required params
List all subsectors	GET /subsectors/	none
List all industries	GET /industries/	none
List all subindustries	GET /subindustries/	none
SGX sector list	GET /sgx/sectors/	none

Company discovery

User wants	Endpoint	Required params
Companies in a subsector	GET /companies/?sub_sector={sub_sector}	sub_sector
Companies in a subindustry	GET /companies/?sub_industry={sub_industry}	sub_industry
Companies in a stock index	GET /index/{index}/	index
Companies with segment data	GET /companies/list_companies_with_segments/	none
SGX companies by sector	GET /sgx/companies/?sector={sector}	sector

Company details

User wants	Endpoint	Required params
Full company report (IDX)	GET /company/report/{ticker}/	ticker
SGX company report	GET /sgx/company/report/{ticker}	ticker
Listing performance	GET /listing-performance/{ticker}/	ticker
Quarterly financial dates	GET /company/get_quarterly_financial_dates/{ticker}/	ticker
Quarterly financials	GET /financials/quarterly/{ticker}/	ticker
Company segments	GET /company/get-segments/{ticker}/	ticker

Market data

User wants	Endpoint	Required params
Daily stock price	GET /daily/{ticker}	ticker
Index daily data	GET /index-daily/{index_code}/	index_code
Index summary	GET /index/{index}/	index
IDX total market cap	GET /idx-total/	none

Rankings and screening

User wants	Endpoint	Required params
Top gainers/losers	GET /companies/top-changes/	none (all optional)
Top companies by metric	GET /companies/top/	none (all optional)
Top growth companies	GET /companies/top-growth/	none (all optional)
Most traded stocks	GET /most-traded/	none (all optional)
SGX top companies	GET /sgx/companies/top/	none (all optional)

For full parameter lists and response schemas, see:

• references/idx-endpoints.md -- all 18 IDX endpoints
• references/sgx-endpoints.md -- all 6 SGX endpoints
• assets/endpoint-map.md -- quick-lookup table

Common patterns

Fetch a company report

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"
headers = {"Authorization": API_KEY}

ticker = "BBCA"
params = {"sections": "overview,valuation,financials"}
resp = requests.get(f"{BASE_URL}/company/report/{ticker}/", headers=headers, params=params)
report = resp.json()

print(report["company_name"])
print(report["overview"]["market_cap"])

Available sections: overview, valuation, future, peers, financials, dividend, management, ownership. Use all or omit for everything.

Get daily stock prices in a date range

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"
headers = {"Authorization": API_KEY}

ticker = "BBRI.JK"
# Normalize: uppercase, strip .JK
clean = ticker.upper().replace(".JK", "")

params = {"start": "2025-01-01", "end": "2025-01-31"}
resp = requests.get(f"{BASE_URL}/daily/{clean}", headers=headers, params=params)
prices = resp.json()

for day in prices:
    print(day["date"], day["close"], day["volume"])

Find top gainers and losers

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"
headers = {"Authorization": API_KEY}

params = {
    "classifications": "top_gainers,top_losers",
    "periods": "7d,30d",
    "n_stock": 5,
    "min_mcap_billion": 5000,
}
resp = requests.get(f"{BASE_URL}/companies/top-changes/", headers=headers, params=params)
movers = resp.json()

for stock in movers["top_gainers"]["7d"]:
    print(stock["symbol"], stock["price_change"])

List companies in an index

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"
headers = {"Authorization": API_KEY}

# Available: lq45, idx30, kompas100, jii70, idxhidiv20, srikehati, etc.
resp = requests.get(f"{BASE_URL}/index/lq45/", headers=headers)
companies = resp.json()

for c in companies:
    print(c["symbol"], c["company_name"])

SGX company report

import os
import requests

API_KEY = os.environ["SECTORS_API_KEY"]
BASE_URL = "https://api.sectors.app/v1"
headers = {"Authorization": API_KEY}

ticker = "D05"  # DBS Group
resp = requests.get(f"{BASE_URL}/sgx/company/report/{ticker}", headers=headers)
report = resp.json()

print(report["name"])
print(report["valuation"]["pe"])
print(report["financials"]["gross_margin"])

Ticker normalization

Market	Rule	Example
IDX	Uppercase, strip .JK suffix	bbca.jk -> BBCA
SGX	Uppercase, strip .SI suffix	d05.si -> D05

Always normalize before passing to an endpoint.

Gotchas

1. Auth header format: Use Authorization: <raw_key>. NOT Bearer <key>. NOT Authorization: Bearer <key>.

2. Date format: Always YYYY-MM-DD. Example: 2025-06-15.

3. Date range limit: The /most-traded/ endpoint requires start and end dates within 90 days of each other.

4. Kebab-case for subsectors and sectors: Use banks, financing-service, consumer-defensive. Not camelCase or snake_case.

5. Nested response structure: Ranking endpoints (top-changes, top, top-growth) return objects keyed by classification, then by period. Always navigate both levels.

   # top-changes returns: { "top_gainers": { "7d": [...], "30d": [...] } }
   # top returns: { "dividend_yield": [...], "revenue": [...] }
   

6. Market cap units: IDX values are in billion IDR (min_mcap_billion). SGX values are in million SGD (min_mcap_million).

7. Default values matter: Many optional params default to "all" or specific values (e.g. n_stock defaults to 5, min_mcap_billion defaults to 5000). Be explicit when you need different behavior.

8. Index codes: IDX index daily data uses lowercase codes: ihsg, lq45, idx30. Company-by-index uses the same codes.

9. Quarterly financials approx flag: When approx=true, the API returns the closest available quarter if an exact match for report_date is not found.

10. Company report sections param: Only appended to the URL when not "all". If you want all sections, omit the sections parameter entirely.

Available IDX indices

ftse, idx30, idxbumn20, idxesgl, idxg30, idxhidiv20, idxq30, idxv30, jii70, kompas100, lq45, sminfra18, srikehati, economic30, idxvesta28

Top companies classifications

IDX (/companies/top/): dividend_yield, total_dividend, revenue, earnings, market_cap, pb, pe, ps

IDX growth (/companies/top-growth/): top_earnings_growth_gainers, top_earnings_growth_losers, top_revenue_growth_gainers, top_revenue_growth_losers

IDX movers (/companies/top-changes/): top_gainers, top_losers

SGX (/sgx/companies/top/): dividend_yield, revenue, earnings, market_cap, pe

Error handling

Always check the response status:

resp = requests.get(url, headers=headers)
if resp.status_code == 403:
    raise ValueError("Invalid or missing API key. Ensure SECTORS_API_KEY is set correctly.")
if resp.status_code == 404:
    raise ValueError(f"Resource not found: {url}")
if not resp.ok:
    raise RuntimeError(f"API error {resp.status_code}: {resp.text}")
data = resp.json()