StockWise

A command-line tool for investors in Indian (NSE/BSE) and US markets. It tracks your portfolio with exact lots and XIRR, works out Indian capital-gains tax and advance tax, looks up stocks, mutual funds and options, and lets an AI assistant read your portfolio through an MCP server. Your data stays in local files. One binary, no account, no API key.

Install

# macOS / Linux / Termux on Android
curl -fsSL https://raw.githubusercontent.com/iamsaquib8/stockwise/main/install.sh | sh

# Debian/Ubuntu, Fedora/RHEL: .deb and .rpm from the latest release
sudo dnf install https://github.com/iamsaquib8/stockwise/releases/latest/download/stockwise-x86_64.rpm

# With Rust (1.97+)
cargo binstall stockwise            # prebuilt binary
cargo install --locked stockwise    # build from source

Windows: scoop install https://github.com/iamsaquib8/stockwise/releases/latest/download/stockwise.json or the .zip from the latest release. Docker: docker run --rm ghcr.io/iamsaquib8/stockwise quote RELIANCE. Nix and the .deb/.rpm details are on the Install page, which also lists what is not published yet (PyPI, Homebrew, winget, AUR).

Then run stockwise doctor to check your setup. If a command fails, see Troubleshooting.

Quickstart

The five-minute quickstart goes from install to a quote, a portfolio with XIRR and a tax estimate. It works on throwaway data, so you can try it safely.

Pick your path

Each guide is a short walkthrough with commands to copy, the output to expect and links to the reference. What do you want to do? lists them with the commands each one uses.

The commands at a glance

stockwise quote RELIANCE TCS            # Indian stocks are the default
stockwise TCS                           # no command needed: a one-screen overview
stockwise quote AAPL NVDA -m us         # US stocks
stockwise import kite tradebook.xlsx    # CSV or .xlsx; yearly tradebooks merge
stockwise portfolio xray                # your real exposure across stocks, funds and ETFs
stockwise tax in                        # LTCG/STCG per lot, with set-off rules
stockwise harvest                       # losses and gains to book before 31 March
stockwise tax advance --paid 2025-06-14:3000   # instalments and Sec. 234C interest
stockwise mf sip 122639 5000 -p 5y      # what a ₹5,000/month SIP became
stockwise backtest INFY -s macd         # a strategy after STT and brokerage
stockwise mcp                           # read-only tools for AI assistants

Reference

When you know what you want and need an option or a field name:

• Cheatsheet: the commands people use most, on one page.
• Commands: every command and option, with the JSON each one prints.
• Markets: India, US, global exchanges, crypto, FX, commodities.
• Data providers: where each number comes from.
• AI: the MCP server for Claude, Cursor and other assistants, and stockwise ask.
• Backtesting and Simulator: strategies, costs, replays and scores.
• Bots and alerts and Brokers: alerts, the paper-trading daemon, importing holdings, and optional live orders behind a preview.
• Troubleshooting: Yahoo or NSE not answering, Not enough price data, import skips, where your data is.
• How StockWise compares with other tools.

StockWise is open source under the MIT licence: github.com/iamsaquib8/stockwise. It is for education and information, not financial advice — see the disclaimer.

Install

StockWise is one binary with no runtime dependencies. Pick whichever way you already use to install tools; they all give you the same stockwise.

Quick install

macOS, Linux and Termux on Android:

curl -fsSL https://raw.githubusercontent.com/iamsaquib8/stockwise/main/install.sh | sh

The installer picks the right build for your system, checks its SHA-256 against the release, and installs to ~/.local/bin ($PREFIX/bin on Termux). STOCKWISE_INSTALL=/usr/local/bin changes the directory and STOCKWISE_VERSION=v0.8.1 pins a version.

Every option

These work today with the latest release:

Coming soon

Prepared, each waiting on a one-time publishing step by the maintainer (see packaging):

On ARM Linux, use stockwise_arm64.deb or stockwise-aarch64.rpm. The Linux binaries (archives, quick install, .deb/.rpm) need glibc 2.34 or newer: Ubuntu 22.04, Debian 12, RHEL 9 and later. Once PyPI is live, its wheels (manylinux, glibc 2.17+, and musllinux) will also cover older and Alpine systems.

Where completions are not installed for you:

stockwise completions zsh > ~/.zfunc/_stockwise           # bash, zsh, fish, powershell, elvish
stockwise man --dir ~/.local/share/man/man1               # then: man stockwise

Check it

stockwise --version
stockwise doctor        # data directory, network, optional Redis/Ollama/keyring

If a command fails, Troubleshooting lists the common messages and what to do about each.

Next steps

• Run the five-minute quickstart.
• Pick a goal on What do you want to do?.
• Something wrong? See Troubleshooting.

Privacy

StockWise sends no telemetry. The project counts downloads only from the public numbers each registry already shows (crates.io, GitHub releases, PyPI, Homebrew, Docker); see download stats.

Quickstart: five minutes

This page takes you from nothing to a quote, a portfolio with XIRR and a tax estimate. It assumes you have not installed StockWise yet. Each step says how long it takes.

1. Install and check (1 minute)

curl -fsSL https://raw.githubusercontent.com/iamsaquib8/stockwise/main/install.sh | sh
stockwise init      # pick a market, import holdings, optional AI assistant
stockwise doctor

The installer works on macOS, Linux and Termux. For Windows, Docker, Nix, .deb, .rpm or cargo, see Install.

stockwise doctor checks your setup and prints the folder where StockWise keeps your data. If it reports a problem, see Troubleshooting.

To try the commands below without touching your real data, point StockWise at a temporary folder first:

export STOCKWISE_HOME=$(mktemp -d)

Close the terminal, or run unset STOCKWISE_HOME, to go back to your real data.

2. Look up a stock (30 seconds)

stockwise quote RELIANCE TCS     # Indian stocks are the default
stockwise quote AAPL NVDA -m us  # add -m us for US stocks
stockwise TCS                    # no command needed: a one-screen overview

Each stock prints a short block: price, change, day range, 52-week range, volume, market cap and P/E. Data comes from Yahoo Finance, so quotes can be delayed. A bare ticker such as TCS means TCS.NS on the NSE.

3. Build a portfolio (2 minutes)

You can type a purchase, or import a file from your broker.

stockwise portfolio add TCS 10 3500 --date 2023-04-12   # 10 shares at ₹3,500
stockwise portfolio add INFY 20 1300 --date 2023-06-05
stockwise portfolio                                      # holdings, P&L and XIRR

Every purchase is a lot with its own date, so the holding period and the XIRR are exact. To load real trades, use the guide Import your trades and see true returns. It covers Zerodha, Groww, Upstox, INDmoney and mutual-fund CAS files.

4. Get a tax estimate (30 seconds)

stockwise portfolio sell TCS 4 3900   # record a sale; the oldest lots go first
stockwise tax in                      # LTCG and STCG for this financial year

tax in shows realised gains from your sales, and what you would owe if you sold everything today. It is an estimate. The guide File your Indian capital-gains tax explains how to read it and how to export the rows for your ITR.

5. Connect an AI assistant (1 minute, optional)

claude mcp add stockwise -- stockwise mcp

This adds StockWise to Claude Code. Claude Desktop and Cursor need a small JSON entry instead; see Use StockWise from Claude or Cursor. The server only reads. It cannot place orders.

Next steps

• Pick a goal on What do you want to do?.
• Keep the cheatsheet open for the commands people use most.
• Look up an option in the commands reference.

What do you want to do?

The guides below are short walkthroughs. Each one starts from a goal, gives commands you can copy, shows what the output looks like and ends with links to the commands reference for every option.

New to StockWise? Do the quickstart first. It takes five minutes.

Pick your path

Where each guide fits

StockWise does four jobs. The guides follow them.

1. One portfolio with true returns. Start with Import your trades, then Rebalance.
2. Indian capital-gains tax. Read File your Indian capital-gains tax. It needs the portfolio from job 1.
3. Quick lookups. Check a stock or fund fast and Set up alerts.
4. AI access with local data. Use StockWise from Claude or Cursor. Script it covers the same data for your own tools.

Backtest and practise sits beside these. It uses past prices and paper money, never your portfolio.

Not here?

• Every command and option is in the commands reference. The cheatsheet lists the common ones on one page.
• Errors and empty results are covered in Troubleshooting.
• Live orders through a broker are in Brokers. They move real money, so they have no guide here.

StockWise is for education and information. It is not financial advice. See the disclaimer.

Import your trades and see true returns

This guide loads your broker trades and mutual-fund statement into StockWise and shows your holdings with profit and XIRR. It takes about ten minutes, most of it spent downloading files.

You need: a Zerodha, Groww, Upstox or INDmoney export, and optionally a CAS for mutual funds. Nothing here changes your broker account. StockWise reads files and stores the result in local files.

1. Pick the right file

XIRR and tax need the date of every purchase. The file you choose decides whether StockWise has it.

Use a tradebook when you can. Use a holdings export only for stocks you cannot get a tradebook for.

Zerodha Console limits a tradebook download to 365 days. Download one file per year. StockWise merges them.

2. Import the tradebook

Import each file with the broker name. CSV and .xlsx both work.

stockwise import kite ~/Downloads/tradebook-2023.xlsx
stockwise import kite ~/Downloads/tradebook-2024.xlsx
stockwise import kite ~/Downloads/tradebook-2025.xlsx

You can import the files in any order. StockWise keeps the trades of each import and merges them, so running the same file twice changes nothing.

Each import prints one line per symbol:

  ✓ TCS.NS — 1 lot(s), 1 sale(s) recorded, now 6 shares @ ₹3250.00
  ✓ INFY.NS — 1 lot(s), 1 sale(s) recorded, now 15 shares @ ₹1300.00
  ✓ SBIN.NS — 1 lot(s), now 50 shares @ ₹620.00

  ✓ Imported 5 rows: 3 holdings updated.

Splits and bonuses are applied as they happened. This needs a network connection.

If a symbol is skipped, the message says why. The usual cause is a sale with no earlier purchase, because an earlier year’s file is missing. Import that file and run the import again. See An import skips a symbol.

3. Import mutual funds from a CAS

A CAS is a PDF, and its tables do not survive text extraction. Convert it with the open-source casparser, then import the result.

pip install casparser
casparser CAS.pdf -p <password> -o cas.json
stockwise import cas cas.json
# or let StockWise run casparser for you (casparser must be on PATH):
stockwise import cas CAS.pdf   # hidden password prompt (or set STOCKWISE_CAS_PASSWORD)
# Note: the bridge passes the password to casparser as a command-line argument,
# so other local users can see it in the process list while it runs.

Each fund with units left becomes MF:<AMFI code>. StockWise values it at AMFI’s latest end-of-day NAV. A fund that AMFI does not list shows N/A, never zero.

4. See your portfolio

stockwise portfolio

  Symbol         Shares   Avg Cost      Price        Value         P&L    P&L %     XIRR
  ──────────────────────────────────────────────────────────────────────────────────────
  TCS.NS           6.00   ₹3250.00   ₹2498.50    ₹14991.00   -₹4509.00  -23.12%    -4.6%
  INFY.NS         15.00   ₹1300.00   ₹1181.40    ₹17721.00   -₹1779.00   -9.12%    -0.9%
  SBIN.NS         50.00    ₹620.00   ₹1018.50    ₹50925.00  +₹19925.00  +64.27%   +19.3%
  ──────────────────────────────────────────────────────────────────────────────────────
  TOTAL                  ₹70000.00               ₹83637.00  +₹13637.00  +19.48%    +5.1%
  Realized P&L (2 sale lots)   +₹1200.00

The numbers above come from a small sample portfolio. Prices are live, so yours will differ.

How to read it:

• P&L % is the gain on cost, ignoring when you bought.
• XIRR is the yearly return that accounts for the date of every purchase. A holding that gained 64% over 3 years has a much lower XIRR than 64%.
• Realized P&L is the profit on shares you already sold.
• A holding with no price shows N/A and is left out of the totals.

Mixed INR and USD holdings are totalled in one currency. Pick it with --base inr or --base usd.

5. Check one holding

stockwise portfolio lots TCS

    # Bought             Qty      Price         Cost     Held  Term  Source
    1 2023-04-12        6.00   ₹3250.00    ₹19500.00    3y 6m    LT  import:kite [zerodha]

  Sales (FIFO)
  Sold               Qty Bought              Buy       Sell         Gain  Term
  2025-08-20        4.00 2023-04-12     ₹3250.00   ₹3300.00     +₹200.00    LT

Each row is one lot with its date, its holding period (LT is long-term, ST is short-term) and where it came from. Check these against your broker’s statement. If a purchase date is wrong, correct it with stockwise portfolio lots TCS --lot 1 --date 2023-04-10.

6. Compare with the index and look through your funds

stockwise portfolio benchmark NIFTY -p 1y   # your return against NIFTY 50
stockwise portfolio xray                    # overlap across stocks, funds and ETFs

benchmark rebuilds what you held on each day and compares the time-weighted return with the index. It also prints alpha, beta and tracking error. xray adds up your real exposure to each company across direct shares, ETFs and mutual funds, and flags any company above 10% of the portfolio.

7. Keep it up to date

• Import the newest tradebook after each year, or whenever you want. Old trades are not counted twice.
• Add a purchase by hand: stockwise portfolio add TCS 10 3500 --date 2023-04-12.
• Record a sale by hand: stockwise portfolio sell TCS 5 3900.
• Apply splits, bonuses and dividends to lots you added by hand: stockwise portfolio actions --apply. It is safe to repeat.
• Rebuild one symbol from a dated file, replacing lots recorded another way: stockwise import kite tradebook.csv --replace.

Next steps

• File your Indian capital-gains tax. The sales you imported feed straight into it.
• Rebalance to target weights.
• Every portfolio option is in the commands reference. The file layouts and rules for imports are in Brokers, and the lots, sales and tax section explains FIFO.
• Something looks wrong? See Troubleshooting.

File your Indian capital-gains tax

This guide takes the lots and sales in your portfolio and turns them into a capital-gains estimate, a list of what you could book before 31 March, an advance-tax schedule, and a CSV laid out for ITR Schedule CG and Schedule 112A.

You need: a portfolio with dated purchases and sales. If you have not built one yet, start with Import your trades.

StockWise gives an estimate. It knows only the sales it recorded, at the prices it recorded, without brokerage or STT. Compare every figure with your broker’s tax P&L before you file, and ask a chartered accountant if you are unsure.

When to use which command

1. Estimate the tax so far

stockwise tax in

  Realized — sales 01 Apr 2026 to 31 Mar 2027
  Symbol               Qty Bought       Sold                 Gain  Term
  INFY.NS             5.00 2023-06-05   2026-07-10         +₹1000    LT

  Unrealized — if you sold everything today
  Symbol                 Cost        Value   Short-term    Long-term
  TCS.NS               ₹19500       ₹14991          +₹0       -₹4509
  ...

  Estimated tax on gains realized in FY 2026-27
  Long-term gains / losses     ₹1000.00 / ₹0.00
  LTCG exemption (₹125000 a year) -₹1000.00
  Taxable LTCG                 ₹0.00
  TOTAL TAX                    ₹0.00

The output has three blocks:

1. Realized. Every lot you sold this financial year, with its own holding period. Long-term means more than 12 months.
2. Unrealized. What each holding would book if you sold everything today. Nothing is sold.
3. Estimated tax. The set-off rules, the ₹1.25 lakh LTCG exemption, the rates and the 4% cess applied to the realized gains.

The rates follow the date of each sale. Sales before 23 July 2024 use the old rates (15% STCG, 10% LTCG). Later sales use 20% and 12.5%.

Some holdings are left out of the estimate and listed with the rule that applies: debt funds, Sovereign Gold Bonds, gold and silver ETFs, liquid ETFs and crypto. Equity funds and equity ETFs count like listed shares. For the full list, see Lots, sales and tax.

2. Look at harvest candidates before 31 March

stockwise harvest

  Loss Harvesting Candidates (STCG / LTCG Offset)
  Symbol             Sell   Avg Cost      Price       ST P&L       LT P&L    Total P&L  Est. Saved
  TCS.NS                6   ₹3250.00   ₹2498.50          +₹0       -₹4509       -₹4509          ₹0

  Tax-Gain Harvesting (Section 112A ₹1.25L Annual LTCG Exemption)
  Unused LTCG Exemption        ₹124000 of ₹125000 remaining this FY
  • SBIN.NS      LTCG:    +₹19925 (saves up to ₹2590 at 12.5%)

harvest lists two things:

• Loss candidates. Sales that would book a loss to set off against gains. Indian demat accounts sell the oldest lots first, so a row shows the whole sale needed to reach the losing lot. Est. Saved is how much the tax estimate falls. It is 0 when you have no gains to set the loss against.
• Exemption candidates. Long-term holdings with a gain, and how much of this year’s ₹1.25 lakh LTCG exemption is still unused.

This is a list of what the arithmetic allows. It is not advice to trade. Brokerage, STT and your own view of each stock are not in the numbers.

Preview a sale before you record it

portfolio sell records the sale. Add --preview (alias --dry-run) to see what it would do and change nothing: portfolio.json is not touched.

stockwise portfolio sell TCS 12 4000 --preview

The preview prints:

• The departing lots, oldest first (FIFO): lot number, purchase date, days held, quantity, cost, gain or loss, and ST or LT. Lot numbers match portfolio lots.
• The tax the sale adds on top of gains already recorded this tax year, from the same rules as tax in: short-term gain at 20%, long-term gain at 12.5% after the ₹1.25 lakh Sec. 112A exemption still unused this year, the 31 Jan 2018 grandfathered cost for old lots, and 4% cess. Other countries use their own rates. Funds and ETFs taxed under other rules show lots and gains only, with the reason.
• A long-term countdown. A lot within 45 days of turning long-term is listed with the day it turns and how much lower the tax would be if the same sale happened then, at the same price. A holding of exactly 12 months is still short-term; the first long-term day is the next one.
• A mutual-fund exit-load check. Units held under 365 days are flagged with a typical 1% exit load. Schemes differ, so check the factsheet.

The price defaults to the live quote (a fund’s latest AMFI NAV). A past --date needs a price. The same preview is the MCP tool portfolio_sell_preview. These are arithmetic on your records, not advice.

Regular vs Direct fund cost

stockwise mf bleed [--return 10] [--json]

For each held Regular-plan growth fund, mf bleed finds the Direct growth plan of the same scheme and reads both expense ratios from AMFI’s TER disclosure. It shows the gap, the yearly rupee cost of the gap on today’s value, and the 10-year compounded difference at a gross return you choose (--return, default 10% a year, no new money). It then splits the units by age:

• Units held more than 12 months, and how many of them redeem with ₹0 tax inside this year’s unused Sec. 112A exemption (oldest units first).
• Younger units, with the day each lot turns long-term and, for a switch today, the tax, the exit load and the months of TER saved needed to cover them.

A switch is a redemption plus a purchase, so it can create tax. Funds that are not equity-oriented are shown without the tax split. portfolio prints a one-line pointer when you hold a Regular plan. MCP tool: mf_bleed.

3. Check advance tax

Advance tax is due when the estimated tax for the year is ₹10,000 or more. Pass each payment with its date so StockWise can work out Section 234C interest exactly.

stockwise tax advance                                # the current financial year
stockwise tax advance --fy 2025-26 --paid 2025-09-10:500

The second command gives output like this:

  Quarter Due Date       Cum. STCG    Cum. LTCG     Cum. Tax  Min %  Min Cum. Due   Quarter Due  Status
  Q1      15 Jun 2025           ₹0           ₹0           ₹0    15%            ₹0            ₹0  Nothing due
  Q2      15 Sep 2025           ₹0         ₹200           ₹0    45%            ₹0            ₹0  Nothing due
  ...
  • Section 208: Exempt (estimated tax < ₹10,000 threshold — advance tax not mandatory)
  • Advance Tax Paid Recorded: ₹500
  • Estimated Section 234C Interest: ₹0 (no shortfall subject to interest)

Things to know:

• Add --fy 2025-26 for a past year.
• --paid 25000 with no date is assumed to be on time. That can understate the interest, so use dates when you have them.
• Capital gains realised after an instalment date do not attract 234C interest if you pay the tax in the later instalments. StockWise applies this proviso.
• Surcharge is not included.

4. Export the schedule for your ITR

stockwise tax export in --fy 2025-26 --out cg-2025-26.csv

  Capital-gains schedule — FY 2025-26 (AY 2026-27)
  Sales                        1
  STCG 111A gains / losses     ₹0 / ₹0
  LTCG 112A gains / losses     ₹200 / ₹0
  Taxable LTCG (112A)          ₹0
  Estimated tax                ₹0

  Wrote 1 sales to cg-2025-26.csv

The CSV has one row per lot sold: section (111A or 112A), ISIN, scrip, quantity, sale date and value, purchase date and cost, days held and the gain. A summary block follows with the totals, the exemption and the loss to carry forward. --fy accepts 2025-26, 2025-2026 and AY2026-27.

Open the file in a spreadsheet and compare it with your broker’s tax P&L. Check these before you file:

• Shares bought on or before 31 January 2018. StockWise flags them. Schedule 112A lets you use that day’s fair market value as the cost. StockWise does not apply it.
• ISINs. StockWise looks them up from NSE and AMFI. A blank ISIN is named in the summary.
• Same-day trades. A buy and sell of the same share on one day is shown separately as speculative business income, not as capital gains.
• Left out. Debt funds, SGBs, gold ETFs and crypto are listed but not in the schedule. Crypto is taxed at a flat 30% under Section 115BBH.

Next steps

• Rebalance to target weights. A buy-only rebalance adds money without selling, so it books no gain.
• Use StockWise from Claude or Cursor. The tax_harvest_check prompt asks an assistant for the same review.
• Script it with JSON, CSV and jq, for example stockwise tax export in --fy 2025-26 --json | jq '.summary.taxable_ltcg'.
• Every rule and field is in the commands reference: lots, sales and tax, harvest, tax export and advance tax.
• Numbers look wrong? See An import skips a symbol.
• StockWise is not financial or tax advice. See the disclaimer.

Check a stock or fund fast

This guide shows how to size up a stock or a mutual fund in a few minutes: a quote, a one-page overview, accounting-quality scores, a timeline of events and what a fund’s past SIP returned.

You need nothing but StockWise. No account or API key is required. Data comes from Yahoo Finance, NSE and AMFI, so quotes can be delayed.

None of these commands tells you what to buy or sell. They show facts and simple scores. The decision stays with you.

1. Find the ticker

stockwise search "tata motors"

Bare tickers use the Indian market, so TCS means TCS.NS. For other markets, add -m us, -m crypto, -m fx, -m commodity or an exchange such as -m uk. See Markets.

2. Get the price

stockwise quote RELIANCE TCS     # one block per stock
stockwise quote AAPL NVDA -m us
stockwise TCS                    # no command: a one-screen overview

  RELIANCE.NS — Reliance Industries Limited
  ₹1320.00  ▲ 6.60 (0.50%)

  Open                         ₹1295.00
  Day Range                    ₹1295.00 — ₹1320.00
  52-Week Range                ₹1152.20 — ₹1611.80
  Volume                       22.77M
  Avg Volume (3M)              14.49M
  Market Cap                   ₹17.86L Cr

Short forms exist for the common commands: q for quote, a for analyze, t for technical and c for compare.

3. Read the full picture for one stock

stockwise deep HDFCBANK

deep puts company details, valuation, profitability, financial health, dividends, analyst ratings, a one-year chart, technical indicators, support and resistance, risk and the six-pillar score on one screen. It is long. Scroll to the part you need.

For smaller pieces, use these:

--explain adds plain-English notes to technical, score, verdict and options oi.

4. Check accounting quality

stockwise score INFY --explain

  Piotroski F-Score:   6/9  ███████░░░  Moderate / Stable
  Altman Z-Score:      8.31  Safe Zone (Low Default Risk)

The Piotroski F-score counts nine yes-or-no tests of profitability, leverage and efficiency. The Altman Z-score estimates distress risk. --explain shows each test, its formula and the value used. When data is missing, StockWise says how many tests it could run instead of guessing.

5. See what happened and what the data says

stockwise events TCS      # filings, results, news and analyst moves, with the price reaction
stockwise insights TCS    # positive and negative findings on ownership, growth, margins, valuation

events lists the last 90 days on a timeline. Each event shows how the stock moved against the index afterwards. insights groups findings such as promoter pledge, institutional buying and selling, and margin trends. Both are summaries of public data, not forecasts.

Upcoming results and dividend dates for your holdings:

stockwise calendar --holdings

6. Check a mutual fund

stockwise mf search parag flexi direct   # find the AMFI code
stockwise mf nav 122639                  # latest NAV and expense ratio
stockwise mf sip 122639 5000 -p 5y       # what ₹5,000 a month became

     Code  Scheme                                                                 NAV        Date
   122639  Parag Parikh Flexi Cap Fund - Direct Plan - Growth                 93.9483 06 Nov 2026

mf sip replays a monthly SIP over the past five years and prints the amount invested, the final value and the XIRR. It describes the past. Compare funds in one category with stockwise mf screen flexi cap.

7. Options and IPOs (optional)

stockwise options chain NIFTY     # strikes with open interest, IV and greeks
stockwise options oi NIFTY        # open-interest walls, put/call ratio, max pain
stockwise ipo                     # open and upcoming IPOs from NSE

Add --explain to options oi for plain-English notes.

Next steps

• Want a message when a price or RSI level is hit? See Set up alerts and the daemon.
• Want to test a rule on past prices? See Backtest and practise on past markets.
• Want an assistant to run these lookups for you? See Use StockWise from Claude or Cursor.
• Every option for these commands is in the commands reference: Analysis, Market and Funds and F&O.
• Quote or data errors: Troubleshooting.

Rebalance to target weights

This guide sets the weight you want for each holding and shows how many shares to buy to move toward it. The most useful form puts new money only into holdings that are below target, so you do not have to sell anything and book a gain.

StockWise only does the arithmetic. It does not place orders, and the output is not a recommendation. You choose the targets.

You need: a portfolio. See Import your trades.

1. Set your targets

stockwise portfolio target set TCS 30
stockwise portfolio target set INFY 30
stockwise portfolio target set SBIN 40
stockwise portfolio target show

  Target Key      Weight%
  ─────────────────────────
  INFY.NS           30.0%
  SBIN.NS           40.0%
  TCS.NS            30.0%
  ─────────────────────────
  Total            100.0%

  Drift Tolerance: Not set (default: 0.0%)

Each set prints the running total. If the targets add up to less than 100%, the rest is shared among holdings with no target. A key can be a symbol or a sector. Remove one with stockwise portfolio target remove TCS.

With no targets saved, StockWise rebalances to equal weights.

2. Add new money without selling

stockwise rebalance --inflow 50000

  Portfolio Rebalance (Inflow: ₹50000.00)
  Current Value                ₹83637.00
  Projected Value              ₹133637.00

  Symbol          Current    Now% Target% Projected%   Allocation           Action
  TCS.NS        ₹14991.00   17.9%   30.0%      30.0%    ₹25100.10    BUY 10 shares
  INFY.NS       ₹17721.00   21.2%   30.0%      30.0%    ₹22370.10    BUY 18 shares
  SBIN.NS       ₹50925.00   60.9%   40.0%      40.0%     ₹2529.80     BUY 2 shares

Read it left to right:

• Now% is the current weight. Target% is the weight you set.
• Projected% is the weight after the new money goes in.
• Allocation is the part of the ₹50,000 that holding receives.
• Action is the whole-share count that fits that amount.

The new money goes to holdings below target. A holding above target, such as SBIN here, gets little or none. Nothing is sold, so there is no capital gain to report.

3. Rebalance by selling too

Without --inflow, StockWise also lists holdings above target as sales.

stockwise rebalance
stockwise rebalance --drift 2.0      # ignore holdings within 2 percentage points of target

  Symbol          Current     Now%  Target%           Action
  TCS.NS        ₹14991.00    17.9%    30.0%     BUY 5 shares
  INFY.NS       ₹17721.00    21.2%    30.0%     BUY 7 shares
  SBIN.NS       ₹50925.00    60.9%    40.0%   SELL 17 shares

A sale books a gain or loss. Run stockwise harvest or stockwise tax in first to see the effect. The tax guide explains both.

--drift skips small differences, so you do not trade for a 0.5% gap. Save a default band with stockwise portfolio target drift 2.0.

4. Try a plan without saving it

Pass targets on the command line to compare options. Nothing is saved.

stockwise rebalance TCS:30 INFY:30 SBIN:40 --inflow 50000

5. Keep the plan current

After you place the orders at your broker, record them so the next run starts from the right place:

stockwise portfolio add TCS 10 2498.50          # a purchase dated today
stockwise import kite tradebook-latest.xlsx     # or import the new tradebook

Next steps

• Import your trades if holdings are missing or out of date.
• File your Indian capital-gains tax before a rebalance that sells.
• Use the numbers elsewhere: stockwise rebalance --inflow 50000 --json prints the same plan as JSON. See Script it with JSON, CSV and jq.
• Every option is in the commands reference under Portfolio. A review prompt for assistants is in Use StockWise from Claude or Cursor.

Use StockWise from Claude or Cursor

This guide connects an AI assistant to StockWise so you can ask questions about quotes, your portfolio and your tax estimate in plain English. It takes about five minutes.

stockwise mcp is a Model Context Protocol server. Your assistant starts it on your machine. The server reads your local StockWise data and answers with JSON. It needs no account and no API key.

You need: StockWise installed (see Install) and an MCP client: Claude Code, Claude Desktop, Cursor or another.

What the assistant can and cannot do

• It can read. The 35 tools cover quotes, history, technicals, risk, scorecards, events, mutual funds, option chains, IPOs, screens, backtests, your portfolio and lots, tax estimate, advance tax, harvest and rebalance plans, calendar, watchlist and alerts.
• It cannot place orders. The server never places, changes or cancels an order and never reads broker credentials. The optional --allow-orders flag adds one tool that only checks an order and returns a command such as stockwise trade buy TCS 2 --limit 4000 for you to review and run yourself.
• It cannot change your data. Every tool only reads.

One point on privacy. The server runs on your machine, but a hosted assistant sends what its tools return to its own model provider. If you ask about your portfolio, the holdings go with the question. If that is a problem, use stockwise ask "question", which can run a local model through Ollama. See AI.

1. Connect your client

Claude Code:

claude mcp add stockwise -- stockwise mcp
claude mcp add stockwise -- stockwise mcp -m us    # US tickers by default

Claude Desktop: open Settings, then Developer, then Edit Config. Add this and restart the app.

{
  "mcpServers": {
    "stockwise": {
      "command": "stockwise",
      "args": ["mcp"]
    }
  }
}

Cursor: put the same JSON in ~/.cursor/mcp.json, or in .cursor/mcp.json inside a project.

If the client cannot find the command, use the full path from which stockwise (where stockwise on Windows) as command.

Other settings go in args or in the client’s env:

2. Check that it works

List the tools from your terminal. This does not need the assistant.

stockwise mcp --list-tools

It prints a JSON array. Each entry has a name, a description and an inputSchema. Then ask your assistant something that needs data:

What is the current price and P/E of TCS and INFY?

The assistant shows a tool call to quote and then answers from the result.

3. Ask useful questions

Questions that work well, grouped by what they use:

Ready-made prompts are built in. In clients that support MCP prompts, pick one from the prompt menu:

• review_portfolio for value, P&L, concentration and risk, with no buy or sell calls.
• tax_harvest_check for unrealised gains and losses by lot before 31 March.
• explain_option_chain for an option chain in plain words.

The server also offers three resources: stockwise://portfolio, stockwise://watchlist and stockwise://alerts.

4. Check the answer

An assistant can misread a number. Keep these habits:

• Open the tool call and look at the returned values for anything that matters.
• Treat tax figures as estimates. Compare them with your broker’s tax P&L.
• Ask for the source of a number. Every result carries a short “not financial advice” note, and long lists say when they were truncated.

5. Over HTTP, or without installing

stockwise mcp --http 127.0.0.1:8788    # Streamable HTTP at http://127.0.0.1:8788/mcp

The server accepts loopback addresses only, unless you pass --allow-remote and set STOCKWISE_API_TOKEN. Use HTTP only with clients that need it. The AI page lists the safety rules. For Docker, uvx and the registry entry, see AI.

Next steps

• Import your trades. The assistant has more to read once your portfolio is in.
• Script it with JSON, CSV and jq for the same data without an assistant.
• The full tool table, the resources and the safety model are in AI. Agents can also read the llms.txt file.
• stockwise ask "question" runs the same tools from the terminal with a local model. See Ask in plain English.
• Server does not start? See Troubleshooting.

Set up alerts and the daemon

This guide makes StockWise tell you when a price, RSI level or result date needs your attention, and shows how to leave it running. It takes about ten minutes.

You need: StockWise installed. For phone or email messages you also need a Telegram bot, a Slack or Discord webhook, or an SMTP account.

1. Build a watchlist

stockwise watch add INFY HDFCBANK
stockwise watch

watch prints your list with live prices. The list also feeds the calendar and the MCP server.

2. Add alerts

An alert is a symbol, a condition and a number.

stockwise alert add RELIANCE below 1200
stockwise alert add INFY rsi-below 30              # RSI(14) at or below 30
stockwise alert add RELIANCE cross-above-sma 200   # close crosses above the 200-day average
stockwise alert add SBIN breakout-high 52          # new 52-week high
stockwise alert add HDFCBANK change-below 3        # a fall of 3% or more today
stockwise alert add TCS volume-spike 2             # 2x the 20-day average volume
stockwise alert add TCS results-in 7               # results due within a week
stockwise alert add AAPL -m us below 180           # US stock

Each command confirms the alert and gives it a number:

  ✓ Alert #0: RELIANCE.NS below 1200.00
  ✓ Alert #1: INFY.NS RSI(14) below 30

The full list of conditions is in Alert conditions.

List the alerts, and check them once against live data:

stockwise alert                 # your alerts, in words
stockwise alert check           # each alert with its current value and status
stockwise alert remove 0        # delete alert #0

alert check marks each alert triggered or waiting. It shows no_data in --json when there is too little history.

3. Choose where messages go

Channels are opt-in and set with environment variables. Check what is configured:

stockwise notify

  · Telegram  not configured
  · Slack     not configured
  · Discord   not configured
  · Email     not configured
  · Desktop   not configured

Add the variables for one channel to your shell profile or your scheduler. For Telegram:

export STOCKWISE_TELEGRAM_TOKEN=<token from @BotFather>
export STOCKWISE_TELEGRAM_CHAT_ID=<your chat id>

To find the chat id, send your bot a message and open https://api.telegram.org/bot<TOKEN>/getUpdates in a browser. Copy the number under chat and id.

Then send a test message to each configured channel:

stockwise notify test

It exits with status 1 if any channel fails. Slack, Discord, email and desktop settings are in Notifications. A token or password in the config file needs a private file (chmod 600).

4. Keep checking during market hours

stockwise alert watch                 # every 60 seconds while the market is open
stockwise alert watch --interval 30   # every 30 seconds (minimum 10)

alert watch checks an alert only while its market is open. It uses the NSE clock for Indian stocks and the NYSE clock for US stocks, and sleeps otherwise. It re-reads your alerts on every pass, so an alert add in another terminal takes effect without a restart.

Each trigger is sent once. An alert fires when its condition becomes true, and fires again only after the condition turns false and true again, at most once a trading day. Press Ctrl+C to stop.

Run it from cron instead

If you would rather not keep a terminal open, run one pass on a schedule:

# every 15 minutes from 09:15 to 15:30 IST, Monday to Friday
*/15 9-15 * * 1-5  STOCKWISE_TELEGRAM_TOKEN=... STOCKWISE_TELEGRAM_CHAT_ID=... stockwise alert watch --once

--once checks every alert one time and exits. It remembers what it already sent, so the same trigger is not repeated. Cron uses the machine’s clock, so check that your server is on IST or adjust the hours.

5. Run the paper-trading daemon (optional)

The daemon runs the intraday paper bot on its own and records the results. It never sends broker orders.

stockwise daemon intraday 25000         # NSE hours, ₹25,000 of paper capital
stockwise daemon intraday 25000 --once  # one session, then exit (for cron)
stockwise sim history                   # results of settled sessions

The daemon follows the exchange clock, skips weekends and holidays, enters positions in the first 15 minutes, checks them every 60 seconds and squares everything off 15 minutes before the close. Ctrl+C closes open positions at the last price, saves the day and exits. If configured, it sends entries, exits and an end-of-day summary to the same notification channels.

There is also a once-a-day research pass:

stockwise daemon longterm   # scores 30 stocks, snapshots wealth, checks alerts, lists holdings below cost

For how the bots decide and the risk limits, see Bots and alerts and Bot design.

Next steps

• Check a stock or fund fast when an alert fires.
• Backtest and practise on past markets to test a rule before you rely on it.
• Alerts and notifications in full: Bots and alerts and Notifications. Command options are in Portfolio (watch, alert).
• Messages not arriving? See Troubleshooting.

Backtest and practise on past markets

This guide covers two ways to learn from history without risking money. A backtest replays a rule on past prices. A replay lets you trade a past market one day at a time, with the future hidden. Both use paper money and neither touches your portfolio or a broker.

You need: StockWise installed and a network connection for price history.

Both describe the past. They are not predictions and not financial advice.

Part 1: Backtest a rule

Run one

stockwise backtest INFY -s macd

  Backtest: INFY.NS — macd (2y, 2024-11-06 → 2026-11-06)
  Entry                        macd_hist(12, 26, 9) crosses_above 0
  Exit                         macd_hist(12, 26, 9) crosses_below 0
  Fills                        next bar's open · capital ₹100000.00
  Costs                        India delivery — brokerage ₹20 or 0.1%, lower, STT, ...

  Net Return (after costs)     -16.60%
  Gross Return (no costs)      -10.96%
  Costs Paid                   ₹5347.83 (5.35% of capital)
  Buy & Hold Return            -35.22%
  Alpha (net vs B&H)           +18.62%
  Max Drawdown                 -33.72%
  Trades                       16 (31% winners)

The numbers are an example. They change with the date you run it.

How to read it:

• Net return is after costs: brokerage, STT, exchange charges, GST, stamp duty and slippage. Gross return is before them. A rule that trades often can lose most of its gain to costs.
• Buy and hold is the benchmark. Compare the net return with it. A rule that loses less than buy and hold in a falling market has not made money.
• Max drawdown is the deepest fall from a peak. Ask whether you would have held on through it.
• Entries and exits are decided on the close and filled at the next open, as you could really trade.

Try variations

stockwise backtest strategies                       # list the built-in strategies
stockwise backtest TCS -s rsi -P oversold=25        # change a parameter
stockwise backtest AAPL -m us -s sma -p 5y          # US stock, five years
stockwise backtest portfolio TCS INFY HDFCBANK -s sma --rebalance monthly
stockwise backtest walkforward RELIANCE -s rsi --train 1y --test 3mo

A walk-forward test picks the best parameters on one year of data, trades the next three months with them, then moves forward. Only those later windows count. This guards against fitting a rule to old data. Try it before you trust a result that looks good.

To test your own rules, write a small TOML file and run stockwise backtest TCS -s file:my_rules.toml. The format is in Backtesting.

Two simpler questions have their own commands:

stockwise sip NIFTYBEES 5000 -p 5y          # what a monthly SIP became
stockwise whatif TCS 100000 2015-01-01      # what a lump sum became

Part 2: Practise on a past market

Start a replay

stockwise sim replay list                    # the built-in scenarios
stockwise sim replay start covid-crash-2020  # 3 Feb 2020, ₹1,00,000 of paper money
stockwise sim challenge start crash-survivor # optional: play for a goal

You see the account and every stock’s close, its change on the day and over 20 trading days. That is all you know, as on the real morning. Scenarios include the 2020 crash, the 2008 crisis, the 2023 Adani report, the 2000 dot-com bust and the 2021 bull run.

Trade one day at a time

stockwise sim replay chart TCS --days 120        # price history up to today's close
stockwise sim replay buy TCS 10 --stop 1900      # set where you are wrong first
stockwise sim replay next                        # orders fill at tomorrow's open
stockwise sim replay status                      # positions, orders and the market
stockwise sim replay next 5                      # five trading days at once
stockwise sim replay sell TCS                    # the whole position, at the next open

Orders fill at the next day’s open. Stops and targets are checked against each day’s range. Costs are charged as in a real India delivery trade.

Finish and read the score

stockwise sim replay end            # scorecard, badges and what happened
stockwise sim profile               # your badges and best scores
stockwise sim card --svg card.svg   # a shareable result card

The score rates how you traded: return for the risk you took, how deep your drawdown went, whether you kept to your own rules and how widely you spread your money. Raw return does not score on its own.

Next steps

• Set up alerts and the daemon. The daemon is a paper-trading bot that runs sessions for you.
• Check a stock or fund fast before you backtest a stock.
• Script a sweep over strategies: see Script it with JSON, CSV and jq.
• Every backtest option, the cost model and the JSON shape are in Backtesting. Replays, challenges, scoring and your own scenarios are in Practice mode.
• The commands are listed under Strategies and bots.

Script it with JSON, CSV and jq

This guide shows how to take StockWise output into a spreadsheet, a shell script, a cron job or another program. It takes about five minutes.

You need: StockWise, and jq for the JSON examples. A spreadsheet handles the CSV.

1. Choose a format

Many commands take --json, and commands that print tables also take --csv. stockwise <command> --help shows which flags a command has. You cannot combine the two.

stockwise portfolio --json   # one JSON document
stockwise portfolio --csv    # a header row, then one row per holding

Both go to stdout and contain nothing else. Progress messages and errors go to stderr, so redirecting stdout is safe.

2. Open it in a spreadsheet

stockwise portfolio --csv > portfolio.csv
stockwise history TCS -p 1y --csv > tcs.csv       # every daily bar
stockwise screen dividend --csv | column -s, -t   # a quick view in the terminal

The CSV columns have the same names as the JSON keys.

symbol,shares,avg_cost,cost_basis,price,value,pnl,pnl_percent,weight_percent,xirr_percent,currency,name,price_source,nav_date
TCS.NS,6.0,3250.0,19500.0,2498.5,14991.0,-4509.0,-23.12,17.92,-4.61,INR,TATA CONSULTANCY SERV LT,quote,

3. Pull one number with jq

stockwise portfolio --json | jq '.totals'

{"cost_basis":70000.0,"value":83637.0,"pnl":13637.0,"pnl_percent":19.48,"currency":"INR"}

More patterns:

# The three worst holdings by return
stockwise portfolio --json | jq -r '.holdings | sort_by(.pnl_percent) | .[:3][] | "\(.symbol) \(.pnl_percent)%"'

# Estimated tax so far this year
stockwise tax in --json | jq '.realized.total_tax'

# Taxable long-term gain in a past year
stockwise tax export in --fy 2025-26 --json | jq '.summary.taxable_ltcg'

# Symbols of triggered alerts
stockwise alert check --json | jq -r '.[] | select(.status == "triggered") | .symbol'

# Prices only
stockwise quote TCS INFY --json | jq '.[] | {symbol, regularMarketPrice}'

# Your return against the index
stockwise portfolio benchmark --json | jq '{portfolio_return, benchmark_return, beta: .metrics.beta}'

The shape of every command’s JSON is in the Shapes table.

4. Loop over symbols

# RSI and bias for everything on your watchlist
for s in $(stockwise watch --json | jq -r '.[].symbol'); do
  stockwise technical "$s" --json | jq -r '"\(.symbol)\t\(.rsi_14)\t\(.bias.verdict)"'
done

# Compare the built-in strategies on one stock
for s in rsi macd sma bb vwap mr; do
  stockwise backtest INFY -s "$s" --json | jq -r '"\(.strategy)\t\(.total_return_percent)"'
done

5. Rules that make scripts safe

• Exit code. Errors go to stderr and the command exits with status 1, so set -e and || work.
• Empty is not an error. An empty portfolio prints {"holdings": [], ...} or a CSV header with no rows.
• Missing is null. A value that is not available is null in JSON and an empty cell in CSV. It is never 0. Test for null before you do arithmetic.
• Names are stable. Keys are snake_case. The exceptions are quote and search, which pass Yahoo’s own camelCase fields through.
• Percent fields. A field ending in _percent is a percentage: 12.5 means 12.5%. A dividend_yield is a fraction: 0.012 means 1.2%.
• Dates are YYYY-MM-DD. history bar times are RFC 3339 in UTC.
• No AI text. The --ai section is never part of JSON or CSV output.

6. Run it on a schedule

Save the day’s portfolio value with wealth, and mail yourself a daily line:

# crontab: weekdays at 16:00
0 16 * * 1-5  stockwise wealth > /dev/null
5 16 * * 1-5  stockwise portfolio --json | jq -r '"Portfolio \(.totals.value) (\(.totals.pnl_percent)%)"' | mail -s "StockWise" you@example.com

Check alerts from cron with stockwise alert watch --once; see Set up alerts and the daemon.

Save your defaults in a config file so scripts do not repeat flags:

stockwise config init     # writes a starter config file
stockwise config show     # where each setting comes from

Shell completion for zsh:

stockwise completions zsh > ~/.zfunc/_stockwise

Next steps

• Use StockWise from Claude or Cursor for the same data through an assistant.
• Rebalance to target weights and File your Indian capital-gains tax both print JSON you can feed into a sheet.
• The full list of JSON shapes and the rules above are in the commands reference. The configuration file section lists every setting.
• A web version of the same data: stockwise serve --open. See Web dashboard and API.

Cheatsheet

One page of the commands people use most. stockwise <command> --help shows every option; the commands reference explains each one.

For step-by-step walkthroughs, see What do you want to do?.

Bare tickers use the Indian market (TCS → TCS.NS). Add -m us, -m uk, -m jp, -m crypto, -m fx, -m commodity … for other markets, or set STOCKWISE_MARKET. Many commands take --json, and tables take --csv (stockwise <command> --help shows which).

Quotes and markets

Analysis

Funds, options, commodities, bonds

Portfolio and tax

Alerts and watchlist

Planning

Strategies and practice

AI assistants

Dashboards and scripting

Live trading (real money)

Every order shows a preview and asks you to type yes. Practise with stockwise sim first. StockWise is not financial advice — see the disclaimer.

Commands Reference

stockwise --help lists every command by group; stockwise <command> --help shows its arguments. This page adds detail.

Looking for a walkthrough instead? What do you want to do? lists task-based guides, and each section below links to its guide.

Global options

Other environment variables: STOCKWISE_HOME (data directory), STOCKWISE_REDIS_URL (cache server, or off), STOCKWISE_DATA_PROVIDER and its API key (data-providers.md), STOCKWISE_AI_PROVIDER, STOCKWISE_MODEL, OLLAMA_HOST and the cloud AI keys (ai.md), STOCKWISE_CONFIG (config file path), STOCKWISE_BIND and STOCKWISE_API_TOKEN (serve), and the notification variables (bots.md). NO_COLOR disables colour; colour is also off when output is piped.

Defaults for most of these, and for each command’s -p, can live in a config file. Precedence: command-line flag > environment variable > config file > built-in default. API keys and the server token are read from the environment only.

Crypto and FX: prices show with the precision they need (FX pairs 4 decimals, coins under 1 up to 8) and quote notes trading hours (crypto 24/7; FX 24 hours Monday–Friday, closed at weekends). Commands built on exchange sessions, sectors or fundamentals — sectors, rotation, sectorcmp, screen, picks, matrix, surprise, peers, intraday, longterm, daemon, sim start — refuse -m crypto / -m fx with an explanation; movers, heatmap, history, technical, backtest and friends work.

Global exchanges (-m uk|de|jp|hk|sg|ca|au): quotes, history, charts, technicals, movers (each exchange’s large caps), markets and alerts work as for India and the US. Prices show in the local currency (£, €, ¥, HK$, S$, C$, A$); London quotes in pence, so VOD.L shows 118.20p while its market cap shows in pounds. sectors, rotation and sectorcmp need sector indices or ETFs, which Yahoo has for Japan (TOPIX-17 ETFs), Hong Kong, Canada and Australia only. Sessions, lunch breaks, half days and holidays come from each exchange’s calendar (markets.md). tax has rules for India, the US and the UK only, and names the other listings it leaves out. Backtest costs default to the US model outside India. The bots and the simulator (intraday, longterm, daemon, sim start, sim replay, sim challenge, report) size positions from the capital you type, so they refuse -m uk, whose prices are in pence; replays on other exchanges use their main index as the benchmark.

Commodities (-m commodity): GOLD/SILVER resolve to COMEX futures, so history gold, chart silver, technical gold and alert add gold above 4200 work; commodity and bonds have their own commands (below).

Hindi (--lang hi): help group titles and the main command descriptions, quote, markets, dashboard, portfolio, search and doctor labels, and common errors. Other commands are still English. Indian amounts keep lakh/crore grouping (₹16.27 लाख करोड़).

Periods (-p): 1d, 5d, 1w (same as 5d), 1mo, 3mo, 6mo, ytd, 1y, 2y, 5y, 10y, max. Value names (screen growth, tax in, -s macd) are case-insensitive.

Exit codes: 0 success, 1 runtime error (unknown symbol, no data, network, invalid config file), 2 invalid arguments.

Machine-readable output: commands marked [--json] print JSON, and [--json\|--csv] print JSON or CSV, instead of a table. See Scripting.

Start here

Guide: Quickstart: five minutes walks through the first commands.

stockwise SYMBOL with no command prints a one-screen overview, and bare stockwise prints a quick start. Short names: q (quote), d (dashboard), a (analyze), t (technical), c (compare), p (portfolio), w (watch), ev (events). The aliases are lowercase: a capital single letter is a ticker, so stockwise C -m us (Citigroup), T, D, A and W work as bare symbols, and stockwise c TCS INFY still compares. A longer ticker that spells a command, such as ALL or PATH, is a symbol when you give -m (stockwise PATH -m us). stockwise quote C -m us always works. Common names resolve to NSE symbols (SBI → SBIN, L&T → LT, index names), and quote suggests close matches for a mistyped symbol.

Analysis

Guide: Check a stock or fund fast.

--explain on verdict, technical, score and options oi adds plain-English notes for beginners.

Market

Guide: Check a stock or fund fast.

--universe (Indian market): scan the current members of an NSE index instead of the built-in 30 large caps — nifty50, niftynext50 (next50), nifty100, banknifty (niftybank), niftyit, nifty500, midcap150 or smallcap250. NSE’s website lists the members and prices them in one bulk request (all 500 of nifty500), whichever data provider you use. movers and heatmap rank from that snapshot alone, so they work when Yahoo Finance is unreachable; screen needs P/E and market cap too, so it asks Yahoo for them and falls back to the snapshot (no P/E or market cap) when Yahoo fails. Every scan also saves the prices into cache.db (market_snapshots) and the index members for the cap tiers below. When NSE can’t be reached or refuses, StockWise says so on stderr and scans a built-in list instead (the 30 large caps for nifty50 / nifty100, a built-in member list for banknifty and niftyit); niftynext50 has no built-in list and fails with the reason.

Cap tiers (mega, large, mid, small, micro): a badge such as [Large] next to the market cap in quote, deep, analyze and compare (and a Cap column in movers, screen and portfolio), and a cap_tier field in their --json / --csv (unknown when there is no market cap, or no exchange rate for the currency). Indian stocks follow the SEBI/AMFI ranks when the index members are known: NIFTY 100 is large (the top 10, or above ₹5,00,000 Cr, is mega), NIFTY MIDCAP 150 is mid, NIFTY SMALLCAP 250 is small and anything outside NIFTY 500 is micro. Scanning those indexes with --universe saves their members (cap_membership.json in the data directory); until then, and offline, rupee cut-offs decide (large from ₹1,00,000 Cr, mid from ₹33,000 Cr, small from ₹10,000 Cr). Every other market converts the market cap to dollars at the built-in approximate rates (London pence GBp and Japanese yen JPY included): mega from $200B, large from $10B, mid from $2B, small from $300M. A display and filtering aid, not a regulatory classification.

--cap all|mega|large|mid|small|micro keeps one tier in movers, heatmap and screen. With a tier, -m in and -m us scans read fresh (under 30 minutes old) market_snapshots rows from cache.db when cache warm or the worker has stored most of the market’s list, with no request at all; otherwise they scan live. There is no per-sector drilldown command yet, so --cap has nothing to filter there.

Funds & F&O

Guide: Check a stock or fund fast covers funds and SIP returns.

MF periods (-p) are <n>mo, <n>y or max, e.g. 6mo, 3y, 10y. Expiries (-e) are YYYY-MM-DD.

options payoff legs and presets

• A leg is buy|sell [QTY] call|put STRIKE [@PRICE] or buy|sell [QTY] stock [@PRICE]: --leg "buy call 24500" --leg "sell call 24800", --leg "sell 2 put atm-1", --leg "buy stock @2450". STRIKE is a listed strike, or atm, atm+N, atm-N (N listed strikes from the money). An unlisted strike is an error that names the nearest listed ones.
• Prices: the bid/ask mid where both are quoted, else the last trade (flagged ltp — it can be stale), else the leg needs @PRICE. A stock leg is priced at the current underlying value (for an index that stands in for the future).
• Presets around the at-the-money strike, W = --width (default two strike steps; a strike that isn’t listed snaps to the nearest one, with a note): bull-call (buy ATM call, sell ATM+W), bear-put (buy ATM put, sell ATM−W), straddle (buy ATM call and put), strangle (buy ATM−W put and ATM+W call), iron-condor (sell ATM±W, buy ATM±2W wings — a credit), butterfly (buy ATM±W calls, sell two ATM calls), covered-call (stock at spot, sell ATM+W call). --strategy and --leg combine.
• Sizes: every amount is per position — per-unit P/L × lot size × --lots. Lot sizes come from the chain (NSE/BSE order-book quantities are whole lots; US contracts are 100 shares). After hours BSE shows no order book: pass --lot-size, otherwise amounts are per unit and the output says so.
• Probability of profit: the chance the expiry price lands where P/L > 0 if the price is lognormal with the at-the-money IV (or --iv) and risk-neutral drift. It is a model, not a forecast. Costs (brokerage, STT, exchange charges) are not included. StockWise never places orders from this command.

Where the data comes from, and what has none

• NAVs: AMFI’s public NAVAll.txt, every Indian scheme, cached in the data directory (cache/) and re-downloaded after 12 hours. NAV history: api.mfapi.in, a free community mirror of AMFI data, cached the same way. If a download fails, a stale cached copy is used with a warning on stderr.
• Returns are point-to-point NAV returns of the growth option, before tax and exit load. mf sip buys at the first NAV on or after each monthly due date.
• Expense ratios (TER): AMFI’s monthly TER disclosure (amfiindia.com/ter-of-mf-schemes), fetched from the API behind that page as one spreadsheet export for the month (/api/populate-te-rdata-revised?MF_ID=All&Month=MM-YYYY&strCat=-1&strType=-1&excel=true, ~3 MB; the previous month if the current one isn’t published yet). It lists each scheme’s TER per day for the regular and direct plan — from April 2026 split into base expense ratio, brokerage, transaction costs and statutory levies. StockWise keeps each scheme’s latest day, caches the result in cache/amfi_ter.json for a day, and uses a stale copy with a warning if AMFI is unreachable. The disclosure has no AMFI scheme code, so schemes are joined on their name (case and punctuation ignored); a plan the scheme doesn’t offer (AMFI writes 0) has no TER. When TERs can’t be loaded, mf nav/history/screen still print NAVs and returns with a note; --sort ter and --max-ter fail instead. In JSON, ter holds plan, total, the breakdown, both plans’ totals and the disclosure date, as fractions (null when not disclosed). mf overlap shows Yahoo’s expense ratio for the funds it covers.
• Holdings (mf overlap) come from Yahoo Finance, which publishes the top 10 holdings and sector weights for US ETFs and mutual funds (SPY, QQQ, VTI, VFIAX, … with -m us) and for some funds under Yahoo’s 0P… IDs. NSE-listed ETFs such as NIFTYBEES and AMFI scheme codes have no holdings data — StockWise says so instead of guessing. With only the top 10 known, the holdings overlap is a lower bound; sector weights cover the whole fund.
• Option chains: in the Indian market (the default), NSE’s public option-chain API — index options on NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY and NIFTYNXT50 (^NSEI and ^NSEBANK work too) and NSE F&O stocks such as RELIANCE. NSE serves browser sessions only: StockWise loads its option-chain page once for cookies, makes two API calls, and stops with a clear error if NSE refuses — wait a minute and retry. SENSEX, BANKEX and SENSEX50 (also ^BSESN, BSE-BANK.BO) and BSE stock options as SYMBOL.BO come from BSE’s derivatives API, the one behind bseindia.com’s option-chain page: one session, calls 400 ms apart, answers cached for a minute in cache/, no retries. BSE’s site sometimes refuses scripted requests (HTTP 403) — StockWise then says so; wait and retry, or use the website. BSE stock options are rarely traded. With -m us, Yahoo Finance (delayed quotes) for US stocks and ETFs.
• Lot sizes: NSE and BSE quote order-book quantities in whole lots, so the lot is their greatest common divisor across the chain (with at least five quotes; a divisor of 1 counts as unknown); US contracts are 100 shares. options chain shows it and --json has lot_size (null when unknown).
• IV and greeks: Black-Scholes-Merton. IV is solved from the bid/ask mid (else the last trade) at the data timestamp; when that fails, the source’s IV is shown (iv_from in JSON). Risk-free rate defaults to 6.5% (India) / 4.0% (US) — pass --rate with the current T-bill yield. Theta is per calendar day, vega and rho per percentage point. NSE options are European; US equity options are American, so their greeks are the usual European approximation.
• PCR and max pain describe positioning for one expiry; they are not forecasts.

Commodities & bonds

Where the data comes from, and what has none

• Gold and silver spot: Yahoo Finance has no free spot quote, so spot is the COMEX front-month future (GC=F, SI=F, USD per troy ounce) converted at USDINR=X (1 troy ounce = 31.1035 g). It excludes Indian import duty and GST, so jewellers’ rates, IBJA rates and MCX prices are higher.
• MCX futures have no free public feed (MCX’s site is bot-protected and its data is licensed), so StockWise shows COMEX contracts and labels them.
• ETFs are NSE listings via Yahoo, in ₹ per unit; each ETF holds a different amount of metal per unit, so compare % moves, not prices.
• SGB prices come from NSE’s Sovereign Gold Bond list (/api/sovereign-gold-bonds) through the same polite NSE session as the NSE provider, cached for 5 minutes and kept on disk. When NSE refuses (it often blocks scripts), the last saved list is shown with its date; with none, every outstanding tranche is listed without a price — never a guessed one. Tranche details (series, issue date, issue price, maturity = issue + 8 years, early redemption from year 5) are bundled from public tranche tables; 33 of the 44 issue dates were checked against RBI press releases, and RBI moves a maturity a day or two earlier when it falls on a holiday. Their NSE symbols come from a public list and are only shown when NSE’s own list is unavailable. No new SGBs have been issued since February 2024. SGBs you hold are valued from the same list in portfolio and the other holdings commands (see Mutual funds and SGBs).
• Yields: CCIL’s tenor-wise indicative yields, end of day, cached for 6 hours; when CCIL can’t be reached, the five benchmark G-sec yields and T-bill cut-offs on the RBI home page. CCIL and RBI data are for personal, non-commercial use.
• Outstanding G-secs: RBI’s list of Government of India securities, cached for a day.
• Prices of individual G-secs and T-bills are not shown: neither CCIL nor RBI publishes them as a plain page, and NSE’s live debt quotes have no documented API. Enter the price your broker shows into bonds calc.
• Bond math: half-yearly coupons on the maturity date’s day, 30/360 (European) day count, yield compounded half-yearly, simple interest in the final coupon period — the G-sec convention. T-bill yield = (100 − price) / price × 365 / days. Floating-rate bonds (FRBs) are not supported.

Strategies & bots

Guide: Backtest and practise on past markets and Set up alerts and the daemon.

Every backtest form also takes:

Costs, fills, the metrics, walk-forward and the strategy file format are in backtesting.md.

Portfolio

Guide: Import your trades and see true returns and Rebalance to target weights.

Data lives in the directory shown by stockwise doctor.

Lots, sales and tax

Guide: File your Indian capital-gains tax.

Every purchase is a lot: quantity, price, date and where it came from (manual, import:kite, broker:angel, …). portfolio sell takes shares from the oldest lots first — FIFO, as Indian demat accounts and the IRS default work — and keeps each slice as a realized sale.

tax classifies every lot by its own purchase date (long-term after more than 12 months for India and the US) and shows realized gains (sales this tax year) separately from unrealized ones (if you sold everything today). For India it applies the set-off rules: gains and losses of the same kind net first; a short-term loss is set off against short-term gains, then long-term gains; a long-term loss only against long-term gains; then ₹1.25 lakh of LTCG is exempt and STCG is taxed at 20%, LTCG at 12.5%. Losses left over are shown as carry forward. Holdings in another currency (e.g. US shares in tax in) are listed but not included. It is an estimate — it includes the 4% cess but not surcharge or brought-forward losses.

Grandfathering (India): for a long-term lot bought on or before 31 Jan 2018, the cost is the higher of the actual cost and the lower of the 31 Jan 2018 price and the sale price (Section 112A). tax in, tax export in, tax advance and harvest all use it. The price is the day’s highest for a listed share (Yahoo) and the NAV for a mutual fund with an AMFI code; it is looked up once and cached. A lot whose price cannot be found keeps its actual cost, and tax export in says so in its notes. Prices are split-adjusted, so a lot recorded before a split or bonus must carry its adjusted cost.

Same-day trades (India): a buy and sell of one share on the same day net against each other first, in a tradebook import and in trade sync fills. The matched quantity is recorded as an intraday sale (priced at that day’s average buy and sell) and the older lots are left alone. tax in, tax export in and tax advance keep intraday results out of Sec. 111A/112A and show them separately as speculative business income at your slab rate (losses can only be set off against speculative gains). Without a date-time column a delivery buy and sell of held shares on one day cannot be told apart from intraday.

Mutual funds and SGBs in tax in: equity-oriented funds — by their AMFI category: equity schemes (ELSS included), arbitrage, aggressive hybrid and equity savings funds, and Nifty/Sensex index funds — are counted like listed shares and named under the estimate. Debt and other funds (taxed at your slab rate for units bought from 1 Apr 2023, at 12.5% after 24 months for older units), funds not found in AMFI’s file, and SGBs (tax-free when RBI redeems them; sold on the exchange, 12.5% after 12 months without the ₹1.25 lakh exemption) are left out and listed with the rule that applies (other_rules in --json). So are exchange-traded gold, silver and international ETFs (12.5% after 12 months with no exemption, slab rate before) and liquid and debt ETFs (slab rate at any holding period). StockWise knows them from a built-in list of NSE symbols (GOLDBEES, SILVERBEES, LIQUIDBEES, MON100, Bharat Bond EBBETF…, …) and from …BEES names that say gold, silver, liquid, gilt, Nasdaq or Hang Seng; an ETF it does not know is counted like a listed share, as are equity ETFs such as NIFTYBEES. harvest skips the same holdings (they are listed under “Not checked”) and tax export in and tax advance leave their sales out.

tax in, harvest, tax export in and tax advance share one rule for what counts as a listed share or an equity-oriented fund (Sec. 111A/112A); the other three load AMFI’s file to read the category of any fund you sold. Crypto (such as BTC-INR) is never in 111A/112A: it is taxed at a flat 30% under Sec. 115BBH with no set-off of losses, tax export in lists it under virtual_digital_assets, and the other commands name it among the holdings they leave out.

Mutual funds and SGBs

Guide: Import your trades shows how to load a CAS.

Holdings that Yahoo Finance doesn’t quote are priced by StockWise itself, the same way in portfolio, dashboard, tui, serve, wealth, rebalance, harvest, tax, portfolio sell and report portfolio:

• Mutual funds — MF:<AMFI code> (portfolio add MF:120503 10 50) or MF:<ISIN> (the growth/payout or IDCW-reinvestment ISIN, as import cas and Groww imports store them) — at the latest NAV in AMFI’s NAVAll.txt (cached 12 hours). NAVs are end of day: the table says “NAV as of <date>” for each fund, and --json rows carry name, price_source: "amfi_nav" and nav_date. A code or ISIN that isn’t in AMFI’s file, or a scheme AMFI lists without a NAV, stays N/A with a note (find codes with mf search) — never 0. A scheme whose last NAV is over a month older than the file is flagged as possibly matured. MF: symbols are never sent to Yahoo, and watch/alert see the NAV too.
• Sovereign Gold Bonds — the NSE symbol (SGBNOV26, stored as SGBNOV26.NS) or the tranche’s ISIN — at the last price in NSE’s SGB list (price_source: "nse_sgb"). When NSE refuses or shows no trade, the value is one gram of gold at the international spot price per unit, labelled “estimated from gold spot” (gold_estimate). Values leave out the 2.5% yearly interest, which is paid to your bank every six months.

Older versions stored portfolio add MF:120503 as MF:120503.NS (and watch add / alert add likewise); those symbols are repaired when the files load.

Passive income and dividend calendar

stockwise income (or stockwise portfolio income) is a 12-month trailing and projected dividend, coupon and passive-income engine for dividend-growth investors, retirees, and bond/SGB holders:

• Monthly Cashflow Schedule: Shows month-by-month cash flows across trailing 12 months (received dividends recorded in portfolio.dividends) and forward N months (default 12), with a visual terminal bar chart and --json/--csv serialization.
• Yield on Cost (YoC): Calculates per-holding and per-lot Yield-on-Cost (YoC = Annual Dividend / Original Lot Cost), comparing it against current market yield to reveal dividend-growth compounding over time.
• TDS and Withholding Tax: Automatically computes withholding tax (flat 10% TDS for Indian dividends and 25% WHT for US foreign dividends; 0% assumed for other currencies) to report net spendable income.
• Sovereign Gold Bonds & Fixed Income: Models half-yearly 2.5% p.a. SGB coupons on issue nominal values across maturity cycles.
• Payout Safety & Sustainability: Evaluates earnings payout ratios, diagnosing distributions as SAFE (< 60%), CAUTION (60–85%), or WARNING (> 85% or negative earnings).
• Upcoming Radar (stockwise income upcoming): Checks upcoming ex-dividend and payment dates for holdings and watchlists, showing held share counts and calendar details.

Harvest

Guide: File your Indian capital-gains tax.

harvest lists what you could sell to book a loss, and which long-term winners you could sell to use this year’s unused ₹1.25 lakh LTCG exemption. For India it follows FIFO, as a demat account does: to reach a losing lot you must sell the older lots first, so the row shows that whole sale (shares, and the net st_pnl and lt_pnl it books). If selling up to a losing lot books a net gain in all, the holding is not offered as a loss; fifo_blocked (and a note on screen) says how many shares you would sell and what the sale books. For the US you can choose lots, so only the losing lots are offered.

estimated_tax_saved is how much the tax estimate falls when the loss is booked on top of this year’s realized gains, so set-off order, the exemption and cess are counted; a loss with nothing to offset saves 0 and is carried forward. The remaining exemption is shared: each winner takes its part of it, biggest first, and the saving counts only that part. Holdings in another currency (US shares for in) are listed under other_currency and not counted; holdings taxed under other rules (crypto, debt funds, SGBs, gold and similar ETFs) under other_rules.

Tax export

Guide: File your Indian capital-gains tax.

tax export in writes the realized sales of an Indian financial year as a spreadsheet laid out for ITR Schedule CG and Schedule 112A: one row per lot sold with section (111A short-term, 112A long-term), ISIN, scrip, quantity, sale date and value, purchase date and cost, days held and the gain, then a summary block — gains and losses of each kind, the short-term loss set off against LTCG, the ₹1.25 lakh LTCG exemption, taxable STCG/LTCG, the estimated tax and losses to carry forward. ISINs come from NSE’s equity list (shares) and AMFI’s NAV file (funds imported from a CAS), both cached for 12 hours; one that can’t be found is left blank and named. tax export us writes a Form 8949 worksheet instead: Part I (held one year or less) and Part II rows with description, dates (MM/DD/YYYY), proceeds, cost basis and gain, then the Schedule D totals, the $3,000 loss deduction and the carryover.

stockwise tax export in --fy 2025-26 --out cg-2025-26.csv   # file + summary on screen
stockwise tax export in --fy AY2026-27 > cg.csv            # same year, by assessment year
stockwise tax export us --fy 2025 --json | jq '.summary'

--fy takes 2025-26, 2025-2026 or AY2026-27 (India) and 2025 (US); the default is the current tax year. Without --out the CSV (or --json) goes to stdout. It is an estimate — verify it with your broker’s tax P&L: it only knows sales StockWise recorded (portfolio sell, tradebook and CAS imports) at their recorded prices, without brokerage or STT. Shares bought on or before 31 Jan 2018 are flagged — Schedule 112A lets you use that day’s fair market value as the cost, which StockWise doesn’t apply; sales in another currency (US shares for in) and crypto (taxed at 30% under section 115BBH, Schedule VDA) are listed but left out, and so are debt and other funds and SGBs.

The rates follow the sale date: sales before 23 Jul 2024 are taxed at 15% (STCG) and 10% (LTCG), later ones at 20% and 12.5%. The LTCG exemption is ₹1 lakh up to FY 2023-24 and ₹1.25 lakh from FY 2024-25, for the whole of that year. In a mixed FY 2024-25, losses and the exemption are used against the higher-rate gains first (the lowest tax; the Act does not prescribe an order), and the summary shows how much of the taxable gain came from before 23 Jul 2024.

Advance tax (India)

Guide: File your Indian capital-gains tax.

Under Section 208 and 211 of the Indian Income-tax Act, any taxpayer whose estimated tax liability for the financial year is ₹10,000 or more must pay advance tax in four quarterly instalments:

• By 15 June: At least 15% of estimated tax
• By 15 September: At least 45% of estimated tax
• By 15 December: At least 75% of estimated tax
• By 15 March: 100% of estimated tax (capital gains realized between 16 and 31 March are payable by 31 March)

Because capital gains cannot always be predicted in advance, the proviso to Section 234C(1) specifies that deferment interest is not levied if the shortfall is due to capital gains realized after an instalment date, provided the remaining tax is paid in subsequent instalments. stockwise tax advance groups realized sales into the four statutory quarterly cut-offs and calculates cumulative set-offs under Indian equity rules, by sale date: from 23 July 2024 STCG @ 20% and LTCG @ 12.5%, before it 15% and 10%; the LTCG exemption is ₹1.25L (₹1L up to FY 2023-24):

stockwise tax advance                             # current FY advance tax schedule
stockwise tax advance --fy 2025-26                # specific financial year
stockwise tax advance --paid 2025-06-14:3000 --paid 2026-01-10:17800   # dated payments: exact Section 234C interest
stockwise tax advance --paid 25000                # a total with no date: assumed paid on time
stockwise tax advance --json                      # programmatic JSON output

• Section 208 Check: Automatically flags whether advance tax is mandatory (total liability ≥ ₹10,000) or exempt.
• Status: A quarter is Paid only when payments dated on or before its due date cover the minimum. With no --paid, a quarter past its due date is Overdue, because StockWise has no record of any payment.
• Section 234C Deferment Interest: Section 234C looks at what was paid by each due date, so pass each payment with its date (--paid 2025-06-14:3000, repeated). It then charges 1% a month (3% for Q1–Q3, 1% for Q4) on each shortfall, rounded down to ₹100, when the payments by that date are below the safe-harbour level (12% in Q1, 36% in Q2, 75% in Q3, 100% in Q4). For Q4 the requirement on 15 March is the tax on gains up to 15 March; tax on gains after it carries no interest when paid by 31 March (the proviso). A payment dated before the financial year began is ignored (it was made for an earlier year) and the output says so. A payment without a date is assumed to have been made before every due date, which can understate the interest.
• Cess: The tax and the instalments include the 4% health and education cess; surcharge is left out.
• Section 234B Note: Flags potential Section 234B liability if assessed after 31 March and cumulative advance tax paid is below 90% of total liability.

Benchmark and attribution

Guide: Import your trades and see true returns.

portfolio benchmark rebuilds what you held at each close of the period from your lots and sales (in today’s share count, so splits don’t break the history), and compares the portfolio’s time-weighted return with an index over the same days.

stockwise portfolio benchmark                  # vs NIFTY 50 over 1 year (S&P 500 with -m us)
stockwise portfolio benchmark SENSEX -p 2y
stockwise portfolio benchmark SP500 --base inr # S&P 500 converted to rupees day by day
stockwise portfolio benchmark NIFTYBEES -p 6mo --csv

• Benchmarks by name: NIFTY, SENSEX, BANKNIFTY, NIFTY500, SP500, NASDAQ, NASDAQ100, DOW; or an index symbol (^NSEI) or any ticker. Periods: 1mo, 3mo, 6mo, ytd, 1y (default), 2y, 5y, 10y, max.
• The period starts at the first close where something was held. Returns come from daily closes: a purchase or sale counts at that day’s close, so the figure measures the holdings, not your fill prices. Dividends are left out on both sides (NIFTY 50 and the S&P 500 on Yahoo are price indices).
• Alpha (annualized, risk-free rate 0), beta, tracking error, information ratio and correlation come from the daily returns and need 20 of them.
• Attribution: each holding’s average weight, its return while held, its contribution to the portfolio return and to the return over the index, in percentage points (linked with Carino’s method, so they add up exactly to the totals); the same by sector, from Yahoo’s asset profile (“Unknown” when Yahoo has none, “Mutual fund” for funds imported from a CAS, valued from their NAV history).
• Holdings in another currency are converted into the base currency (--base, else the holdings’ one currency, else the market’s) at each day’s exchange rate; an index in another currency is converted too.
• Flagged under Partial history: holdings with no price history (left out), days held before a holding’s price history starts (left out of those days), and purchases inside the period with an estimated date (the shares may have been held earlier than the history shows).

Public Market Equivalent (Index Twin)

stockwise portfolio pme mirrors your exact tradebook cash flows into a passive benchmark index or ETF (e.g. SPY, VOO, VWCE, NIFTY, NIFTYBEES) on their matching trade dates:

• Every buy of $X on date D buys $X worth of the benchmark twin.
• Every sell on date D distributes the equivalent proceeds from the benchmark twin.
• Recorded dividends are distributed from the twin on matching dates.

It answers: “Did my active trading and stock picking actually beat investing in a passive index on the exact same dates?”

Metrics reported:

• Index Twin Value: Current value of the synthetic benchmark portfolio.
• Value Added / Lost: Terminal portfolio value minus Index Twin value (in exact currency units: +$ / +₹).
• Kaplan-Schoar PME (KS-PME): Compounded future value of distributions + terminal portfolio value over future value of investments (> 1.000 indicates active outperformance; 1.000 is parity).
• Direct Alpha (Gredil, Griffiths, Stucke 2014): Annualized IRR of benchmark-discounted cash flows, yielding 0.00% on parity.
• Holding Breakdown: Direct Alpha and Value Added breakdown for each held asset.

XIRR (in portfolio and portfolio lots) is the money-weighted annual return from each lot’s purchase, each sale, recorded dividends and today’s value. It shows — with under 30 days of history. The portfolio figure includes closed positions and converts other currencies at today’s rate.

Lots marked * have an estimated date: holdings from before lot tracking (dated when they were added to StockWise) or imported from a file without dates. Fix one with portfolio lots SYMBOL --lot N --date YYYY-MM-DD.

Corporate actions. portfolio actions lists splits, bonus issues (Yahoo reports a 1:1 bonus as a 2:1 split) and dividends since each holding’s first purchase. Nothing changes until --apply, which multiplies the quantity and divides the price of lots bought before the split (cost and date unchanged) and records each dividend on the shares held at its ex-date. Each lot remembers the splits applied to it, so running it again is a no-op. Indian tax treats bonus shares as bought at zero cost on the allotment date — check bonus lots against your tax statement.

Imports. A holdings export (Kite, INDmoney) has no purchase dates: existing lots are kept and only the quantity is matched — more shares add a lot dated today, fewer shares come out of the oldest lots (not recorded as a sale). trade holdings syncs the same way. When the snapshot has more shares and a split or bonus isn’t applied to your lots yet, that holding is skipped until you run portfolio actions --apply (otherwise the bonus shares would be counted twice). A file with a date column (Date, Purchase Date, Buy Date, trade_date, …) is a list of lots: each symbol’s lots are rebuilt from it. With a buy/sell column (trade_type, Type, Side) it is a tradebook — such as Zerodha Console’s — sells come out FIFO as realized sales, and splits and bonuses are applied as they happened (this needs a network connection). StockWise keeps the trades of each tradebook import and merges the next file with them, so several yearly tradebooks (Console allows 365 days per download) can be imported one after another, in any order, and re-importing a file changes nothing. A symbol is left unchanged when its sells have no earlier buy yet (the trades are kept; import the earlier tradebook to finish), or when it already has lots or sales from elsewhere (manual entries, another import, or a tradebook imported before StockWise kept trades) — --replace rebuilds it from this file alone anyway. A file of dated buys only (no buy/sell column) is the symbol’s whole list of lots and replaces them. Dates may be YYYY-MM-DD, DD-MM-YYYY, DD/MM/YYYY (MM/DD/YYYY with -m us) or 15-Mar-2024; a file with an unrecognized date is refused.

Mergers. A dated row (or portfolio add --date) for a ticker that was merged away is restated in the acquirer’s shares, keeping the date and the total cost: HDFC up to the 13 Jul 2023 record date becomes HDFCBANK at 42 shares for every 25, and Mindtree up to 24 Nov 2022 becomes LTIM at 73 for every 100 (quantity × ratio, price ÷ ratio). Rows without a date, and plain renames such as ZOMATO → ETERNAL, are mapped to the new name only. Fractional shares from the swap are kept as a fraction (the cash paid for them is not recorded). Existing lots already imported under the new name are not corrected — re-import the tradebook with --replace.

Accounts. Each lot and sale carries the demat account it came from, named after the broker: import kite and trade … --broker zerodha are zerodha, import groww is groww, and so on. A holdings file or tradebook only matches, rebuilds or sells the lots of its own account, so the same stock held at two brokers is two sets of lots in one holding (portfolio lots shows the account). Lots entered by hand or saved by an older version, with no account of their own, count as the account of their source, or — for manual lots — join the first broker that syncs the symbol. Totals and tax span all accounts. portfolio sell works on the whole holding, oldest lot first.

Groww, Upstox, CAS. Groww and Upstox exports are snapshots (quantity sync, like Kite). A CAS whose transactions cover a fund’s whole balance rebuilds it as dated lots, with redemptions as realized sales; otherwise only the quantity is synced. See brokers.md.

Upgrading. Portfolios saved before lot tracking are upgraded on first load: each holding becomes one lot dated when it was added, and the original file is kept once as portfolio.json.bak.

Planning

--from-portfolio and --holdings value the portfolio (or the named holdings, such as MF:122639 or NIFTYBEES) at live prices, or at cost when offline, and use that as existing savings; they replace --savings. Taxes and exit loads are estimates, not advice; --tax defaults to debt up to 60 months and equity beyond, with a 1% exit load on equity lots held under 12 months in India.

stockwise goal sip --target 1cr --years 15                  # ₹19,819 a month at 12%
stockwise goal sip --target 1cr --years 15 --step-up 10     # ₹11,516 a month, rising 10% a year
stockwise goal sip --target 10L --months 9                  # short goal: 6.75% baseline, month-by-month table
stockwise goal sip --target 50L --by 2031-06 --inflation 6 --from-portfolio
stockwise goal retire --monthly-expense 80k --years-to-retire 20 --years-in-retirement 30
stockwise goal education --cost 25L --years 10 --savings 3L
stockwise goal add house --target 50L --by 2031-06 --holdings NIFTYBEES
stockwise goal swp --corpus 1cr --withdrawal 50k
stockwise goal prepay --principal 50L --loan-rate 9 --remaining-months 240 --extra 10k

Amounts take Indian units — 50k, 25L / 25 lakh, 1cr / 1.5 crore, 2,50,000 — and results print in lakhs and crores (dollars with -m us). The math, as Indian SIP calculators do it: the monthly rate is the annual return ÷ 12 and SIPs are paid at the start of each month; a step-up raises the SIP once a year; --savings already invested grows at the same return and lowers the SIP. In retirement the expense rises with inflation once a year and the corpus earns --return-post until it runs out at the end of the last year. Returns are assumptions, not promises.

AI assistants

Guide: Use StockWise from Claude or Cursor.

Both use the same read-only tools (quotes, history, technicals, risk, scorecards, insights, events, mutual funds, option chains, IPOs, screens, backtests, your portfolio, lots, tax estimate, advance tax, harvest and rebalance plans, calendar, goals, watchlist and alerts). See ai.md.

stockwise ask "how is my portfolio doing?"
claude mcp add stockwise -- stockwise mcp     # Claude Code
stockwise mcp --list-tools | jq '.[].name'

Interfaces

Both are read-only and share the data layer with the commands above, so they show the same numbers. They are on by default and can be left out of a build with --no-default-features (cargo features tui and server).

Live trading

See brokers.md. Orders are previewed and need a typed yes. Every trade command takes --broker angel|zerodha|upstox|dhan|fyers (default angel, or STOCKWISE_BROKER); all but angel are experimental — untested against a live account.

Setup

Scripting with --json and --csv

Guide: Script it with JSON, CSV and jq.

stockwise portfolio --json | jq '.totals'
stockwise portfolio --json | jq -r '.holdings | sort_by(.pnl_percent) | .[:3][] | "\(.symbol) \(.pnl_percent)%"'
stockwise portfolio --csv > portfolio.csv                 # open in a spreadsheet
stockwise history TCS -p 1y --csv > tcs.csv               # every daily bar
stockwise alert check --json | jq -r '.[] | select(.status == "triggered") | .symbol'
stockwise screen dividend --csv | column -s, -t
stockwise tax in --json | jq '.realized.total_tax'
stockwise tax export in --fy 2025-26 --json | jq '.summary.taxable_ltcg'
stockwise portfolio benchmark --json | jq '{portfolio_return, benchmark_return, beta: .metrics.beta}'
stockwise goal sip --target 1cr --years 15 --json | jq '.monthly_sip'
for s in rsi macd sma bb vwap mr; do
  stockwise backtest INFY -s "$s" --json | jq -r '"\(.strategy)\t\(.total_return_percent)"'
done
for s in $(stockwise watch --json | jq -r '.[].symbol'); do
  stockwise technical "$s" --json | jq -r '"\(.symbol)\t\(.rsi_14)\t\(.bias.verdict)"'
done
stockwise quote TCS INFY --json | jq '.[] | {symbol, regularMarketPrice}'
stockwise markets --json | jq '.[] | select(.change_percent < -1)'
stockwise mf sip 122639 5000 -p 3y --json | jq '{invested, value, xirr}'
stockwise options chain NIFTY -n 2 --json | jq '.rows[] | {strike, delta: .call.greeks.delta}'
stockwise options payoff NIFTY -s straddle --json | jq '{breakevens, pop, max_loss}'
stockwise mf screen flexi cap -s ter --json | jq '.[] | {name, ter, return_3y}'

Rules

• stdout holds only the JSON or CSV; errors go to stderr with exit code 1, so set -e and || work. --json and --csv can’t be combined.
• Empty states are not errors: an empty portfolio prints {"holdings": [], ...} or a CSV header with no rows.
• Keys are stable snake_case. The exceptions are quote --json and search --json, which pass Yahoo’s own fields through (camelCase, unchanged since 0.3); their --csv uses snake_case columns.
• A value that isn’t available is null in JSON and an empty cell in CSV — never 0. A holding without a live price keeps its row but is left out of totals and listed in unpriced.
• Fields ending in _percent are percentages (12.5 = 12.5%). dividend_yield in quote, compare and screen is a fraction as Yahoo reports it (0.012 = 1.2%). Prices are as Yahoo returns them; derived money values are rounded to 2 decimals, indicators to 4.
• Dates are YYYY-MM-DD; history bar times are RFC 3339 in UTC.
• CSV follows RFC 4180 quoting (fields with a comma, quote or newline are quoted, quotes doubled), starts with a header row, and ends lines with \n. CSV columns are the same names as the JSON row keys.
• The --ai section is never part of JSON or CSV output.
• mf and options have their own --json (no --csv); fractions there are decimals (0.1234 = 12.34%), and missing values are null, never 0.
• options payoff --json is {symbol, source, underlying, currency, as_of, expiry, days_to_expiry, strategy, width, lot_size, lot_size_from, lots, multiplier, rate, div_yield, legs: [{side, qty, instrument, strike, price, price_from, iv, iv_from, delta}], net_premium, net_premium_total, premium_type, max_profit, max_loss, breakevens, profit_ranges: [{from, to}], pop, pop_iv, pop_iv_from, greeks: {delta, gamma, theta, vega, rho}, notes, curve: [{price, expiry, today}]}. net_premium and leg prices are per unit (positive = debit); money totals, greeks and the curve are for the whole position (× multiplier = lot size × lots). max_profit/max_loss are null when unlimited; max_loss is negative; to: null means “and above”. price_from is mid, ltp, manual or spot. Money values, prices and breakevens are rounded to 2 decimals.

Shapes ([...] is an array; row is described next to it)

Alert conditions

Guide: Set up alerts and the daemon.

stockwise alert add <SYMBOL> <CONDITION> <NUMBER>:

Technical conditions read daily bars (one chart request per symbol per check), with the last bar updated to the live quote, so a cross or breakout fires on the session it happens in. A symbol with too little history reads no_data and never triggers. alert watch notifies each alert once until it re-arms, at most once per trading day.

stockwise alert add INFY rsi-below 30
stockwise alert add INFY rsi-above 70 --period 9
stockwise alert add RELIANCE cross-above-sma 200
stockwise alert add AAPL -m us breakout-high 52
stockwise alert add HDFCBANK change-below 3
stockwise alert add TCS volume-spike 2
stockwise alert add TCS results-in 7

Alerts saved by earlier versions keep working unchanged.

Results and corporate calendar

Guide: Check a stock or fund fast and Set up alerts and the daemon.

stockwise calendar lists what is coming up for your holdings and watchlist (--holdings or --watchlist for one of them, or name symbols), over the next 30 days (--days 1-365):

• For an Indian stock, NSE’s filed results date replaces Yahoo’s estimate, and NSE’s ex-dividend date replaces Yahoo’s.
• Upcoming splits come from NSE only; Yahoo lists splits after they happen, so US splits don’t appear in advance.
• BSE filings are not read; a .BO symbol uses the same company’s NSE filings.
• NSE’s API serves browser sessions. StockWise opens one session per run, waits a second between requests and caches every answer for a day in calendar_cache.json (failures for an hour). When NSE refuses, the table says so and shows Yahoo’s dates.
• Crypto, FX and indices have no calendar and are skipped.

stockwise calendar
stockwise calendar --holdings --days 14
stockwise calendar TCS INFY
stockwise calendar AAPL MSFT -m us --json

Configuration file

Everything works without one. To set your own defaults:

stockwise config init     # write a commented template
stockwise config path     # where it is
stockwise config show     # every effective setting and where it came from

The file is config.toml in your platform’s config directory — ~/Library/Application Support/stockwise/ on macOS, ~/.config/stockwise/ on Linux ($XDG_CONFIG_HOME), %APPDATA%\stockwise\ on Windows — or the file named by STOCKWISE_CONFIG.

market = "us"                       # in | us | crypto | fx | commodity | uk | de | jp | hk | sg | ca | au
lang = "hi"                         # en | hi
quote_currency = "inr"              # BTC → BTC-INR with -m crypto
portfolio = "long-term"             # a named portfolio
ai = false
ai_provider = "ollama"              # ollama | openai | anthropic | gemini
model = "llama3.1:8b"
ollama_host = "http://gpu-box:11434"
data_provider = "yahoo"             # yahoo | alphavantage | massive | twelvedata
redis_url = "off"
home = "~/Dropbox/stockwise"        # data directory; ~ is your home

[periods]                           # default -p per command
technical = "6mo"
backtest = "5y"
sip = "10y"

[notify]                            # STOCKWISE_* notification variables, lower-case, no prefix
telegram_chat_id = "123456789"
smtp_host = "smtp.gmail.com"
email_to = "me@example.com"

[periods] accepts the commands that take -p: deep, technical, history, risk, patterns, support, fibs, volume, gaps, stoploss, forecast, options, backtest, sip. --help shows the default from your file, e.g. [default: 6mo].

A file that doesn’t parse — an unknown key, a wrong type, an unknown market or period — stops every command with exit code 1 and an error naming the file and the key. config, doctor and completions still run, so you can inspect it or replace it with stockwise config init --force.

API keys (OPENAI_API_KEY, the data provider’s key, …) and STOCKWISE_API_TOKEN are read from the environment only. Notification tokens and passwords may go in [notify]; if they do, keep the file private (chmod 600) — config show and doctor warn when other users can read it.

stockwise serve answers with the same shapes over HTTP — see server.md.

Markets

-m picks the market bare tickers belong to. India (in, the default) and the US (us) have their own lists and rules; crypto (crypto), currency pairs (fx) and gold and silver (commodity) trade around the clock or 24x5; and seven more stock exchanges come from one market table in src/market.rs.

Global exchanges

stockwise -m uk quote VOD BARC          # VOD.L, BARC.L — prices in pence (118.20p)
stockwise -m jp history 7203 -p 1y      # Toyota, 7203.T
stockwise -m hk quote 700 5             # 0700.HK, 0005.HK
stockwise -m au sectors                 # S&P/ASX 200 sector indices
stockwise markets --global              # every exchange's main index, open or closed now

What each row holds:

• Symbols: the Yahoo Finance suffix bare tickers get. Symbols that already say where they trade (TCS.NS, ^FTSE) pass through unchanged.
• Currency: prices use the local symbol (£, €, ¥, HK$, S$, C$, A$). London quotes shares in pence: prices print as 118.20p, market caps (which Yahoo reports in pounds) as £27.38B, and portfolio totals convert pence at GBP’s rate ÷ 100. Enter London costs in pence too (portfolio add VOD.L 100 118.2). The bots and the simulator size positions in pounds, so they refuse -m uk for now.
• Benchmarks for markets (-m uk markets leads with the FTSE 100, FTSE 250 and FTSE All-Share); the first one is the markets --global row.
• Sectors where Yahoo has a usable set: TOPIX-17 sector ETFs (Japan), Hang Seng sub-indices (Hong Kong), iShares S&P/TSX sector ETFs (Canada), S&P/ASX 200 sector indices (Australia). The UK, Germany and Singapore have none, so sectors, rotation and sectorcmp say so.
• Universe: 14–15 large caps scanned by movers, screen and the bots.
• Session and time zone: European and Australian summer time are computed (no time-zone database needed); Tokyo, Hong Kong and Singapore have lunch breaks, during which is_open is false and alerts wait.
• Holidays (src/clock.rs): weekday closures and half days from each exchange’s own calendar — LSE business days, Deutsche Börse’s trading calendar, JPX’s holiday page, SEHK circulars CT/075/25 and CT/077/26, ASX’s trading calendar, TMX holiday notices, and for SGX the Ministry of Manpower public holidays it follows (2026 cross-checked against SGX’s monthly trading-day counts; 2027 provisional for SGX and TSX until they publish). Years outside a table fall back to “every weekday trades”, and markets --global warns about it.
• Tax: stockwise tax has rules for India, the US and the UK only. Other listings are left out of an estimate and named.

Commodities

-m commodity resolves GOLD (or XAU) to COMEX gold futures GC=F and SILVER (XAG) to SI=F; other bare tickers are NSE listings, for gold and silver ETFs (GOLDBEES) and Sovereign Gold Bonds. So history gold, chart silver, technical gold and alerts work on them. stockwise commodity shows spot in ₹/g, ₹/10 g and ₹/kg; see commands.md for where every number comes from — and what has no free source (MCX).

Indian government bonds

stockwise bonds reads CCIL’s tenor-wise indicative yields (RBI’s benchmarks as the fallback) and RBI’s list of outstanding G-secs, and prices bonds with bonds calc. markets shows the India 10-year yield. Details and limits are in commands.md.

Adding an exchange

1. Add a variant to Exchange and a MarketInfo row to GLOBAL_MARKETS in src/market.rs, in the same order (a test checks the order). Check every symbol against Yahoo Finance first.
2. Add its holiday table to src/clock.rs (weekday closures and half days, from the exchange’s own calendar) and list the years in official_years. If its time zone has summer time not covered by a TzRule, add the rule with a test of the changeover instants.
3. Add its title to the messages! table in src/i18n.rs (MarketXx).
4. If the exchange quotes in a new currency, add its symbol to currency_symbol in src/market.rs.
5. cargo test market clock checks suffixes, universes, hours, that every holiday is a weekday in a covered year and that half days trade.

Updating holiday tables

Exchanges publish next year’s list between June (HKEX) and December (NSE, TMX). Add the rows, move the year into official_years, and run cargo test clock.

Data providers

StockWise gets market data from Yahoo Finance by default — no account or key needed. You can opt in to another provider for quotes, daily history and symbol search. Yahoo stays in the loop either way: it fills every field the other provider lacks and answers whatever the provider can’t.

export STOCKWISE_DATA_PROVIDER=twelvedata
export TWELVEDATA_API_KEY=...
stockwise doctor            # "Twelve Data answered for AAPL (180 ms)"
stockwise quote AAPL -m us  # ends with "Data: Twelve Data"

Providers

Free-tier limits are the providers’ own and change over time; check their pricing pages. Twelve Data’s free plan is licensed for internal, non-display use only.

Indian stocks: none of the keyed free tiers carries NSE, and only Alpha Vantage carries BSE. With those providers, TCS (TCS.NS) keeps coming from Yahoo; RELIANCE.BO goes to Alpha Vantage. For prices straight from the exchanges, use nse, bse or exchange below. SENSEX (^BSESN) and non-Indian indices always come from Yahoo.

What goes where

NSE and BSE

export STOCKWISE_DATA_PROVIDER=exchange   # or nse, or bse; or data_provider = "exchange" in config.toml
stockwise doctor              # "NSE answered for RELIANCE.NS (640 ms)", "BSE answered for 500325.BO (...)"
stockwise quote RELIANCE      # ... Circuit Limits ₹1,307.20 — ₹1,597.60, Delivery 52.35%, "Data: NSE"
stockwise quote 500325        # a bare 6-digit number is a BSE scrip code (500325.BO)
stockwise movers --universe nifty50

What these are. NSE and BSE have no free public market-data API. Their websites load prices from JSON endpoints meant for the site’s own pages, and these providers read the same endpoints. They are unofficial and undocumented: the exchanges can change, rate-limit or block them at any time, and their terms of use restrict automated access and redistribution of their data. Use them for your own analysis; don’t republish what they return, and check NSE’s and BSE’s terms of use yourself. Licensed real-time feeds come from the exchanges’ data vendors (NSE Data & Analytics, BSE’s data products) and from brokers’ market-data APIs.

What StockWise reads

Everything else — names when the exchange gives none, fundamentals, multi-day intraday bars (-p 5d), history beyond 5 years or -p max, dividends and splits — comes from Yahoo, exactly as with the other providers. --json quotes from NSE add deliveryPercent, lowerCircuit and upperCircuit (and dataSource: "NSE"); --csv has delivery_percent, lower_circuit and upper_circuit columns, empty for other sources.

Being a polite client

• One session per site per run: NSE’s home page is loaded once for the cookies its API expects; an expired session (HTTP 401) is renewed once.
• At most three requests a second per site, with random jitter on top, across everything a command does.
• Timeouts, HTTP 429 (honouring Retry-After, capped at 10 s) and 5xx are retried twice with exponential backoff.
• A refusal is final. HTTP 403 or an “Access Denied” page means the site doesn’t want automated requests right now: StockWise prints one ⓘ notice on stderr, stops asking that site for 15 minutes (the rest of a normal run), and Yahoo answers. It never retries a refusal with different headers.
• If an endpoint disappears (404) or answers in a shape StockWise doesn’t know, it says “NSE changed its response format (…)” once and Yahoo answers. doctor shows the same reason.
• Answers share the Redis / in-memory cache (quotes 30 s, intraday 1 minute, daily history 10 minutes, search 1 hour); the BSE scrip list and NSE’s equity file are kept in the data directory’s cache/ for a day.
• Big scans stay on Yahoo: a quote request for more than 12 uncached NSE symbols (8 on BSE) goes to Yahoo in one request rather than waiting on the rate limit. Members of an index fetched with --universe are already priced by that one NSE request, so movers --universe nifty500 costs one NSE request and no Yahoo request, and still works when Yahoo is unreachable; screen --universe also asks Yahoo for P/E and market cap.

Mixed mode (exchange): .NS symbols and NSE indices go to NSE, .BO symbols to BSE, and US stocks, crypto, FX and SENSEX to Yahoo — so a portfolio holding both TCS and AAPL gets each price from its own market. search lists NSE matches first, then BSE’s.

Index members (--universe on movers, heatmap and screen) come from NSE whichever provider is set; see commands.md. Offline, the built-in lists stand in.

The fields StockWise reads from each endpoint, and how to record a fresh response for a test fixture, are in exchange-responses.md.

Backup providers (Finnhub and FMP)

Set a key and the provider joins a router that backs Yahoo up — no STOCKWISE_DATA_PROVIDER needed (name one there and it becomes the primary provider instead):

export FINNHUB_API_KEY=...   # US quotes, profile, analyst trend, earnings surprises
export FMP_API_KEY=...       # quotes, statements, screener
stockwise doctor             # "Backup providers: Finnhub answered for AAPL (210 ms)"
stockwise config show        # finnhub_api_key (set) — the value is never shown

Keys stay in the environment. They are sent in a header (Finnhub) or added to the request when it is sent (FMP), and never reach a cache key, a log line or an error message.

Each capability goes to the best configured provider that covers the symbol and still has calls left in its free-tier window, then down the list:

Field-level merge. When two sources each supply part of a quote — Finnhub the price, FMP the market cap, or Yahoo the price and Finnhub’s profile the market cap — the first source to answer keeps its fields and the others fill only what is empty. --json quotes then carry meta.sources, in the order the sources answered: {"meta": {"sources": ["Yahoo Finance", "Finnhub"]}}. Quotes Yahoo answered completely cost no backup request and carry no meta. Only lists of ten symbols or fewer get holes filled (one extra request each); bigger tables stay as the first source gave them, so one table never burns a free tier.

Free-tier windows. Finnhub gets 60 calls a minute; FMP gets 16 every two hours (its 250 a day, with room for two windows to touch). A provider with no calls left in its window is skipped for the next one, not waited for. A rate limit or refused key pauses the provider and prints one ⓘ notice.

Built from documentation. The Finnhub and FMP clients follow the providers’ documented response formats (Finnhub /quote, /stock/profile2, /stock/recommendation, /stock/earnings; FMP’s stable API: batch-quote, profile, income-statement, balance-sheet-statement, cash-flow-statement, company-screener). They are tested against recorded shapes, not against the live services. Free plans do not reach every exchange or endpoint; a refused request falls through to the next source.

BSE filings. The BSE provider also reads a scrip’s corporate announcements and quarterly-result filings (AnnGetData) and the members of a BSE group (ListofScripData with Group). These follow the format open-source BSE clients read and are unconfirmed against the live site. BSE 500 snapshots are not read yet.

Limits and fallback

• Each command spends at most a small allowance of provider requests — 4 for Alpha Vantage, 5 for Massive, 8 for Twelve Data — so one scan can’t burn a day’s allowance or wait a minute for the next slot. The allowance comes back after a window: a minute for Massive and Twelve Data, 4 h 48 min for Alpha Vantage (4 a window: two windows can touch, so 5 could reach 29 in a day against its limit of 25). A long-running serve, tui, mcp or daemon therefore keeps using the provider instead of dropping to Yahoo after the first few requests.
• If a provider reports a rate limit, refuses the key, or can’t be reached, StockWise prints one ⓘ notice on stderr, stops asking it for a while (to the end of the window after a rate limit, 3 minutes after a network error, an hour after a refused key) and uses Yahoo meanwhile. A later pause prints its own notice. --json output on stdout is unaffected.
• Yahoo’s cookie-and-crumb handshake, which quotes, fundamentals and options need, is tried once per call. When it fails, the failure is remembered for 45 seconds and later calls get the same error at once, so a command that makes dozens of fundamentals calls doesn’t repeat six requests and their waits for each. Charts and search need no crumb and are unaffected.
• When AMFI’s NAV file or a scheme’s NAV history can’t be downloaded, mf commands use the saved copy only if it is at most 7 days old; mf nav and mf history then say so under the table and add a stale entry (source, reason, day saved) to --json. An older copy is an error that says how old it is.
• A provider’s quote is dated by its own trading day (Alpha Vantage’s “latest trading day”, Twelve Data’s timestamp, the day of Massive’s latest bar), so an end-of-day quote from yesterday is never taken for today’s trade.
• Provider answers share the Redis / in-memory cache (quotes 1–5 minutes, daily history 10 minutes), so repeating a command doesn’t spend another request. API keys are never part of a cache key or an error message.
• An unknown provider name or a missing key is reported (by every command on stderr, and by doctor) and StockWise carries on with Yahoo.
• doctor asks the provider for one AAPL quote to show it answers — one request of your allowance per run. With nse, bse or exchange it asks for RELIANCE.NS and/or 500325.BO instead and reports each exchange on its own line.

--json quotes from another provider carry a "dataSource" field naming it; Yahoo-only quotes don’t have the field.

Adding a provider

Implement the MarketData trait in src/providers/ (quote, daily series, search), map Yahoo-style symbols to the provider’s syntax and back, and add a ProviderKind. Parse responses in pure functions with fixture tests, and test the HTTP path against testutil::MockServer — tests must never call a real API or need a real key. A source without an API (a website’s JSON) goes through providers::session::Session, which brings the rate limit, retries, caching and refusal handling.

AI Integration

StockWise works with AI in three ways:

• Commentary — report and --ai add a plain-English section to analysis commands.
• stockwise ask — ask a question; the model calls StockWise’s read-only tools (quotes, technicals, your portfolio, …) and answers from the results. See Ask in plain English.
• stockwise mcp — an MCP server, so Claude Desktop, Claude Code, Cursor and other assistants can use the same tools. See Use StockWise from AI assistants.

By default the model runs locally through Ollama: no stock data, portfolio or credentials leave your machine. If you prefer a hosted model you can opt in to OpenAI, Anthropic or Google Gemini instead (see Cloud providers). Everything else in StockWise works without any AI.

Setup (local, the default)

# Install Ollama (macOS; see ollama.com for Linux/Windows)
brew install ollama

# Start the server
ollama serve

# Pull the default model
ollama pull qwen3:14b

# Check that StockWise can see it
stockwise doctor

Commentary: reports and --ai

Dedicated reports always use the model:

stockwise report intraday     # Notes on today's intraday scan
stockwise report longterm     # Research notes on the long-term scores
stockwise report portfolio    # Notes on your portfolio (funds at NAV, SGBs from NSE)
stockwise report RELIANCE     # Single-stock analysis

Opt-in sections on analysis commands — add --ai (or set STOCKWISE_AI=1 to make it the default):

stockwise analyze RELIANCE --ai
stockwise compare TCS INFY --ai

Educational, not advice

Every prompt starts with the same rules: explain what the data shows — signals, trends, valuation context, risks and what to watch — in neutral, conditional language, and never tell the reader to buy, sell, hold, accumulate or avoid anything, never pick a winner, and give no price targets, entry or exit levels, position sizes or allocations. This follows SEBI’s rules for investment advisers and research analysts (and its guidance on finfluencers): StockWise is neither. Every AI section ends with a one-line disclaimer:

AI-generated educational analysis, not investment advice or a recommendation to buy, sell or hold. StockWise is not a SEBI-registered investment adviser or research analyst.

A model can still ignore its instructions; treat its output as commentary. The prompts live in src/ai.rs (ai::prompts), and a test checks that none of them asks for a verdict or a call. When the prompts change, PROMPT_VERSION is bumped: it is part of the cache key, so an answer cached under older wording is never shown again.

AI is opt-in because a local model typically takes 30–60 seconds per answer, which would turn these sub-second commands into minute-long waits. StockWise prints a progress line while the model works, and caches answers for an hour when Redis is available.

The daemon workers write an end-of-day AI note when local Ollama is running. With a cloud provider they only do so when started with --ai.

Ask in plain English

stockwise ask "how is my portfolio doing?"
stockwise ask "compare TCS and INFY on RSI and one-year risk" --verbose
stockwise ask "what SIP reaches 1 crore in 15 years at 12%?"
stockwise ask "which of my holdings are long term for tax?" --json

ask sends your question and the list of StockWise tools to the configured model. The model picks tools, StockWise runs them (read-only, against live data and your local portfolio), sends the results back, and the model answers in plain English. The answer ends with the tools that ran. The tools are the same ones the MCP server offers.

At most 12 tool calls run per question, and each result is kept to about 24 KB (12 KB for local models): long price histories keep their newest bars and option chains their strikes nearest the money. With Ollama the model must answer once the conversation fills most of its 16k-token context.

Models. ask needs a model with tool (function) calling:

• Ollama: qwen3 (the default qwen3:14b), llama3.1, qwen2.5, mistral-nemo and other models tagged tools on ollama.com. StockWise asks Ollama for a 16k-token context, because the tool definitions alone take a few thousand tokens. A model without tool support gets a clear error naming one that has it.
• Cloud (opt-in, see below): OpenAI (Responses API function calling), Anthropic (Messages API tool use) and Gemini (generateContent function calling). Running ask is the opt-in, as with report; --ai is not needed.

Answers are educational, not financial advice: the model is told to describe what the data shows and its risks, not to tell you to buy or sell. The tools cannot place orders.

Privacy. With a cloud provider, the question and every tool result go to that provider — including your holdings, lots and tax figures when the model calls portfolio_summary, holdings_lots or tax_estimate. Keep the default local Ollama if that matters to you. The first request of each run prints the usual notice.

Use StockWise from AI assistants (MCP)

Guide: Use StockWise from Claude or Cursor is a short walkthrough of this section.

stockwise mcp is a Model Context Protocol server built on the official Rust SDK. AI assistants start it and call its tools; it runs on your machine with your data directory and needs no account.

stockwise mcp                          # stdio — what desktop and editor clients use
stockwise mcp --http 127.0.0.1:8788    # Streamable HTTP at http://127.0.0.1:8788/mcp
stockwise mcp --list-tools             # the tools and their JSON schemas

Set it up

Claude Code

claude mcp add stockwise -- stockwise mcp
claude mcp add stockwise -- stockwise mcp -m us     # US tickers by default

Claude Desktop — Settings → Developer → Edit Config, then restart:

{
  "mcpServers": {
    "stockwise": {
      "command": "stockwise",
      "args": ["mcp"]
    }
  }
}

Use the full path from which stockwise (where stockwise on Windows) if Claude Desktop can’t find the command.

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "stockwise": {
      "command": "stockwise",
      "args": ["mcp"]
    }
  }
}

Without installing — once the PyPI wheels are published, any client can run it through uv: command uvx, args ["stockwise", "mcp"]. With Docker: command docker, args ["run", "-i", "--rm", "-v", "stockwise:/data", "ghcr.io/iamsaquib8/stockwise", "mcp"].

Other clients — command stockwise, args ["mcp"], transport stdio; or point an HTTP client at stockwise mcp --http.

Settings work as usual: -m us (or STOCKWISE_MARKET) sets the market for bare tickers, --portfolio NAME picks a named portfolio, STOCKWISE_HOME the data directory. Add them to args or the client’s env.

Tools

There are 35 tools. Every tool only reads. Each result is JSON with the data, a short “not financial advice” note, and truncated when long lists were shortened. Tools that take tickers accept market (in, us, crypto, fx, commodity, uk, de, jp, hk, sg, ca, au).

Hosts see each tool’s read-only and open-world hints; the portfolio tools are marked as not reaching outside your machine.

Resources and prompts

Orders stay with you

The MCP server never places, modifies or cancels orders, and never reads broker credentials. That is a deliberate choice: an assistant can misread a request, and a prompt hidden in a web page or document it read could try to trade for you.

stockwise mcp --allow-orders adds one more tool, order_preview. It checks an order you are considering against the last price (the same trigger and price checks as trade), estimates its value, and returns the stockwise trade command — for example stockwise trade buy TCS 2 --broker zerodha --limit 4000 — for you to review and run. That command shows its own preview, applies the max_order_value cap from your broker config and asks you to type yes. Nothing is sent to a broker from the MCP server.

HTTP

--http ADDR serves Streamable HTTP at http://ADDR/mcp, stateless, with JSON responses. It follows the same rules as stockwise serve:

• Loopback addresses only (127.0.0.1:8788, localhost:8788) unless you pass --allow-remote, which requires STOCKWISE_API_TOKEN (16+ characters); every request must then send Authorization: Bearer <token>.

• Without a token, requests must name a loopback host (Host header) and come from no browser origin or a localhost one, so a web page you visit can’t reach it through DNS rebinding.

• Loopback alone does not authenticate operating-system users. On a shared machine, another local user can call the unauthenticated MCP HTTP endpoint and read available portfolio data. Set STOCKWISE_API_TOKEN even when listening only on 127.0.0.1, and configure your HTTP MCP client to send Authorization: Bearer <token>.

Put a TLS proxy in front of it before exposing it beyond your network.

Registry and Claude Desktop extension

• server.json describes the server for the official MCP registry as io.github.iamsaquib8/stockwise. It lists the crates.io package and the GHCR image (ghcr.io/iamsaquib8/stockwise); uvx stockwise mcp works once the PyPI wheels are published.
• packaging/mcpb/ builds a Claude Desktop extension (.mcpb) from a release binary.

For agents: Agent Skill and llms.txt

• skills/stockwise/SKILL.md is an Agent Skill that tells Claude Code and other agents how to use the CLI (--json, markets, safe commands) and the MCP server. Copy the folder into ~/.claude/skills/ (or a project’s .claude/skills/).
• The documentation site publishes llms.txt (an index of the docs and the cheatsheet’s commands) and llms-full.txt (every page in one file), and a Markdown copy of each page.

Configuration

Environment variables win over the config file. API keys are read from the environment only, never from the config file.

STOCKWISE_MODEL=llama3.1:8b stockwise report portfolio
STOCKWISE_ALLOW_REMOTE_OLLAMA=1 OLLAMA_HOST=192.168.1.20:11434 stockwise report TCS

If the Ollama model isn’t pulled, StockWise tells you the exact ollama pull command instead of printing an empty section. An unknown STOCKWISE_AI_PROVIDER value is an error, never a silent fallback: StockWise won’t guess where to send your data.

Cloud providers (opt-in)

export STOCKWISE_AI_PROVIDER=anthropic
export ANTHROPIC_API_KEY=...            # from console.anthropic.com
stockwise doctor                        # shows provider and model, never the key
stockwise report RELIANCE               # first cloud request of the run prints a notice

To use a cheaper or newer model, set STOCKWISE_MODEL — for example gpt-6-luna, claude-sonnet-5-5, claude-haiku-5-5 or gemini-3.5-flash-lite. STOCKWISE_MODEL applies to whichever provider is active, so change or unset it when you switch providers.

The prompts are the same for every provider. On Claude models that support it (Opus 5.5, Opus 5, Sonnet 5.5, Fable 5.x), StockWise asks the API to retry a safety-classifier decline on Anthropic’s recommended fallback model (fallbacks: "default"); a request that is still declined is reported as an error, not as an empty answer.

Privacy

• Nothing is sent unless you choose a cloud provider. The default is Ollama on your own machine.
• Choosing a provider is not enough on its own. A cloud model is called only for report (which you run to get AI output) or when you add --ai (or set STOCKWISE_AI=1). Plain commands never contact it.
• What is sent: the prompt for that command — the market data StockWise fetched (prices, ratios, indicators, backtest numbers) and, for report portfolio, your holdings with quantities, cost and fund names. No broker credentials, API keys for other services, or data-directory files are included.
• You are told when it happens: the first cloud request of each run prints ⓘ Sending this request's data to <provider> (<model>): market data, and your portfolio if a tool reads it on stderr.
• Keys are read from the environment and sent only in request headers, never in URLs, logs or error messages. doctor names the variable it found, not its value.
• Requests to OpenAI set store: false. Each provider’s own data-retention policy still applies; read it before sending portfolio data.
• Answers are cached for an hour in Redis (when running) under a hash of the prompt version, provider, model and prompt, so repeating a command doesn’t send it again.

Suggested local models

Model output is commentary, not advice. See DISCLAIMER.md.

Backtesting

stockwise backtest replays a strategy over daily price history and reports what it would have made after trading costs. It can test one stock, a portfolio of stocks sharing one pot of capital, or run a walk-forward test that tunes parameters on old data and scores them only on newer data. Strategies are small TOML files; the six built-ins are files too.

Backtests describe the past. They are not predictions and not financial advice — see DISCLAIMER.md.

Quick start

Guide: Backtest and practise on past markets walks through a backtest and a replay.

stockwise backtest INFY -s macd                     # one stock, 2 years, Indian delivery costs
stockwise backtest TCS -s rsi -P oversold=25        # change a parameter
stockwise backtest AAPL -m us -s sma -p 5y          # US stock, US cost model
stockwise backtest portfolio TCS INFY HDFCBANK -s sma --rebalance monthly
stockwise backtest walkforward RELIANCE -s rsi --train 1y --test 3mo
stockwise backtest strategies                       # list built-in and your own strategies
stockwise backtest TCS -s file:my_rules.toml        # your own strategy file

Every form takes --json.

How a backtest trades

• Data. Daily bars from Yahoo Finance for -p (default 2y; 5y for walk-forward). A bar missing any of open, high, low or close is dropped, never filled in. Prices are split-adjusted; dividends are not credited.
• Signals at the close, fills at the next open. Entry and exit rules are checked on each bar’s close and filled at the next bar’s open — the first price you could actually trade at. --fill close fills at the signal bar’s close instead (how StockWise 0.3 and earlier filled); it peeks at a price that only exists once the bar is over, so it flatters results.
• Long only, whole shares. An entry buys as many whole shares as the cash allows after costs; an exit sells them all. Cash earns nothing. If the capital can’t buy one share the entry is skipped and counted.
• Entry and exit on the same bar cancel: no new position is opened, and an open one is closed.
• Stops and targets (stop_loss_pct, take_profit_pct in a strategy file) are measured from the entry price and checked against each bar’s low and high. A gap through the level fills at the open. If one bar touches both, the stop is assumed to have hit first.
• The last bar. A position still open at the end is sold at the last close, with costs, and listed as still open.

Costs

Costs are on by default. --costs auto (the default) uses the crypto model for coins (-m crypto, BTC-USD), the FX model for currency pairs (-m fx, USDINR=X), India delivery for INR stocks, and the US model for everything else. The Indian presets are refused for coins and currency pairs.

The stock presets add 5 bps of slippage per fill: buys fill 0.05% above the price, sells 0.05% below. Override with --slippage-bps, and brokerage with --brokerage: 20 (flat per order), 0.03% (percent of the order), or 20,0.03% (whichever is lower). A Zerodha delivery account is --brokerage 0. Rates are NSE equity rates as of 2025; check your broker’s contract note.

Worked example (delivery): buy 100 shares at ₹1,000 and sell at ₹1,100.

The ₹10,000 gross profit keeps ₹9,704.26 — before slippage. A unit test checks these numbers.

Every report shows the net return (after costs), the gross return (the same rules with --costs none), and the money paid in costs.

What the numbers mean

Portfolio backtests

stockwise backtest portfolio TCS INFY HDFCBANK RELIANCE -s sma
stockwise backtest portfolio TCS INFY -s rsi --weights 0.7,0.3
stockwise backtest portfolio AAPL MSFT NVDA -m us -s macd --weights inverse-vol --rebalance monthly

Each symbol gets a sleeve of the capital — its weight — and trades the strategy on its own; a flat sleeve holds cash. The report adds a per-symbol table: trades, win rate, net P&L, contribution (sleeve P&L as a percent of starting capital; the contributions add up to the total return), and how often the symbol was held.

• --weights equal (default), explicit weights (0.5,0.3,0.2, normalised, one per symbol), or inverse-vol: weight ∝ 1 ÷ volatility of the last 63 daily returns, computed at each rebalance from data before that day. inverse-vol needs --rebalance.
• --rebalance none|monthly|quarterly: on the first trading day of each month or quarter, at the open, overweight positions are trimmed, cash is moved between sleeves, and underweight positions are topped up, so every sleeve is back at its weight. Drifts under 1% are left alone. Trades pay costs as usual.
• Symbols are aligned by date; a symbol with no bar on a day keeps its last price. Every symbol must trade in the same currency and use the same cost model (stocks and coins can’t share a portfolio backtest unless you pass one --costs).

Walk-forward

A single backtest picks parameters with hindsight. Walk-forward avoids that:

history:  |----- train 1 -----|- test 1 -|
                    |----- train 2 -----|- test 2 -|
                              |----- train 3 -----|- test 3 -|

For each window, every parameter combination in the strategy’s [grid] is backtested on the train window; the one with the best Sharpe (among those that traded) trades the following test window. Only test windows count. The test windows are chained with compounding capital into one out-of-sample equity curve, after costs.

Positions carry across windows: the chosen parameters trade from the start of their train window, so a position they would already hold is open when the test window starts, and a position open at a window’s end is valued, not sold — only the last window sells at the final close. A trade is listed in the window it closes in. Switching parameters between windows is assumed to cost nothing.

stockwise backtest walkforward RELIANCE -s rsi --train 1y --test 3mo -p 10y

• --train / --test take 90d, 13w, 6mo, 1y, counted in daily bars: for stocks a week is 5, a month 21 and a year 252 trading days; crypto trades every day (7, 30, 365); FX years are 260 weekdays. Train needs 20 bars or more, test 5. Windows step forward by the test length; a short final test window is kept if it has at least half the test length.
• The report lists each test window with the chosen parameters, in-sample return and Sharpe, and out-of-sample return and Sharpe, then the stitched out-of-sample result and an overfitting check:
  • Walk-forward efficiency: out-of-sample annualised return ÷ the average in-sample annualised return.
  • Verdict: inconclusive with fewer than 2 windows or no out-of-sample trades; no edge if it loses money even in-sample; likely overfit if out-of-sample loses money, keeps under 30% of the in-sample return, or its Sharpe is more than 1.0 lower; degraded under 60% or a Sharpe gap over 0.5; otherwise robust.
• A strategy without a [grid] has nothing to tune; walk-forward then checks how stable fixed parameters are across periods.

Strategy files

-s takes:

1. A built-in: rsi, macd, sma (sma_crossover), bb (bollinger), vwap, mr (mean_reversion).

2. The name of a file in your strategies folder: -s trend_pullback loads trend_pullback.toml from

   • strategies/ next to your config file — stockwise config path shows where that is (~/Library/Application Support/stockwise/ on macOS, ~/.config/stockwise/ on Linux, %APPDATA%\stockwise\ on Windows), or
   • $STOCKWISE_HOME/strategies/ when STOCKWISE_HOME is set.

   stockwise backtest strategies prints the folder it uses.

   Built-in names win over files of the same name. A NAME.wasm plugin in the folder is found too (after NAME.toml).

3. A path: -s file:path/to/rules.toml (or any path ending in .toml).

4. A WASM plugin: -s wasm:path/to/strategy.wasm — see WASM plugins. Needs a build with --features wasm-plugins.

The built-ins live in examples/strategies/ next to two more examples (trend_pullback, breakout) — copy one to start. stockwise backtest strategies lists everything and checks your files; stockwise backtest strategies FILE... checks specific files. Both exit 1 if a file has errors.

Format

name = "trend_pullback"                 # optional; defaults to the file name
description = "Buy RSI dips above the 200-day average"
entry = ["close > sma(200)", "rsi(14) < $dip"]   # all must hold
exit = "rsi(14) > 70 or close < sma(200)"
stop_loss_pct = 8                       # optional, from the entry price
take_profit_pct = 15                    # optional

[params]                                # numbers, used as $name
dip = 35

[grid]                                  # optional: values walk-forward tries
dip = [30, 35, 40]

Unknown keys are errors, so a typo like stop_los_pct is caught.

Conditions

A condition compares two values:

Combine conditions with and, or, not (or &&, ||) and parentheses. Values can be numbers, $params, the series below, and + - * / between them: close < sma(20) * (1 - $band_pct / 100). Keywords and indicator names are case-insensitive; parameter names are not.

These are the indicators of src/technical.rs; a test checks that every value matches. Periods are whole numbers from 1 to 1000 and may be $params.

While an indicator is warming up it has no value, and a condition that uses it is neither true nor false — so nothing fires, even under not. Division by zero behaves the same way.

The file is checked before anything runs, with messages that name the file and the condition:

Error: rules.toml: entry "rsx(14) < 30": unknown indicator `rsx`. Available: close, open, ...
Error: rules.toml: `$dip` is used in a condition but not defined under [params]
Error: strategy `rsi` has no parameter `oversld` (it has: overbought, oversold, period)

Strategies in the intraday bot

stockwise intraday 50000 1.5 -s trend_pullback

intraday -s adds a strategy file as one more signal next to the bot’s nine: a Long vote (strength 70) when its entry rule holds on the latest daily bar, a Short vote (strength 60) when its exit rule holds. The rule gets its own daily history (one year, or more for slow indicators), so the built-in signals are unchanged. The vote shows as Custom rule in the plan’s strategy list.

Not yet: daemon intraday and sim start don’t take -s.

WASM plugins

Experimental. When a strategy needs state or logic that TOML conditions can’t express — a custom indicator, a regime filter, a model — write it in any language that compiles to WebAssembly and load it with -s wasm:PATH:

cargo install stockwise --features wasm-plugins

cd examples/wasm-strategy-rsi
cargo build --target wasm32-unknown-unknown --release   # rustup target add wasm32-unknown-unknown
cd -

P=examples/wasm-strategy-rsi/target/wasm32-unknown-unknown/release/wasm_strategy_rsi.wasm
stockwise backtest RELIANCE -s wasm:$P -P oversold=25
stockwise backtest portfolio TCS INFY HDFCBANK -s wasm:$P
stockwise backtest walkforward TCS -s wasm:$P
stockwise intraday 50000 1.5 -s wasm:$P
stockwise backtest strategies $P        # check a plugin: name, ABI, parameters

A plugin works everywhere a TOML strategy does: single, portfolio and walk-forward backtests, -P overrides, [grid]-style tuning, and the intraday bot’s extra vote. Copy it into your strategies folder as NAME.wasm to run it as -s NAME; backtest strategies lists it with its declared name and ABI version. -s wasm:FILE.wat also loads WebAssembly text, handy for tiny experiments.

examples/wasm-strategy-rsi is a complete plugin in Rust with no dependencies: RSI mean reversion with exactly the built-in rsi strategy’s signals (a test checks every grid combination). src/backtest/fixtures/level.wat is the smallest complete one, in WebAssembly text.

Sandbox

• No imports. A plugin gets no host functions: no WASI, files, network, clock or randomness. A module that imports anything is refused at load (build for wasm32-unknown-unknown, not wasm32-wasip1).

• Fuel. Each call runs on a budget of about one unit per instruction: 10 million for a stockwise_on_bar call, 50 million for instantiation and each setup call. An endless loop stops with an error at the first bar.

• Memory. 64 MB of linear memory per instance, one memory, plugin files up to 16 MB, and wasmi’s strict limits on module structure (functions, globals, tables, data segments).

• Errors, not crashes. A trap (a Rust panic, an out-of-bounds access, division by zero, stack overflow), running out of fuel or memory, or a return value outside the ABI ends the command with exit code 1 and a message naming the plugin, the call and the bar:

  Error: loop.wasm: `stockwise_on_bar` on bar 1 of 496 (2024-10-23): ran past its budget of 10000000 instructions for one call — an endless loop?
  Error: src/backtest/fixtures/level.wat: the plugin rejected {"level":0.0} (`stockwise_init` returned 1): level must be a whole number above 0
  

• No look-ahead. The plugin sees bars one at a time, oldest first, so a signal can only depend on the bars before it — the same guarantee as TOML rules. Signals take effect as usual: at the next bar’s open by default.

ABI (version 1)

A plugin is a WebAssembly module with these exports. Integers are i32 / i64; strings cross as UTF-8 in the plugin’s exported memory, returned as one i64 packing (pointer << 32) | length.

Signals. stockwise_on_bar returns 0 (nothing), 1 (entry), 2 (exit) or 3 (both: an exit while holding, nothing when flat — as when a TOML strategy’s entry and exit rules both hold). A negative value is an error reported by the plugin (with stockwise_error’s message); anything else is refused as bad output. time is the bar’s start in Unix seconds (UTC); volume may be 0.

Lifecycle. At load, StockWise instantiates the module once to check the exports and their signatures, call stockwise_abi_version and read stockwise_meta. Then every price series — each symbol, each parameter set in walk-forward, each stock the intraday bot scans — gets a fresh instance: stockwise_alloc(len), the parameters written there, stockwise_init(ptr, len), then stockwise_on_bar for each bar. Keep state in globals; it never leaks between series. Parameter defaults and every grid combination are tried through stockwise_init at load, so a plugin can refuse values up front.

Metadata (stockwise_meta), every key optional, unknown keys refused:

{
  "name": "rsi-wasm",
  "description": "RSI(14) mean reversion as a WASM plugin",
  "params": { "period": 14, "oversold": 30, "overbought": 70 },
  "grid": { "oversold": [25, 30, 35], "overbought": [65, 70, 75] },
  "lookback": 15,
  "stop_loss_pct": 8,
  "take_profit_pct": 15
}

name defaults to the file name. params and grid follow the TOML rules (names of letters, digits and _; at most 500 grid combinations); -P sets a parameter and fixes it for walk-forward. lookback (default 0, at most 10,000) is how many bars the plugin needs before its first signal: backtests refuse shorter histories and the intraday bot fetches enough. stop_loss_pct and take_profit_pct work as in TOML.

Parameters reach stockwise_init as compact JSON: one flat object of every parameter, names sorted, numbers as JSON numbers — {"overbought":70.0,"oversold":25.0,"period":14.0}. Keys never contain , : or quotes, so a small hand-written reader is enough (the example does this).

Runtime

Plugins run in wasmi 2.x, a pure-Rust WebAssembly interpreter. It was chosen over wasmtime because:

• Size and build time. With the feature, the release binary grows by 2.4 MB (12.9 → 15.3 MB on aarch64 macOS): 1.5 MB for wasmi and 0.9 MB for the WAT text parser. Its crates add about 35 s of CPU time to a release build, mostly in parallel with the rest. wasmtime with Cranelift is several times larger, slower to compile, and pulls in a much bigger dependency tree.
• MSRV. wasmi 2.0 builds on Rust 1.86, well inside StockWise’s 1.97. wasmtime requires the newest compilers (wasmtime 50 needs 1.97, and each monthly release moves that up), which would tie StockWise’s MSRV to wasmtime’s release train.
• Limits. wasmi meters fuel deterministically per instruction and enforces memory, table and module-structure limits — what a plugin sandbox needs. wasmtime’s extra features (JIT speed, epoch interruption, WASI) are unneeded: a plugin does a few hundred instructions per bar, and has no host access.
• No unsafe host surface. No imports are linked, the module is validated before it runs, and an interpreter cannot jump to plugin-generated machine code.

The feature is off by default, so default builds and binaries are unchanged.

JSON output

--json prints one object. Percentages end in _percent; money is in the stock’s currency.

• backtest SYMBOL: symbol, currency, strategy, period, interval, bars, start, end, fill, capital, the metrics (start_value, end_value, total_return_percent, cagr_percent, max_drawdown_percent, sharpe, sortino, exposure_percent, trade_count, win_rate_percent, avg_win_percent, avg_loss_percent, profit_factor, costs_paid), gross_return_percent, buy_hold_return_percent, alpha_percent, skipped_entries, costs (brokerage, stt, exchange, sebi, gst, stamp, dp, slippage, total), cost_model, rules (the strategy as loaded, with -P applied), trades: [trade] and equity: [{date, value}]. A trade is {symbol, entry_date, exit_date, qty, entry_price, exit_price, gross_pnl, costs, net_pnl, pnl_percent, bars_held, exit_reason} with exit_reason one of signal, stop-loss, take-profit, rebalance, end-of-data.
• backtest portfolio: the same, with symbols, weights, rebalance, rebalances and per_symbol: [{symbol, weight, pnl, contribution_percent, trades, win_rate_percent, costs, exposure_percent}].
• backtest walkforward: symbol, currency, strategy, period, interval, fill, capital, cost_model, rules, train_days, test_days, combos, folds: [{params, in_sample, out_of_sample}] (each window {start, end, bars, return_percent, annualised_percent, sharpe, max_drawdown_percent, trade_count}), out_of_sample (the metrics), out_of_sample_gross_return_percent, out_of_sample_annualised_percent, in_sample_annualised_percent, in_sample_sharpe, efficiency, verdict, verdict_reason, trades, equity.
• backtest strategies: {builtin: [{aliases, strategy}], directory, user: [{path, ok, strategy | error}], skipped_plugins: [path]}. skipped_plugins lists .wasm files a build without wasm-plugins did not load.

For a WASM plugin, rules (and strategy above) has empty entry and exit, the plugin’s params and grid, and plugin: {abi_version, lookback}.

for s in rsi macd sma bb vwap mr; do
  stockwise backtest INFY -s "$s" --json | jq -r '"\(.strategy)\t\(.total_return_percent)"'
done

Limits

• Long only; no short selling, leverage or F&O.
• Daily bars only. Intraday costs (--costs in-intraday) can be applied, but positions are still held from one daily bar to another.
• Dividends are not credited; symbols that were delisted are not in Yahoo’s data (survivorship bias).
• WASM plugins are experimental and opt-in (--features wasm-plugins); the ABI may change in a later version, which bumps abi_version.

Practice mode: replays, challenges and scores

Practice mode turns the paper-trading simulator into a way to learn. You trade a past market one day at a time, without seeing what comes next, and you get a score for how you traded: return for the risk you took, how deep your drawdowns went, whether you kept to your own rules, and how widely you spread your money. Raw return never scores on its own.

Everything here uses paper money. Nothing in practice mode can reach a broker, and every scorecard and card says so: paper trading — not financial advice.

• A five-minute tutorial
• Replays
• Challenges
• Scores, grades and badges
• Profile and result cards
• Your own scenarios and challenges
• JSON output
• Files and limits

For the bot-driven daily simulator (sim start, sim settle) see bots.md.

A five-minute tutorial

Guide: Backtest and practise on past markets puts this next to backtesting.

stockwise sim replay list                       # the built-in scenarios
stockwise sim replay start covid-crash-2020     # 3 Feb 2020, ₹1,00,000 of paper money
stockwise sim challenge start crash-survivor    # optional: play for a goal

You see the account, the challenge and the market on the replay date: every stock’s close, its change on the day and over 20 trading days. That is all you know — the same as an investor on that morning.

stockwise sim replay chart index                 # NIFTY 50 up to today's close
stockwise sim replay chart TCS --days 120
stockwise sim replay buy TCS 10 --stop 1900      # decide where you are wrong first
stockwise sim replay buy HINDUNILVR 8 --stop 2000 --target 2600
stockwise sim replay next                         # orders fill at tomorrow's open
stockwise sim replay status
stockwise sim replay next 5                       # five trading days at once
stockwise sim replay set TCS --stop 2000          # move a stop
stockwise sim replay sell TCS                     # the whole position, at the next open
stockwise sim replay end                          # scorecard, badges, what happened
stockwise sim card --svg card.svg                 # share the result

Replays

sim replay start takes a built-in scenario, a scenario file, or your own window:

stockwise sim replay start --from 2022-01-03 --to 2022-06-30 --symbols TCS,INFY,HDFCBANK,ITC
stockwise -m us sim replay start --from 2008-09-02 --to 2009-03-31 --symbols JPM,BAC,XOM,KO --benchmark ^GSPC
stockwise sim replay start covid-crash-2020 --capital 500000 --costs none

A custom window uses the global market (-m in, the default, or -m us) and benchmarks against NIFTY 50 or the S&P 500 unless you pass --benchmark. Its stocks have no sector, so the diversification part of the score only counts the number of stocks; write a scenario file to name sectors.

The future stays hidden. At the start, StockWise downloads each stock’s daily history once (about a year before the window, for charts, through the window’s end) and saves it next to the replay. From then on the replay runs offline. The price data lives in one place, and every view — tables, charts, scorecards and --json — reads it only up to the replay date. A test plants impossible prices after the replay date and checks that none of them, and none of their dates, appear in any output.

How orders fill. The replay day is over when you see it: you know its close. Orders you place fill at the next trading day’s open:

• Sells fill before buys on the same morning, so you can rotate from one stock to another in one step. A buy that the cash no longer covers (a gap up) is cut to what you can afford.
• Every fill pays slippage and the same charges as the backtester (costs): India delivery (brokerage, STT, exchange and SEBI fees, GST, stamp duty, DP charge) for NSE stocks, the US model for US stocks. --costs none|in-delivery|in-intraday|us overrides the choice.
• After the fills, stop-losses and targets are checked against the day’s low and high. A stop fills at its level, or at the open if the stock gapped through it; when a day touched both, the stop is assumed first.
• Long only: no short selling and no leverage. A stock that did not trade on a day (a halt, or a gap in the data) keeps its order waiting.

sim replay next N moves up to N trading days and prints what happened each day. On the last day of the window, run sim replay end; you can also end early — a run of fewer than five trading days is not scored. end shows the scorecard and then the scenario’s debrief: what actually happened.

Challenges

A challenge is a set of rules and goals, played over a replay or over your live paper sessions (the bot’s sim start picks, settled by sim settle).

stockwise sim challenge list
stockwise sim challenge start steady-hands       # inside the running replay
stockwise sim challenge status
stockwise sim challenge end                      # give up, or score a finished live one

Hard rules cannot be broken by accident: an order that would break one is refused with the reason, and a hard rule broken by the market (a drawdown) ends the challenge as failed. Soft rules are recorded and cost discipline points. Position size is judged when you place the order, at the last close, and the score judges it the same way. A challenge must fit in the days left in the replay, so start a 30-day challenge at least 30 trading days before the end.

sip-discipline starts on the replay’s first day, before any order: your account begins with one month’s contribution (10,000 in the replay’s currency) and the same again arrives on the first trading day of every month. It is compared with a plain SIP that buys the benchmark with the same money on the same days — can your timing beat discipline? Returns are time-weighted, so the money you add never counts as profit.

Over live paper sessions a challenge counts settled sessions from the day you start it: the first session settled on each trading day, up to the challenge’s length. The rules are checked over the trades the bot made. Start it outside a replay, then use sim start each morning and sim settle after the close. Your return compounds each session’s intraday P&L, while the benchmark moves close to close over the same dates, overnight gaps included — a tougher comparison than in a replay.

Scores, grades and badges

A finished run gets a score from 0 to 100, from four parts:

The first two parts scale with how invested you were, reaching full weight at 30% invested on average. Sitting in cash through a crash avoids the loss, but it is not a trading decision worth points. Grades: A+ 90+, A 80+, B 70+, C 60+, D 50+, F below. The score is a pure function of the run, so the same trades always score the same.

Badges are earned once and kept in your profile:

Streaks. A disciplined run is a scored run where every buy had a stop-loss and was at most 20% of the account, and no rule was broken. The profile counts disciplined runs in a row and challenges passed in a row.

Profile and result cards

stockwise sim profile                   # badges (earned and how to earn the rest), streaks, best scores, recent runs
stockwise sim card                      # your last run as a text card, ready to paste
stockwise sim card --svg card.svg       # ...or as a 640 × 360 image
stockwise sim card --svg card.svg --text

The card shows the scenario, dates, score and grade, your return, drawdown and Sharpe ratio next to the benchmark’s, your curve against the benchmark, badges, challenges and the disclaimer. It is built from your local profile: nothing is uploaded, and there is no leaderboard.

Your own scenarios and challenges

A scenario is a TOML file in the same format as the built-ins in src/practice/scenarios/:

name = "my-2018-midcaps"
title = "The 2018 mid-cap fall"
market = "in"                  # in or us
from = "2018-01-01"
to = "2018-12-31"
benchmark = "^NSEI"
benchmark_name = "NIFTY 50"
capital = 100000
description = "Shown before and during the replay: don't give the ending away."
debrief = "Shown after `sim replay end`."

[[universe]]
symbol = "RELIANCE.NS"
sector = "Energy"

stockwise sim replay start file:my-2018-midcaps.toml

Challenges use the [[challenge]] format of src/practice/challenges.toml, with these rule kinds: max_drawdown {percent, hard}, max_position {percent, hard}, stop_loss_required {hard}, invest_each_month {percent, hard} (rules), and beat_benchmark {margin_percent}, beat_sip (needs monthly_contribution), min_exposure {percent}, min_positions {count}, min_trades {count}, drawdown_vs_benchmark {ratio} (goals). days = 0 runs until the replay ends.

stockwise sim challenge start file:my-challenges.toml   # the file's first challenge

JSON output

--json works on sim replay list|start|next|buy|sell|status|end, sim challenge list|start|status|end and sim profile. Field names are listed in commands.md. Every replay view carries the same no-future guarantee as the tables.

Files and limits

• One replay at a time, and one challenge at a time inside it (start another when it finishes). Replays use daily bars only: no intraday fills.
• Prices are Yahoo Finance daily bars, adjusted for splits but not dividends, so a replay ignores dividends. A stock missing from Yahoo for the window is left out with a note; it is not valued at zero.
• Live paper trades carry no sector, so live challenges can’t earn the sector badge.
• Practice mode is not shown in tui or the web dashboard yet.

Trading Bots

Intraday Bot

9-strategy multi-signal engine for day trading.

stockwise bot 25000 2       # ₹25K capital, 2% daily target
stockwise -m us bot 5000 1  # US market, $5K, 1% target

Strategies

Scoring

• Each strategy generates a strength score (0-100)
• Consensus bonus: +8 per additional agreeing strategy
• Volume multiplier: 1.15x if volume >1.5x average
• Regime multiplier: 1.2x if trade aligns with strong trend, 0.6x if counter-trend
• Confidence: HIGH (score >=75, 3+ strategies), MEDIUM (>=60, 2+), LOW (others)

Position Sizing (Kelly Criterion)

• Half-Kelly fraction for safety (max 25% of capital)
• 1% max risk per trade
• Never more than 30% of capital in one position
• At most 5 plans, and together they never need more than your capital: walking down the ranking, a plan that doesn’t fit in what’s left is shrunk to what does (or dropped)
• Exit level for each paper position: uses support levels when available, else ATR-based

Output

• Sector heat map (which sectors are moving)
• Market regime detection (Strong Uptrend → Strong Downtrend)
• Top 15 signals ranked by score
• The strategies behind the five strongest signals, with each one’s strength and reason (intraday shows no position sizes or price levels; the paper-trading daemon and sim still size simulated trades and show them as long or short with level 1, level 2 and an exit level)

Long-Term Scores

6-pillar scoring of the market’s stock universe with a Monte Carlo illustration. It shows data and how each score was built: no buy, sell or hold calls, no entries, stops or targets, and no allocation advice.

stockwise longterm 15000         # ₹15K/month SIP budget
stockwise -m us longterm 1000    # US market, $1K/month

6 Scoring Pillars

Moat Analysis

Stocks get Wide/Narrow/No Moat signals from these rules:

• Profit margins >25% (pricing power)
• ROE >25% (capital efficiency)
• Revenue growth >25% (market dominance)
• Market cap >$1T (scale advantage)

Monte Carlo Simulation

• 1000 simulated 5-year paths using historical volatility
• Reports: P10 (worst case), Median, P90 (best case) returns
• Uses deterministic PRNG for reproducibility

Output

• Top 12 names ranked by composite score, with each pillar’s score (a dash where the pillar had no data; n/a when under half the weight had data)
• Detailed top 3: score band, data coverage, risk level (Lower / Moderate / Higher), PEG, earnings yield, and the facts that added or took away points
• 5Y and 10Y growth at an assumed annual return set from the score (not a forecast), with dividends reinvested
• SIP arithmetic (the monthly amount that would reach ₹10L in 10 years at that rate, and what your budget compounds to)
• A simulated 5-year range: 10th percentile, median and 90th percentile

Paper Trading Simulator

Test the intraday bot without risking real money.

stockwise sim start 25000 2    # Morning: lock in trades
stockwise sim status           # During day: live P&L
stockwise sim settle           # After the close: replay the day, record results
stockwise sim history          # Performance over time

sim start only runs on a trading day before the close (the clock is IST, or ET with -m us, and knows exchange holidays), and records when each trade was entered.

How sim settle decides

Each open session is settled from its own day’s 5-minute bars, not from whatever the price is when you run the command:

1. Bars before the entry time are ignored.
2. The bars are walked with the same position manager as the daemon: book half at level 1 and move the exit level to the opening price, close the rest at level 2, trail the exit level after level 1, tighten it in the wind-down. (Levels are fixed when the paper position opens; they are simulation mechanics, not advice.)
3. Whichever of the exit level or level 2 the price reached first decides the trade. Inside a single bar the order of the high and low is unknown, so a bar that touched both counts as the exit level (conservative). Levels fill at their price; a bar that opens beyond one fills at the open.
4. Otherwise the trade exits at the open of the 15:15 IST bar (15:45 ET).

Yahoo keeps 5-minute bars for about 60 days. Older sessions fall back to hourly bars, then to the daily bar (same rules, exit at the close). Today’s session is refused until the market closes; sim settle --now settles it at the latest bar. A session whose bars can’t be fetched stays open and the command exits non-zero if nothing was settled.

What It Tracks

• Per trade: opening and closing price, whether level 2 or the exit level was reached, P&L, strategies used
• Per day: total P&L, win/loss count, how often level 2 was reached
• Cumulative: equity curve, Sharpe ratio, win streaks, day/trade win rates

Confidence Rating (after 5+ days)

Practice mode

To practise your own decisions rather than the bot’s, replay a past market day by day with the future hidden — the COVID crash, 2008, the dot-com bust — take on goal-based challenges, and get a risk-adjusted score, badges and a shareable card: stockwise sim replay start covid-crash-2020. See simulator.md.

Daemon Mode

Guide: Set up alerts and the daemon.

Persistent background workers that run the bots continuously.

Intraday Daemon

stockwise daemon intraday 25000         # NSE, ₹25K paper capital
stockwise -m us daemon intraday 5000    # NYSE hours (ET), $5K
stockwise daemon intraday 25000 --once  # one session, then exit

The daemon keeps running: after it settles a session it waits for the next trading day (skipping weekends and exchange holidays) and runs that one, so one process covers every day until you stop it with Ctrl+C or SIGTERM. Start it any time: before or during a session it picks that session up (a late start enters no new positions); after the close or on a weekend it waits for the next pre-market. Add --once to run a single session and exit with status 0 (for example from cron or a systemd timer).

Lifecycle (NSE; NYSE uses the same offsets from 09:30–16:00 ET):

9:00 AM   Pre-market scan (sectors, gaps)
9:15 AM   Enter up to 5 positions (9 strategies, Kelly sizing, ≤ capital in total)
9:30–3:15 Monitor every 60 seconds:
          - Level 1 reached → book 50%, move the exit level to the opening price
          - Level 2 reached → close fully
          - Exit level reached → close, record the loss
          - Trailing exit level updates (1.5% trail)
          - Wind-down (2 PM+): tighten the exit level to 0.5%
3:15 PM   Square off all remaining positions
3:20 PM   Settle → save to sim_history.json → AI EOD report → wait for the
          next session (with --once: exit)

The clock is the exchange’s, not your machine’s: IST (+05:30) for NSE, US Eastern with daylight saving for NYSE. Weekends and exchange holidays are closed all day; the daemon prints the reason and the next session, then sleeps until 15 minutes before it.

Risk controls:

• 1% max risk per trade, 30% max per position, total allocation ≤ capital
• 3% daily loss kill switch (closes everything; counts every realised exit, including level 2 exits)
• Max 5 concurrent positions
• Entries only in the first 15 minutes; no new entries after that
• Forced square-off 15 minutes before the close

Resilience:

• One Yahoo session is reused across ticks. A failed tick is logged and retried after 15 s, 30 s, 60 s … (capped at 5 minutes); after three failures in a row the session is rebuilt. Network blips never stop it.
• The day’s state (positions, risk manager, entries) is saved to daemon_state.json (daemon_state_us.json with -m us) in the data directory after every tick. Restarting the daemon the same day resumes it — the capital from the saved state wins.
• Ctrl+C (or SIGTERM, e.g. from systemd) squares off open positions at their last price, records the day in the simulator history, saves, and exits 0. A second Ctrl+C exits immediately; the saved state is resumed next time.
• If the daemon missed the square-off (crash, laptop asleep), it hands that day’s entries to the simulator as an open session instead of closing them at stale prices: run stockwise sim settle to settle them from the day’s 5-minute bars.
• One NSE and one NYSE daemon can run side by side; don’t start two for the same market — they would share one state file.

The daemon is paper-only: it never calls a broker order API. Results are saved to simulation history — check with stockwise sim history. With notifications configured, it also sends entries, exits, the kill switch and the end-of-day summary.

Market calendar

Holidays come from a table in src/clock.rs: the NSE equity-segment list (2026 official; 2027 provisional — only fixed-date holidays until NSE publishes its circular in December) and the NYSE calendar for 2026–2028, including 1:00 pm early closes. When the current year’s list is missing or provisional, the daemon prints a warning. Muhurat trading sessions are not traded.

Long-Term Daemon

stockwise daemon longterm

Runs 5 steps:

1. Score 30 stocks on 6 pillars + Monte Carlo and print the three highest scores
2. Check portfolio value, snapshot wealth tracker
3. Check all price alerts
4. List holdings priced below their average cost
5. Generate AI research notes via Ollama

Run daily after market close, or weekly for deep analysis.

Deep Dive

One command for everything about a single stock:

stockwise deep RELIANCE

Shows: company info, price action, valuation (P/E, PEG, P/B, EV/EBITDA), profitability, financial health, dividends, analyst ratings, 1Y chart, all technicals (RSI + gauge, SMA, MACD, Bollinger, ATR, VWAP), support/resistance, Fibonacci, risk (vol, Sharpe, drawdown, VaR), OBV trend, open gaps, insights, the 6-pillar score, and (with --ai) AI analysis.

Price and Technical Alerts

Guide: Set up alerts and the daemon walks through alerts, notifications and cron.

stockwise alert add TCS above 4200
stockwise alert add AAPL -m us below 180
stockwise alert add INFY rsi-below 30         # RSI(14) at or below 30
stockwise alert add RELIANCE cross-above-sma 200
stockwise alert add AAPL -m us breakout-high 52
stockwise alert add HDFCBANK change-below 3   # a fall of 3% or more today
stockwise alert add TCS volume-spike 2        # 2x the 20-day average volume
stockwise alert add TCS results-in 7          # results due within a week
stockwise alert watch                 # check every 60 s while markets are open
stockwise alert watch --interval 30   # every 30 s (minimum 10)
stockwise alert watch --once          # one pass over every alert, for cron

alert watch checks each alert only while its market is open — .NS/.BO symbols on the NSE clock, US tickers on the NYSE clock, crypto and FX (BTC-USD, USDINR=X) around the clock — and sleeps until the next open otherwise. Alerts are re-read every pass, so alert add in another terminal takes effect without a restart.

Technical conditions (RSI, moving-average crosses, breakouts, day change, volume spikes) are evaluated on daily bars, fetched once per symbol per check and brought up to the live price. A cross fires on the session it happens in, not on the days after. results-in reads the next results date from stockwise calendar (Yahoo, plus NSE board meetings for Indian stocks, cached for a day). Every condition is listed in commands.md.

Each trigger is announced once: an alert fires when its condition becomes true, re-arms after the condition turns false again, and fires at most once a trading day. Day-change and volume-spike alerts describe one session, so they re-arm with each new session, using the quote’s own session date. Until today’s session has traded they give no reading, so a weekend or holiday does not repeat Friday’s move; results-in re-arms once the results date has passed. That memory lives in alert_watch.json, so a restart doesn’t repeat notifications. If every configured channel fails, the trigger is not marked and the next check tries again. Network errors are retried with backoff; Ctrl+C stops it.

Notifications

alert watch and daemon intraday send to every channel you configure. All channels are opt-in, set with environment variables:

The same settings can live in the config file under [notify], named without the STOCKWISE_ prefix in lower case (telegram_chat_id = "123", smtp_host = "smtp.gmail.com"). An environment variable wins over the file. If you put a token or password there, keep the file private (chmod 600); config show and doctor warn otherwise.

stockwise notify          # which channels are configured (secrets are never shown)
stockwise notify test     # send a test message to each; exits 1 if any fails

Security: the bot token, webhook URLs and SMTP password are only sent to their own endpoint. Redirects are not followed, error messages are stripped of URLs, and notify shows only the chat id, the webhook’s host, or the SMTP server. Email uses TLS (rustls); STOCKWISE_SMTP_TLS=none with a password is refused unless the server is localhost. A failed notification is printed as a warning and never stops the daemon or the alert loop.

Telegram setup: message @BotFather → /newbot → copy the token; send your bot a message, then open https://api.telegram.org/bot<TOKEN>/getUpdates in a browser and copy chat.id.

Bot Design & Architecture

Current State vs Vision

What exists today

• On-demand scanners (intraday, longterm): scan once, show the scores, exit.
• daemon intraday: a paper-only worker on the exchange clock (IST / ET, holidays included) that enters at the open, manages positions every 60 seconds, squares off before the close and settles into the simulator history. It survives network errors, saves its state every tick (daemon_state.json), resumes after a restart, and squares off on Ctrl+C.
• daemon longterm: a one-shot post-market scan.
• alert watch: checks price alerts while their market is open.
• Notifications to Telegram, Slack, Discord, email and the desktop for alert triggers and daemon entries, exits, kill switch and end of day.

Not built: live order execution from the daemon (Phase 2), the learning loop (Phase 4), and scheduling (run the workers from cron/systemd/launchd).

Design

Two persistent background workers that run throughout the day:

┌─────────────────────────────────────────────────────┐
│  INTRADAY WORKER (9:00 AM – 3:30 PM IST)            │
│                                                      │
│  9:00  Pre-market: scan overnight gaps, sector heat  │
│  9:15  Market open: lock initial positions            │
│  9:15–10:00  Aggressive phase: momentum entries       │
│  10:00–2:00  Monitoring: trail exit levels, book level 1 │
│  2:00–3:00  Wind-down: no new entries, tighten stops  │
│  3:15  Square off: close all intraday positions       │
│  3:30  EOD: settle, record P&L, update sim history    │
│                                                      │
│  Runs every 60 seconds during market hours            │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│  LONGTERM WORKER (runs daily after market close)     │
│                                                      │
│  4:00 PM  Scan all stocks, score on 6 pillars        │
│  4:01     Run Monte Carlo on top candidates           │
│  4:02     Portfolio value, wealth snapshot            │
│  4:03     Check alerts: any triggered?                │
│  4:04     Holdings priced below their average cost    │
│  4:05     AI research notes (optional)                │
│                                                      │
│  Runs once daily, optionally weekly deep scan         │
└─────────────────────────────────────────────────────┘

Intraday Worker: Detailed Design

Lifecycle

PRE-MARKET (9:00 – 9:14)
├── Fetch sector heat (NIFTY IT, Bank, Pharma, etc.)
├── Scan for overnight gaps in all 30 stocks
├── Check global cues (US futures, SGX NIFTY)
├── Identify watchlist candidates (top 10 by score)
└── Print morning brief

MARKET OPEN (9:15 – 9:30)
├── Run 9-strategy engine on all candidates
├── Filter by confidence (HIGH/MEDIUM only)
├── Size positions via Kelly criterion
├── Lock paper positions (opening price, level 1, level 2, exit level, trailing exit level)
├── Record them in the simulator (the daemon never places orders)
└── Print the positions

MONITORING LOOP (9:30 – 3:00, every 60s)
├── Fetch live prices for all open positions
├── For each position:
│   ├── If price >= level 1: book 50%, move exit level to the opening price
│   ├── If price >= level 2: book remaining, position closed
│   ├── If price <= exit level: close, record loss
│   ├── Update trailing exit level (max of previous, price - 1.5*ATR)
│   └── Log P&L snapshot
├── Check for new signals (only in first 2 hours)
├── Print status table every 5 minutes
└── Notify when level 1, level 2 or the exit level is reached

WIND-DOWN (3:00 – 3:15)
├── No new entries
├── Tighten all trailing stops to 1x ATR
├── Book any position with >0.5% profit
└── Prepare for square-off

SQUARE OFF (3:15 – 3:20)
├── Close all remaining positions at market
├── Calculate final P&L
├── Settle simulation session
└── Generate EOD report

POST-MARKET (3:30+)
├── Save results to sim_history.json
├── Update wealth tracker
├── Generate AI EOD report
└── Print daily scorecard

State Machine

          ┌──────────┐
          │  IDLE     │ (before 9:00 or after 3:30)
          └────┬─────┘
               │ 9:00 AM
          ┌────▼─────┐
          │ PRE_SCAN  │ gaps, sectors, candidates
          └────┬─────┘
               │ 9:15 AM
          ┌────▼─────┐
          │ ENTERING  │ place orders, lock trades
          └────┬─────┘
               │ orders filled
          ┌────▼─────┐
      ┌──►│ WATCHING  │◄──── main loop (60s ticks)
      │   └────┬─────┘
      │        │ level 1 / exit level
      │   ┌────▼─────┐
      └───┤ MANAGING  │ partial exits, trail stops
          └────┬─────┘
               │ 3:15 PM
          ┌────▼─────┐
          │ CLOSING   │ square off all
          └────┬─────┘
               │ done
          ┌────▼─────┐
          │ SETTLED   │ record P&L, generate report
          └──────────┘

Data Flow

Yahoo Finance (prices) ──┐
                         ├──► Intraday Engine ──► Trade Manager ──► Angel One API
Ollama (AI insights) ────┘         │                    │
                                   │                    ▼
                              Score/Signal         Order Placed
                                   │                    │
                                   ▼                    ▼
                              sim_history.json     Real P&L

Risk Controls

Long-Term Worker: Detailed Design

Daily Run (after market close)

SCAN (4:00 PM)
├── Fetch quotes for all 30 popular stocks
├── Fetch 1Y daily charts for each
├── Score on 6 pillars (val, growth, quality, momentum, dividend, safety)
├── Run Monte Carlo (1000 sims × 5 years)
├── Detect moat rating
└── Rank by total score

PORTFOLIO CHECK (4:02 PM)
├── Fetch current holdings from portfolio.json
├── Value them in the market's currency
└── Snapshot the value in wealth_history.json (skipped when a price is missing)

ALERT CHECK (4:03 PM)
└── Check all price alerts

HOLDINGS BELOW COST (4:04 PM)
└── List holdings whose price is under their average cost

REPORT (4:05 PM)
└── Optional AI research notes via Ollama (score, data coverage, moat signals,
    risk level), printed to the terminal

Not built: weekly deep scan, saved reports, allocation or rebalance output. longterm and daemon longterm show scores and the facts behind them. They do not allocate a budget, rank names as picks, place orders or say when to act.

Score bands

The composite and each pillar use the same descriptive bands as verdict. A band describes the score; it is not an instruction.

Score 65 and above   Strong
Score 45 to 64       Moderate
Score below 45       Weak
No inputs            No data (the composite shows n/a under 50% data coverage)

SIP arithmetic

longterm compounds your monthly budget at an assumed annual return that is set from the composite score (a rule of thumb, not a forecast) and shows the monthly amount that would reach 10 lakh / 1 million in 10 years at that rate. Every instalment grows only for the time it stays invested. It places no orders and does not size a position.

Implementation Plan

Phase 1: Daemon Mode (what to build)

stockwise daemon intraday          # Run intraday worker
stockwise daemon longterm          # Run longterm daily worker
stockwise daemon --all             # Run both

Implementation (done):

• Tokio loop; the phase comes from clock::market_phase(market, now) — IST for NSE, US Eastern (with daylight saving) for NYSE, holidays closed
• Intraday: 60-second tick during market hours; one Yahoo session reused, failed ticks retried with bounded backoff (15 s → 5 min), never fatal
• State persisted to daemon_state.json (daemon_state_us.json for NYSE) after every tick and resumed on a same-day restart; a day whose square-off the daemon missed is handed to sim settle
• Ctrl+C / SIGTERM: square off at last prices, settle into the simulator history, save, exit 0
• Longterm: single run, cron-scheduled or manual
• Not built: daemon --all

Phase 2: Trade Execution (planned — not implemented)

Today the daemon is paper-only: it never sends orders to a broker. Live orders are placed only by stockwise trade buy/sell/limit, one at a time, after a preview and confirmation.

Signal Generated ──► Confirmation Check ──► Angel One API
                          │
                     Risk check:
                     - Within daily loss limit?
                     - Position count < 5?
                     - Not in wind-down period?
                     - Capital available?

• Auto-execute: stockwise daemon intraday --auto-trade
• Paper mode (default): stockwise daemon intraday --paper
• Requires Angel One configured

Phase 3: Notifications (done)

src/notify.rs sends to Telegram (bot API), Slack and Discord (incoming webhooks), email (SMTP via lettre + rustls) and the desktop (notify-rust, behind the desktop-notify feature). Channels are configured with environment variables; stockwise notify test checks them. The daemon sends openings, closings (level 1, level 2, exit level, square-off), the kill switch and the end-of-day summary; alert watch sends each trigger once. See bots.md.

Phase 4: Learning Loop

After 30+ simulation days:
├── Analyze which strategies win most
├── Adjust strategy weights automatically
├── Identify which market regimes favor which strategies
├── Backtest adjusted weights on historical data
└── If improvement > 5%: adopt new weights

File Structure

src/
  clock.rs            Exchange clock: IST / US Eastern, holiday tables, phases
  daemon.rs           Positions, risk manager, daemon state + events, shutdown
  commands/worker.rs  The intraday and long-term loops
  commands/alerting.rs  `alert watch` and `notify`
  notify.rs           Telegram, Slack, Discord, email, desktop
  simulator.rs        Sessions, stats, and the bar replay behind `sim settle`

Planned: scheduler.rs (cron-like scheduling for the long-term worker).

Market Hours Reference

Holidays: NSE 2026 (official), 2027 (provisional), NYSE 2026–2028. To add a year, see the module docs at the top of src/clock.rs.

FAQ

Q: Should the bot trade automatically? A: Not yet. Start with paper trading (sim commands). Once you have 20+ days of HIGH confidence rating from sim history, then consider a future auto-trade mode (not built yet — today the daemon only paper-trades).

Q: How much capital should I start with? A: Paper trade with the same amount you’d use for real. ₹25,000–₹50,000 is a good starting point for intraday. For long-term SIP, whatever your monthly budget is.

Q: What if the bot loses money? A: The 1% per-trade risk limit means max loss per trade is ₹250 on ₹25K capital. Daily loss limit of 3% = ₹750 max. The kill switch stops all trading if this is breached.

Q: Can I run both workers simultaneously? A: Yes, they’re independent. Intraday worker runs during market hours, longterm worker runs after close. No conflict.

Brokers: live trading and holdings import

StockWise can read your holdings and place orders through a broker’s API, and import holdings from broker exports and CAS statements.

Experimental — untested against a live account. The Zerodha, Upstox, Dhan and Fyers integrations, and stop-loss / GTT orders on Angel One, were built from each broker’s public API documentation and tested against recorded and handwritten responses on a local mock server. Nobody has run them against a real account yet. Until you opt in, they only read (holdings, positions, orders) and preview (--dry-run); see Turning on live orders. Reports from real accounts are very welcome: run stockwise trade selftest and paste its report — see Help verify a broker.

Pick the broker per command with --broker, or set a default with STOCKWISE_BROKER=zerodha. Without either, trade uses Angel One, as before.

stockwise trade holdings --broker zerodha
STOCKWISE_BROKER=dhan stockwise trade orders

Order safety

Every order — any broker, any order type, GTT included — goes through the same steps:

1. Exact instrument. The symbol must match one NSE cash-equity (EQ series) instrument in the broker’s own instrument list: Angel One’s searchScrip, Kite’s instrument dump, Upstox’s NSE instrument file, Dhan’s NSE_EQ scrip master, Fyers’ NSE_CM symbol master. Partial names, other series (-BE), ETFs with a similar name, and F&O contracts never match; two matches are refused.
2. Price checks. Prices must be positive with at most 2 decimals (never silently rounded). For stop-loss orders the trigger must sit on the right side of the market (above it for a BUY, below it for a SELL — otherwise it would fire at once), and the limit must be at or beyond the trigger in the order’s direction. A limit more than 20% away from its trigger is treated as a typo. A GTT trigger must be at least 0.25% away from the last price, and a stop GTT (SELL below the market, BUY above it) needs a limit that is marketable at the trigger. Stop and GTT orders need a last price; if it can’t be fetched the order is refused. Orders go to NSE only: a .BO symbol is refused rather than traded on NSE.
3. Preview. Instrument and broker token, side, quantity, order type, product (delivery / CNC), last price, estimated value.
4. max_order_value. If set in the broker’s config file, any order whose estimated value is higher is refused (also on --dry-run). With a cap set, an order whose value can’t be estimated (a MARKET order without a last price) is refused too. Without a cap the preview says so, and --yes (step 7) is refused.
5. --dry-run stops here: nothing is sent.
6. Opt-in for experimental paths ("enable_orders": true, below).
7. Typed confirmation. You type yes. Without a terminal (scripts, cron) the order is refused unless you pass --yes. --yes also needs max_order_value in the broker’s config file, because it removes the last guard against a wrong quantity; without a cap, the order is refused before StockWise logs in to the broker. --dry-run is not affected.

If the network fails while an order is in flight, StockWise says the order state is unknown — check the broker app or stockwise trade orders before retrying, so you don’t place it twice. Cancelling a GTT goes through the same preview, opt-in and confirmation.

The paper-trading daemon never sends broker orders.

Order types

stockwise trade buy RELIANCE 10                              # MARKET
stockwise trade buy RELIANCE 10 --limit 1300                 # LIMIT
stockwise trade limit RELIANCE 10 1300                       # LIMIT buy (0.3 form)
stockwise trade sell RELIANCE 10 --trigger 1250              # SL-M: market sell once 1250 trades
stockwise trade sell RELIANCE 10 --trigger 1250 --limit 1245 # SL: limit sell at 1245 once 1250 trades
stockwise trade buy RELIANCE 10 --trigger 1400 --limit 1405  # SL buy (breakout entry)

All orders are delivery (CNC) on NSE with DAY validity. MARKET and SL-M orders carry the broker’s automatic market protection where the broker requires it (Kite, Upstox).

GTT (good till triggered)

A single-leg GTT places a LIMIT order when the trigger trades; it stays active for up to a year.

stockwise trade gtt sell TCS 5 --trigger 3400 --limit 3390 --broker zerodha   # stop-loss below the market
stockwise trade gtt sell TCS 5 --trigger 4200 --limit 4190                    # target above it
stockwise trade gtt buy INFY 10 --trigger 1350 --limit 1355                   # buy the dip
stockwise trade gtt list
stockwise trade gtt cancel 112127

Two-leg (OCO) GTTs are not supported yet. Upstox GTT rules have no limit price, so StockWise can’t express “LIMIT at this price once triggered” there and refuses GTTs for Upstox.

Syncing trades and GTTs into the portfolio

trade sync reads the broker’s trade book (executed fills) and turns delivery trades into the lot-based portfolio: a buy becomes a lot with its fill date, average fill price and order id; a sell comes out of the oldest lots (FIFO) and is recorded as a realized sale for tax. It previews by default and writes only with --apply.

stockwise trade sync --broker zerodha                 # preview: what would change
stockwise trade sync --broker zerodha --apply         # write it
stockwise trade sync --broker dhan --since 2026-10-01 --apply
stockwise trade sync --apply --notify --json          # for cron: JSON on stdout, notify on changes

• Read-only at the broker. Sync and gtt list run on a session that refuses any order, GTT or cancel request.
• Idempotent. Every fill applied is remembered (broker, order and trade id) in the portfolio file, and lots and sales keep the broker order id. Running sync twice, or after a partial fill completes, never counts a fill twice: the later part of a partly filled order becomes its own lot.
• Delivery equity only. Intraday (MIS / INTRADAY), margin (MTF), F&O and commodity fills are listed as skipped, not turned into lots. NSE and BSE fills of a stock you already hold go to that holding; a new holding takes the exchange of its fill (.NS or .BO).
• Sells need the shares. A sell larger than the shares the portfolio held on that date is left out (and not marked as synced) until you add the missing lots, e.g. with portfolio add SYMBOL QTY PRICE --date. Sells of a stock whose lots still wait for a split or bonus are held back too — run portfolio actions SYMBOL --apply first.
• Dates. Fills are dated by the broker’s timestamp. Angel One gives a time only, so its fills are dated with the last NSE session (today once the market has opened, else the previous trading day).
• Today only, mostly. Angel One, Zerodha, Upstox and Fyers return today’s trades only — run sync at the end of each trading day (or from cron). Dhan keeps a trade history, so --since fetches older fills there (up to 50 pages; history rows get their NSE symbol from Dhan’s scrip master). For older history on other brokers, stockwise import a tradebook export.
• Open orders (pending, partly filled) are listed; their fills sync once they appear in the trade book.
• Quantity check. For each symbol it touched, sync compares the portfolio’s quantity with the broker’s holdings list. Today’s buys reach that list only after settlement (T+1), so a same-day gap is normal; a lasting gap means lots are missing or doubled. Use either trade sync (dated lots from fills) or trade holdings (quantities only, estimated dates) as your source for a broker — trade holdings matches quantities, so after a sync it only changes something when the two disagree.

GTT status changes

trade gtt list remembers what it saw (in gtt_seen_<broker>.json in the data directory) and shows what changed since the last look: GTTs that triggered, were cancelled or expired, or no longer appear (brokers drop old ones from the list). --notify sends those changes to your notification channels (Telegram, Slack, Discord, email — see stockwise notify status); only real state changes and vanished GTTs are sent, not a status spelling change such as Angel One’s NEW → ACTIVE. If every channel fails, the record is not updated, so the changes are reported again next time. trade sync --apply updates the same record and includes the changes; trade sync --apply --notify notifies about them and about synced orders.

stockwise trade gtt list --broker zerodha --notify
stockwise trade gtt list --json     # {broker, gtts, changes, first_check, last_checked}

Turning on live orders

Read-only commands work as soon as a broker is configured. To send real orders through an experimental path, first compare a --dry-run preview with what the broker app shows, then add to that broker’s config file:

"enable_orders": true

This applies to every order on Zerodha, Upstox, Dhan and Fyers, and to SL, SL-M and GTT orders on Angel One. Angel One MARKET and LIMIT orders work as in 0.3 without it.

Most Indian brokers now accept API orders only from a static IP registered with your app (Kite, Upstox, Dhan, Fyers and Angel One since April 2026). Reads work from anywhere.

Credentials and the OS keyring

stockwise trade config --broker <name> creates <name>_config.json in your data directory (the path is printed; stockwise doctor shows it too) with owner-only permissions (0600 on Unix). Fill in the placeholders and run the command again.

On the next trade command run in a terminal (or trade config again), secrets in that file — passwords, TOTP secrets, API secrets, access tokens — move into the OS keyring when one is available (macOS Keychain, Windows Credential Manager, the Secret Service on Linux desktops), and the file is rewritten without them. It keeps the non-secret settings plus "secret_store": "keyring" and the keyring entry name. Each data directory (STOCKWISE_HOME) gets its own keyring entry.

• stockwise trade config --keyring moves them now and says why if it can’t.
• Scripts and cron jobs (no terminal) never move secrets themselves; after a move they read them from the keyring, so on a machine where the keyring is locked when cron runs, keep STOCKWISE_KEYRING=off.
• With no keyring (headless Linux, containers, CI) the secrets stay in the owner-only file. Set STOCKWISE_KEYRING=off to always use the file.
• To change a secret later, put the new value in the file; it moves into the keyring again on the next command.
• stockwise doctor shows, per broker, where its secrets live.
• On macOS a rebuilt or upgraded binary may trigger a Keychain prompt the first time it reads an entry; choose “Always Allow”. Unattended runs right after an upgrade may wait for that prompt.

Never pass credentials as command-line arguments — they end up in your shell history. StockWise never prints or logs them, and sends them only to the broker’s own API.

Common optional settings in every broker config: "max_order_value": 50000 and "enable_orders": true.

Angel One

1. Create an account at angelone.in and an app at smartapi.angelone.in; note its API key.
2. Enable TOTP on your account and note the base32 secret.
3. stockwise trade config, then fill in:

{
  "api_key": "YOUR_API_KEY",
  "client_id": "YOUR_CLIENT_ID",
  "password": "YOUR_PASSWORD_OR_PIN",
  "totp_secret": "YOUR_TOTP_SECRET",
  "max_order_value": 50000
}

Angel One logs in with your PIN and a TOTP generated locally (built-in HMAC-SHA1) on every command, so there is no trade login step. Existing angel_config.json files keep working; their secrets move into the keyring on first use.

Zerodha Kite (experimental)

1. Create a Kite Connect app at developers.kite.trade (a paid Kite Connect plan); note the API key and API secret. Set the redirect URL to anything you can copy from the address bar, e.g. http://127.0.0.1/.
2. stockwise trade config --broker zerodha and fill in api_key and api_secret.
3. Every trading day: stockwise trade login --broker zerodha. It prints the Kite login URL; log in in your browser, then paste the address the browser was redirected to (it contains request_token=…). StockWise exchanges it for an access token (checksum = sha256(api_key + request_token + api_secret)) and saves it. Kite sessions end at 06:00 IST.

Holdings include T1 shares. Selling holdings without DDPI/POA may need a CDSL TPIN authorisation in the Kite app first (Kite answers HTTP 428).

Upstox (experimental)

1. Create an app at account.upstox.com/developer/apps; note the API key and API secret and set a redirect URL such as http://127.0.0.1/.
2. stockwise trade config --broker upstox; fill in api_key, api_secret and the same redirect_uri.
3. Every trading day: stockwise trade login --broker upstox — log in in the browser, paste the redirect address (it contains code=…). Sessions end at 03:30 IST. Orders use the v3 endpoint on api-hft.upstox.com.

Dhan (experimental)

1. On web.dhan.co open My Profile → Access DhanHQ APIs and generate an access token (valid 24 hours).
2. stockwise trade config --broker dhan; put your Dhan client id in api_key.
3. stockwise trade login --broker dhan and paste the token (input is hidden). It is checked against your Dhan profile and saved (in the keyring when available). Repeat when it expires.

GTT orders on Dhan are single “Forever Orders”.

Fyers (experimental)

1. Create an app at myapi.fyers.in/dashboard; note the App ID (e.g. XXXX-100) and Secret ID, and set a redirect URL such as http://127.0.0.1/. Only App IDs ending in -200 can place orders.
2. stockwise trade config --broker fyers; put the App ID in api_key, the Secret ID in api_secret, and the redirect_uri.
3. Every trading day: stockwise trade login --broker fyers — log in in the browser and paste the redirect address (it contains auth_code=…). StockWise validates it with appIdHash = sha256(app_id:secret). Sessions end around 06:30 IST.

Commands

stockwise trade setup [--broker B]          # How to connect
stockwise trade config [--broker B] [--keyring]
stockwise trade login --broker B            # Zerodha, Upstox, Fyers, Dhan
stockwise trade holdings                    # Live holdings (synced into `portfolio`)
stockwise trade positions                   # Open positions
stockwise trade orders                      # Today's order book
stockwise trade buy RELIANCE 10 --dry-run   # Resolve + preview, send nothing
stockwise trade sell TCS 5 --trigger 3400   # SL-M sell
stockwise trade gtt list [--notify]         # GTT orders + status changes since the last look
stockwise trade sync [--since DATE] [--apply]          # Fills into the portfolio (preview first)
stockwise trade selftest [--redact-amounts] [--json]   # Read-only check; report for a GitHub issue

Help verify a broker

Zerodha, Upstox, Dhan and Fyers — and stop-loss / GTT orders on Angel One — were built from public API docs and have never been run against a real account by the maintainers. If you have an account with one of them, you can help take the “experimental” label off in about five minutes, without placing an order.

1. Install the latest StockWise and set the broker up as described above (trade setup, trade config, trade login).

2. Run the self-test:

   stockwise trade selftest --broker zerodha
   stockwise trade selftest --broker zerodha --redact-amounts   # also hide prices
   stockwise trade selftest --broker zerodha --json             # machine-readable
   

   It is strictly read-only. It logs in (or loads today’s session), reads the profile, holdings, positions, order book, trade book and GTT list, resolves RELIANCE, TCS and NIFTYBEES (the Nifty 50 ETF) exactly, runs a 1-share LIMIT buy 5% below the market through every order check and stops before sending (like --dry-run), and compares the field names of each response with the documented ones. The session it uses refuses any order, GTT or cancel in code, and the self-test never calls those methods.

3. Read the report, then paste it into a broker test report. It contains no credentials, tokens, names, e-mail addresses or holdings symbols; the account id is cut to its last two characters, and long numbers in error messages are masked. Field names, row counts, statuses and instrument tokens stay, as do the dry-run price and value unless you pass --redact-amounts. The command exits with status 1 if a check failed.

4. Optional, and only if you want to: place one small order yourself — say a 1-share LIMIT buy of a liquid stock below the market, which you can cancel — after adding "enable_orders": true to the broker’s config. Check it in the broker’s app, run trade orders and trade sync, and say in the report what happened. Nobody will ask you to place an order; this is the step that proves the write path.