Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,9 @@ src/
bookmarklet or paste for the cookie) and the background page sign-in behind MCP
analysis/ technical.rs (indicators + signal), fundamental.rs (verdict), screen.rs (filter DSL,
presets), sentiment.rs (lexicon), returns.rs (windows, CAGR, drawdown, volatility, beta
against a benchmark on shared dates), lens.rs (growth, valuation and risk lenses),
against a benchmark on shared dates), rotation.rs (relative rotation graph: weekly
resampling, RS-Ratio and RS-Momentum, an open approximation of the JdK formulas),
lens.rs (growth, valuation and risk lenses),
dividends.rs (totals, TTM yield, streak), bandar.rs (bandarmology: tiers, signal,
phase, screen filters and presets), intraday.rs (session bars, VWAP), stats.rs (Welch t,
Student t p-values), astro.rs (returns backtest by lunar phase, Mercury, pasaran, Sun
Expand Down Expand Up @@ -106,7 +108,7 @@ src/
http.rs streamable-HTTP transport (axum, bearer token); clients.rs the
per-agent registration recipes behind `idx mcp setup` (keep docs/mcp.md in step)
model/ provider-agnostic domain types = the JSON contract (Quote, Candle, History, ...,
dividends.rs, returns.rs, market.rs, brief.rs, watchlist.rs, institutions.rs, lenses.rs,
dividends.rs, returns.rs, rotation.rs, market.rs, brief.rs, watchlist.rs, institutions.rs, lenses.rs,
intraday.rs, astro.rs)
output/ table*.rs (comfy-table), json.rs (Envelope + JSON Schema), csv.rs (-o csv),
jsonl.rs (-o jsonl: which list each schema streams, ROWS), format.rs (numbers);
Expand Down Expand Up @@ -150,7 +152,7 @@ flake.nix Nix flake (crane + rust-overlay, built from Cargo.lock): pa
```

CLI groups: `stocks` (quote, history, intraday, profile, financials, earnings, dividends, returns,
fundamental, growth, valuation, risk, technical, brief, compare, screen, news, sentiment, actions,
rotation, fundamental, growth, valuation, risk, technical, brief, compare, screen, news, sentiment, actions,
foreign, list),
`market` (overview, indices, foreign, brokers, calendar, holidays, members, astro),
`ownership` (import, ticker, entity, search, cross-holders, concentration, graph, resolve, changes, foreign,
Expand Down
55 changes: 50 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,7 @@ idx completions powershell | Out-String | Invoke-Expression
| `stocks earnings <SYMBOL> [--annual\|--quarterly] [--reported\|--estimates]` | Quarterly EPS vs estimates with surprise, yearly and quarterly revenue/earnings, analyst consensus for this and next quarter and fiscal year, next earnings date; the flags keep only those rows in every format (`--history`/`--forecast` are aliases) |
| `stocks dividends <SYMBOL>` | Every cash dividend (ex-date, split-adjusted amount) and split; yearly totals, TTM total and yield, payout streak |
| `stocks returns <SYMBOLS> [--benchmark ^JKSE]` | 1w/1m/3m/6m/YTD/1y/3y/5y returns, CAGR, volatility, max drawdown, best/worst day, 52-week position, and excess over IHSG |
| `stocks rotation <SYMBOLS> [--benchmark ^JKSE] [--interval 1wk\|1d] [--window 14] [--tail 10]` (alias `rrg`) | Relative rotation graph: each ticker's RS-Ratio, RS-Momentum and quadrant (leading, weakening, lagging, improving) against IHSG, with its recent path. An open approximation of the JdK formulas; see [Relative rotation](#relative-rotation) |
| `stocks brief <SYMBOL>` | One page: quote, verdict, signal, returns vs IHSG, dividends, top holders, headlines, with plain-language key points |
| `stocks fundamental <SYMBOL>` | P/E, P/B, PEG, EV/EBITDA, ROE, ROA, margins, leverage, growth, dividend, analyst targets, plus a plain-language verdict that lists every rule it applied (negative equity counts against a company; multiples that mix USD statements with an IDR price are marked and not scored) |
| `stocks growth <SYMBOL>` | Growth lens: latest-quarter revenue and earnings growth, forward EPS against trailing, and revenue and net income across the annual statements (CAGR, how often revenue grew, a turn from profit to loss); every rule with its points, every skipped rule with the reason |
Expand Down Expand Up @@ -182,8 +183,8 @@ idx completions powershell | Out-String | Invoke-Expression
| `stockbit movements [SYMBOL] [--from D --to D] [--holder ID] [--action A] [--source idx\|ksei] [--pages N]` | Insider and 5 % holder movements from your Stockbit session: IDX insider disclosures (with the trade price) and KSEI's 5 % holder changes (Stockbit's estimated price kept apart), shares exact and signed |
| `watch [add\|rm\|list\|clear\|returns]` | Plain-text watchlist next to the config; `idx watch` quotes it |
| `ownership releases\|discover [--family F --limit N]\|path` | Imported months, files published on idx.co.id and ksei.co.id (families `above1`, `above5`, `investor-type`, `classification`, `composition`, `all`, each marked `importable`), database path |
| `mcp [--http ADDR --token T]` · `mcp setup <client>` | MCP server over stdio or streamable HTTP, and the registration recipe for 25 agent harnesses. 47 tools: `idx_brief`, `idx_market`, `idx_quote`, `idx_history`, `idx_intraday`, `idx_profile`, `idx_financials`, `idx_earnings`, `idx_dividends`, `idx_returns`, `idx_fundamental`, `idx_technical`, `idx_compare`, `idx_screen`, `idx_news`, `idx_sentiment`, `idx_insights`, `idx_corporate_actions`, `idx_foreign`, `idx_instruments`, `idx_market_foreign`, `idx_market_brokers`, `idx_indices`, `idx_calendar`, `idx_holidays`, `idx_astro`, `idx_members`, `idx_broker`, `idx_bandar`, `idx_bandar_screen`, `idx_bandar_broker`, `idx_ownership_ticker`, `idx_ownership_entity`, `idx_ownership_changes`, `idx_ownership_foreign`, `idx_ownership_releases`, `idx_ownership_search`, `idx_ownership_rankings`, `idx_ownership_graph`, `idx_ownership_composition`, `idx_ownership_snapshot`, `idx_ownership_institutions`, `idx_orderbook`, `idx_stockbit_status`, `idx_stockbit_login`, `idx_stockbit_actions`, `idx_stockbit_movements` |
| `schema [name]` | JSON Schema for every payload (`quotes`, `history`, `intraday`, `profile`, `fundamentals`, `growth`, `valuation`, `risk`, `compare`, `financials`, `earnings`, `dividends`, `returns`, `market`, `brief`, `technical`, `screen`, `news`, `sentiment`, `insights`, `actions`, `foreign`, `foreign-value`, `instruments`, `market-foreign`, `market-brokers`, `indices`, `calendar`, `holidays`, `astro`, `members`, `broker`, `bandar`, `bandar-screen`, `bandar-broker`, `ownership-*`, `stockbit-*`, `watchlist`, `error`, ...) |
| `mcp [--http ADDR --token T]` · `mcp setup <client>` | MCP server over stdio or streamable HTTP, and the registration recipe for 25 agent harnesses. 48 tools: `idx_brief`, `idx_market`, `idx_quote`, `idx_history`, `idx_intraday`, `idx_profile`, `idx_financials`, `idx_earnings`, `idx_dividends`, `idx_returns`, `idx_rotation`, `idx_fundamental`, `idx_technical`, `idx_compare`, `idx_screen`, `idx_news`, `idx_sentiment`, `idx_insights`, `idx_corporate_actions`, `idx_foreign`, `idx_instruments`, `idx_market_foreign`, `idx_market_brokers`, `idx_indices`, `idx_calendar`, `idx_holidays`, `idx_astro`, `idx_members`, `idx_broker`, `idx_bandar`, `idx_bandar_screen`, `idx_bandar_broker`, `idx_ownership_ticker`, `idx_ownership_entity`, `idx_ownership_changes`, `idx_ownership_foreign`, `idx_ownership_releases`, `idx_ownership_search`, `idx_ownership_rankings`, `idx_ownership_graph`, `idx_ownership_composition`, `idx_ownership_snapshot`, `idx_ownership_institutions`, `idx_orderbook`, `idx_stockbit_status`, `idx_stockbit_login`, `idx_stockbit_actions`, `idx_stockbit_movements` |
| `schema [name]` | JSON Schema for every payload (`quotes`, `history`, `intraday`, `profile`, `fundamentals`, `growth`, `valuation`, `risk`, `compare`, `financials`, `earnings`, `dividends`, `returns`, `rotation`, `market`, `brief`, `technical`, `screen`, `news`, `sentiment`, `insights`, `actions`, `foreign`, `foreign-value`, `instruments`, `market-foreign`, `market-brokers`, `indices`, `calendar`, `holidays`, `astro`, `members`, `broker`, `bandar`, `bandar-screen`, `bandar-broker`, `ownership-*`, `stockbit-*`, `watchlist`, `error`, ...) |
| `config init\|set\|get\|path` | Config file management |
| `cache stats\|clear\|path` | Response cache management |
| `completions <shell>` | bash, zsh, fish, powershell, elvish |
Expand All @@ -202,7 +203,7 @@ Global flags work anywhere on the line:
| `--no-color` | `NO_COLOR` | Plain tables |
| `-v, -vv, -vvv` | `IDX_LOG` | Diagnostics on stderr, including every URL requested |
| `-q, --quiet` | `IDX_QUIET=1` | stderr carries errors only: no warnings, notes or loading line. stdout is unchanged and `-o json` keeps `warnings` in the envelope |
| | `IDX_EXCHANGE=SI` | Yahoo Finance suffix a bare ticker gets in `stocks quote`, `history`, `profile`, `financials`, `earnings`, `dividends`, `returns`, `fundamental`, `technical`, `compare` and `watch` (default `JK`, IDX). An explicit suffix (`D05.SI`) always works there; every other command reads IDX tickers only |
| | `IDX_EXCHANGE=SI` | Yahoo Finance suffix a bare ticker gets in `stocks quote`, `history`, `profile`, `financials`, `earnings`, `dividends`, `returns`, `rotation`, `fundamental`, `technical`, `compare` and `watch` (default `JK`, IDX). An explicit suffix (`D05.SI`) always works there; every other command reads IDX tickers only |
| | `IDX_PROGRESS=never\|always` | The loading line on stderr (`⠹ 6s · waiting on investasi.kontan.co.id 6s`) shows on a terminal only; `never` hides it, `always` forces it |

## For scripts and agents
Expand All @@ -221,7 +222,7 @@ idx -q -o csv stocks quote BBCA BBRI > quotes.csv # stderr: errors onl
on stderr in both modes.
- `-o auto` (or `IDX_OUTPUT=auto`) prints a table on a terminal and the JSON
envelope when stdout is piped or captured.
- `-` in a ticker list (`stocks quote|returns|compare`, `broker`, `bandar`,
- `-` in a ticker list (`stocks quote|returns|rotation|compare`, `broker`, `bandar`,
`watch add|rm`) reads tickers from stdin: plain text (spaces, commas or lines,
`#` comments) or idx's own `-o json` / `-o jsonl` output.
- The envelope records `provider`, `fetched_at`, `cached`, `stale`, `stale_reason` (`offline` or `fetch_failed`, only when stale) and `warnings`.
Expand Down Expand Up @@ -284,7 +285,7 @@ claude mcp add --scope user idx -- npx -y ihsg-mcp # no idx install needed (No
npx -y ihsg-mcp setup cursor # any client's recipe, in the npx form
```

The server lists 47 tools with typed input schemas kept to the subset every
The server lists 48 tools with typed input schemas kept to the subset every
harness accepts (no nullable type arrays, no `format` or `default` keywords)
and one-paragraph descriptions. `idx_brief` is the one-call starting point;
`idx_fundamental` takes an optional `lens` (`growth`, `valuation` or `risk`)
Expand All @@ -293,6 +294,50 @@ each tool returns the same envelope as `-o json`, so an agent that learned the
CLI already knows the tools. Failures come back as tool errors carrying
`{error: {code, message}, exit_code}`.

## Relative rotation

`idx stocks rotation` (alias `rrg`, MCP `idx_rotation`) places each ticker on
a relative rotation graph against a benchmark, IHSG (`^JKSE`) by default:

```sh
idx stocks rotation BBCA BBRI BMRI TLKM ASII
idx stocks rotation BBCA TLKM --benchmark ^JKLQ45 --tail 5
idx stocks rotation BBCA TLKM --interval 1d --window 20
idx -o json stocks rotation BBCA GOTO | jq '.data.rows[] | {symbol, quadrant}'
idx stocks rotation - < watchlist.txt
```

The x axis is RS-Ratio (is the stock beating the benchmark?), the y axis
RS-Momentum (is that getting stronger?), both centred on 100. The quadrants:
**leading** (both at or above 100), **weakening** (ratio above, momentum
below), **lagging** (both below), **improving** (ratio below, momentum
above). Stocks usually rotate clockwise through them. Each row carries its
latest point, the change over the tail, and the tail itself (the recent
path, oldest first); the table adds the four quadrants laid out as the graph
draws them.

idx computes it from five years of daily closes (the history `stocks
returns` reads, so the two share the cache), on the dates the stock and the
benchmark both have:

- RS = 100 x close / benchmark close
- RS-Ratio = 100 + (RS - mean) / standard deviation over the last `--window` bars
- RS-Momentum = 100 + the same z-score of RS-Ratio's rate of change

The original JdK RS-Ratio and RS-Momentum (RRG Research, shown by StockCharts
and Optuma) are proprietary, so this is an open approximation and says so
(`method.approximation`, `method.formula` in the JSON): its values will not
match those charts. The axes are in standard deviations, not percent. Weekly
bars (`--interval 1wk`, the default) are each week's last session, and the
current week counts with its latest one. Defaults: window 14, tail 10. A
first point needs 2 x window bars and a full tail 2 x window + tail - 1 (37
weeks by default); a shorter history (a new listing) leaves the row's values
`null` with a warning, never a fill. Yahoo has no history for the IDX sector
indices, so a sector graph is not possible yet; index codes that do have one
(`^JKLQ45`, `^JKII`) work as symbols or as the benchmark. The web terminal
does not draw the graph yet: it runs in the CLI and the MCP server. Not
investment advice.

## Bandarmology

"Bandar" is market slang for the big, concentrated money that moves a stock.
Expand Down
5 changes: 5 additions & 0 deletions docs/agent-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,10 @@ to the other.
- The fundamentals verdict, the technical signal, news sentiment and the
bandarmology readings are rule-based heuristics, and each lists the rules
that fired. Repeat them as heuristics, not as advice.
- `stocks rotation` (MCP `idx_rotation`) is an open approximation of the
JdK RS-Ratio and RS-Momentum (`method.approximation` is `true`): say so
when quoting it, and do not compare its values with StockCharts' RRG.
Its axes are standard deviations around 100, not percent.
- Prices from the free sources are delayed as published.
- `idx schema <name>` prints the JSON Schema of a payload;
[json-output.md](json-output.md) documents every field.
Expand Down Expand Up @@ -60,6 +64,7 @@ idx -o json stocks fundamental BBCA | jq '.data.verdict'
idx -o json stocks history TLKM --period 1y --interval 1wk | jq '.data.summary'
idx -o json stocks screen -f 'pe<10,div>5,mcap>5T' --sort div
idx -o json bandar detect BBRI --period 1m
idx -o json stocks rotation BBCA BBRI BMRI TLKM | jq '.data.rows[] | {symbol, quadrant, rs_ratio, rs_momentum}'
idx -o json ownership ticker BBCA # after the import below
```

Expand Down
41 changes: 37 additions & 4 deletions docs/json-output.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ status|logout`) follow the same flag, `IDX_OUTPUT` and config file.

Machine-readable schemas: `idx schema <name>` with `quotes`, `history`,
`intraday`, `profile`, `fundamentals`, `growth`, `valuation`, `risk`,
`compare`, `financials`, `earnings`, `dividends`, `returns`, `market`,
`compare`, `financials`, `earnings`, `dividends`, `returns`, `rotation`, `market`,
`brief`, `technical`, `screen`, `news`, `sentiment`, `insights`,
`foreign-value`, `astro`, `ownership-holders`, `ownership-entity`, `ownership-changes`,
`ownership-foreign`, `ownership-foreign-flow`, `ownership-releases`,
Expand Down Expand Up @@ -56,7 +56,7 @@ already documents.
| `idx.intraday.v1` | `data.bars[]` (the quote and the summary stay in `-o json`) |
| `idx.financials.v1` | `data.periods[]` |
| `idx.dividends.v1` | `data.dividends[]` (yearly totals, splits and TTM figures stay in `-o json`) |
| `idx.screen.v1`, `idx.bandar.screen.v1`, `idx.ownership.foreign-flow.v1`, `idx.ownership.concentration.v1` | `data.rows[]` |
| `idx.screen.v1`, `idx.bandar.screen.v1`, `idx.rotation.v1`, `idx.ownership.foreign-flow.v1`, `idx.ownership.concentration.v1` | `data.rows[]` |
| `idx.watchlist.v1` | `data.symbols[]`, JSON strings (`idx -o jsonl watch list \| jq -r .`) |
| `idx.holidays.v1` | `data.holidays[]` |
| `idx.instruments.v1` | `data.instruments[]` |
Expand Down Expand Up @@ -159,8 +159,8 @@ estimated. When `source` is `yahoo:chart`, expect `market_cap`, P/E, dividend
and average-volume fields to be `null`.

Other markets: the Yahoo-backed commands (`stocks quote`, `history`,
`profile`, `financials`, `earnings`, `dividends`, `returns`, `fundamental`,
`technical`, `compare`) also take a ticker with another Yahoo Finance suffix,
`profile`, `financials`, `earnings`, `dividends`, `returns`, `rotation`,
`fundamental`, `technical`, `compare`) also take a ticker with another Yahoo Finance suffix,
or a bare one with `IDX_EXCHANGE` set. In every payload an IDX ticker stays
bare (`BBCA`) and another market's keeps its suffix (`D05.SI`); `currency` is
what Yahoo reports (`SGD`), and times are still given in WIB (`+07:00`): the
Expand Down Expand Up @@ -860,6 +860,39 @@ the history is too short), `cagr_3y_pct`, `cagr_5y_pct`, `volatility_1y_pct`
`returns`, `excess` in percentage points) or `null`. Everything is computed
from five years of daily closes; dividends are excluded.

## `idx.rotation.v1` (`stocks rotation`)

A relative rotation graph against one benchmark, computed by idx from five
years of daily closes on the dates each stock and the benchmark share:

- `benchmark`, `benchmark_name`: e.g. `^JKSE`, `IDX COMPOSITE`.
- `interval`: `1wk` (each week's last session, the current week with its
latest one) or `1d` (every session).
- `method`: `approximation` (always `true`: an open approximation of the JdK
RS-Ratio and RS-Momentum, whose formulas are proprietary, so values differ
from StockCharts and Optuma), `window` (bars in each rolling mean and
sample standard deviation), `tail` (points kept per symbol), `centre`
(`100`), `formula` (the formulas in words).
- `rows[]`, in the order requested: `symbol`, `name`, `as_of` (the latest
point's date), `rs_ratio` (100 + the z-score of RS = 100 x close /
benchmark close), `rs_momentum` (100 + the z-score of RS-Ratio's rate of
change), `quadrant` (`leading` both >= 100, `weakening` ratio >= 100 and
momentum < 100, `lagging` both < 100, `improving` ratio < 100 and
momentum >= 100), `rs_ratio_change` and `rs_momentum_change` (latest
minus the tail's first point, `null` under two points), `observations`
(bars shared with the benchmark after resampling) and `tail[]` (`date`,
`rs_ratio`, `rs_momentum`, `quadrant`, oldest first, ending at `as_of`).

Both axes are in standard deviations around 100, not percent; values have
two decimals. A first point needs `2 x window` bars: with a shorter history
`as_of`, the values and the quadrant are `null` and `tail` is empty, with a
warning; so are they when a symbol moved exactly with the benchmark (no
spread to normalise). A symbol that cannot be read is left out with a
warning; the call fails when the benchmark cannot be read. When the
benchmark's latest bar is older than a symbol's (Yahoo's `^JKSE` daily bar
often arrives a session after the shares'), a warning names the symbols
whose newest close waits for it.

## `idx.market.v1` (`market overview`)

`as_of`, `market_state`, `behind_session` (`true` when even the newest quote,
Expand Down
Loading
Loading