pair-trading — Claude Code skill for NSE stock pairs
The pair-trading Claude Code skill tests NSE stock pairs for cointegration and measures their spread. It responds to requests for hedge ratios, z-scores, or a pair-trade plan.
MIT ★ 69 updated 2026-11-13
/plugin marketplace add Shubhamkumartrichy/claude-trading-skills-india
/plugin install india-trading-skills@india-trading-skillsWhat pair-trading does
The skill runs scripts/pairs.py to test two stocks, estimate their hedge ratio and half-life, and calculate the spread’s current z-score. Its screen command checks same-sector pairs; signal lists historical trades and their hit rate. That hit rate is in-sample: the test and trade results use the same data, and trading costs are excluded.
The plan command estimates Indian execution details, including whole futures lots, hedge mismatch, margin, charges, and rollover dates. Supply price CSVs with dates and closing prices, or use yfinance to fetch data from Yahoo with pip install yfinance. Run the script with python3. Multi-day short positions in India use stock futures; cash-market shorts must be closed on the same day.
What it helps with
- test two NSE stocks for cointegration
- screen for pairs within a sector
- measure a spread’s z-score and hedge ratio
- estimate futures lots, margin, and rollover dates
Example prompts for the agent
- Test whether HDFCBANK and ICICIBANK are cointegrated.
- Find pairs in the banking sector using
members.csv. - Plan a BPCL–HPCL trade using the data in
stocks/.
How to install pair-trading
1Plugin marketplace
/plugin marketplace add Shubhamkumartrichy/claude-trading-skills-india/plugin install india-trading-skills@india-trading-skillsThis installs the whole india-trading-skills plugin with all its skills
2Skills CLI (Vercel)
npx skills add Shubhamkumartrichy/claude-trading-skills-india --skill pair-trading -a claude-code3Manually: put the files in place
~/.claude/skills/pair-trading/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pair-trading/
1Skills CLI (Vercel)
npx skills add Shubhamkumartrichy/claude-trading-skills-india --skill pair-trading -a codex2Manually: put the files in place
.agents/skills/pair-trading/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Shubhamkumartrichy/claude-trading-skills-india --skill pair-trading -a cursor2Manually: put the files in place
.cursor/skills/pair-trading/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Shubhamkumartrichy/claude-trading-skills-india skills/pair-trading2Manually: put the files in place
.github/skills/pair-trading/SKILL.md1Skills CLI (Vercel)
npx skills add Shubhamkumartrichy/claude-trading-skills-india --skill pair-trading -a gemini-cli2Platform CLI
gemini skills install https://github.com/Shubhamkumartrichy/claude-trading-skills-india --path skills/pair-tradingManually: put the files in place
.devin/skills/pair-trading/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pair-trading
How do I install pair-trading in Claude Code?
Run /plugin marketplace add Shubhamkumartrichy/claude-trading-skills-india, then run /plugin install india-trading-skills@india-trading-skills.
What does pair-trading do?
It tests NSE stock pairs for cointegration, calculates spread statistics and historical signals, and estimates futures trade parameters for Indian execution.
What does pair-trading need to run?
It needs Python 3 and price data in CSV files with dates and closing prices. To fetch prices from Yahoo, install yfinance with pip install yfinance.
Source text
SKILL.md · MIT
---
name: pair-trading
description: |
Statistical pair trading (market-neutral long/short) for NSE stocks. pairs.py tests whether two
stocks are cointegrated (Engle-Granger with an ADF on residuals, judged against MacKinnon's
cointegration critical values), estimates the hedge ratio, half-life and current spread z-score,
screens every same-sector pair with a Bonferroni caution, lists in-sample z-score trades with a
hit rate, and plans Indian execution: stock futures in whole lots, residual hedge mismatch,
margin, charges, last-Tuesday rollover, F&O ban and lot-size revisions. Stdlib only; offline CSVs.
Use when the user asks: "is HDFCBANK/ICICIBANK a good pair", "are TCS and INFY cointegrated",
"find pairs in the bank/IT sector", "what is the z-score of the BPCL-HPCL spread", "pair trade
entry and exit", "hedge ratio between two stocks", "how many lots for a pair trade", "how do I
short the other leg in India", or wants a market-neutral or relative-value trade.
---
# Pair Trading (NSE)
Two stocks that share the same economics (two private banks, two oil marketing companies) can
drift apart for weeks, then close the gap. A pair trade is long the cheap one and short the rich
one, sized so the market move cancels out. This works only if the gap is statistically
mean-reverting (cointegrated). A high correlation is not enough.
## 1. Run it
```bash
python3 scripts/pairs.py test HDFCBANK ICICIBANK --csv-dir stocks/ # one pair, full statistics
python3 scripts/pairs.py screen --members members.csv --csv-dir stocks/ # all same-sector pairs
python3 scripts/pairs.py signal BPCL HPCL --csv-dir stocks/ --exit 0.5 # rules + in-sample trades
python3 scripts/pairs.py plan BPCL HPCL --csv-dir stocks/ --lots-csv fo_mktlots.csv \
--ban-list fo_secban.csv --margin-a 120000 --margin-b 110000 # India execution
```
Without `--csv-dir`, prices come from Yahoo (`pip install yfinance`). Create offline CSVs with
`../technical-analysis/scripts/ta.py fetch --symbol TCS --out stocks/TCS.csv`. Only a date and a
close column are needed; a volume column turns on the liquidity filter. Use split and bonus-adjusted
closes. `--members` is a `symbol,sector` CSV. Common options: `--lookback 500` sessions (0 = all),
`--end YYYY-MM-DD` (re-test an earlier window), `--window 60` (z-score), `--entry 2 --exit 0
--stop 3.5`, `--adf-lag N` or `--max-lag N`, `--splits 3`, `--max-half-life 40`, `--json`.
Screen adds `--min-bars 250 --min-turnover 10` (₹ crore a day) `--min-corr 0.5 --top 20`.
## 2. What it computes
| Statistic | How |
|---|---|
| Correlation | Pearson correlation of daily log returns on common dates |
| Hedge ratio β | OLS of ln A on ln B. Hold ₹β of B against each ₹1 of A. Also reverse OLS and total least squares |
| Cointegration | Engle-Granger: ADF (no constant) on the OLS residuals, lag by AIC (Schwert maximum) or fixed |
| Critical values | MacKinnon (2010) Table 2, N = 2 with constant: ≈ −3.90 / −3.34 / −3.04 (1/5/10%) plus a T-adjustment. These are stricter than plain Dickey-Fuller values (≈ −2.86 at 5%) because β was fitted |
| p-value | MacKinnon (1994) asymptotic surface. Use it for ranking; the critical values decide |
| Half-life | AR(1) on the spread: s_t = c + φ·s_{t−1}; half-life = ln 0.5 / ln φ sessions |
| z-score | (spread − 60-session mean) / 60-session sd |
| Stability | β in 3 consecutive sub-periods; drift ≤ 25% of β = stable, > 50% = unstable |
Both regression directions are tested. A pair counts only if both reject the unit root.
## 3. Reading the result
- **Candidate:** rejected at 5% or better both ways, half-life 1–40 sessions (`--max-half-life`;
3–20 fits a monthly futures cycle best) and β stable. Then look at the z-score.
- **Half-life sets the trade.** A 5-session half-life suits a 1–3 week trade inside one futures
month. A 40-session half-life means several rollovers and more charges for the same reversion.
- **z ≥ +2:** A is rich against B, so short the spread (sell A, buy B). **z ≤ −2:** long the spread.
**|z| beyond 3.5:** do not add. The relationship may be breaking, often because of news.
- **High correlation without cointegration** (common in a sector rally) means the stocks move
together day to day, but the gap can trend for months. Do not trade it as mean reversion.
## 4. Signals (in-sample)
`signal` enters at |z| ≥ 2 once |z| has reset inside the band. It exits when z returns to 0 (or
±0.5 with `--exit 0.5`), stops at |z| ≥ 3.5, and time-stops after 2× the half-life
(`--max-hold`, `--time-stop-mult`). Each trade is returned as % of gross notional. **The trade list
is in-sample:** β, the test and the half-life all come from the same data, so the hit rate is an
optimistic upper bound and excludes costs. Check out of sample: run `test` with `--end` six
months back, then see whether the pair still holds on the newer data.
## 5. Executing in India (`plan`)
- **The short leg.** Cash-market shorts must be covered the same day. A short left undelivered
goes to the exchange auction and pays a close-out penalty. Multi-day pairs therefore use **stock
futures**: both legs (default), or `--legs cash-long` to buy the long leg for delivery and short
the other leg in futures. SLB (stock lending) exists but is thin.
- **Whole lots.** A stock-futures lot is several lakh rupees, so β rarely maps to whole lots.
`plan` rounds the B leg, reports the residual mismatch in % and ₹, and lists the lot combinations
with the tightest hedge. With `--legs cash-long`, the delivery leg is sized in shares.
- **Lot sizes:** `--lot-a/--lot-b`, or `--lots-csv` with NSE's `fo_mktlots.csv` (one column per
contract month). NSE revises lot sizes periodically, and corporate actions adjust them. If the
file shows a different size in a later month, the plan flags it: re-size the hedge when you roll.
- **Margin:** `--margin-a/--margin-b` (₹ per lot from your broker), otherwise `--margin-pct 25` of
contract value per leg. Margin is summed leg by leg. A long/short across two different stocks is
not a recognised spread, so do not count on a hedge margin benefit. Futures are marked to market
daily, so keep a buffer.
- **Charges** come from `../trading-costs/scripts/charges.py` (futures STT 0.05% on the sell side
since Apr 2026). The plan counts one round trip per leg plus one per roll, and futures carry (the
long leg pays it, the short earns it).
- **Rollover:** stock futures expire on the last Tuesday of the month, or the previous trading day
if that is a holiday (from `../fno-options-analysis/scripts/options.py`). They are physically
settled. The plan lists roll-by dates within the expected hold (2× half-life). Near expiry, it
switches to the next month.
- **F&O ban:** a stock enters the ban when OI crosses 95% of MWPL, and stays until it falls below
80%. In a ban you can only reduce, so you cannot open the pair or roll the leg. Pass
`--ban-list` (NSE `fo_secban.csv`), `--banned SYM`, or `--mwpl-a/--mwpl-b` (%). See
`indian-market-structure`.
## 6. Classic Indian pairs to test (not recommendations)
HDFCBANK/ICICIBANK, KOTAKBANK/AXISBANK, SBIN/BANKBARODA, TCS/INFY, HCLTECH/WIPRO, BPCL/HPCL
(IOC as a third), ULTRACEMCO/SHREECEM, TATASTEEL/JSWSTEEL. They share sector, regulation and
macro drivers. That makes them worth testing, not cointegrated by default. Re-test every quarter.
## 7. Pitfalls
- **Structural breaks:** mergers and demergers end relationships. HDFC Ltd merged into HDFC Bank
in July 2023, which ended the classic HDFC/HDFCBANK pair. A demerger (Jio Financial out of
Reliance, 2023) leaves a price gap in unadjusted data. Results, management changes and
regulatory actions can break a pair for good. A stop is for that case, not for noise.
- **Corporate actions:** use adjusted closes for splits and bonuses. A large special dividend shows
up as a spread jump on the ex-date.
- **Look-ahead:** in-sample signals use tomorrow's β today. Expect worse results live.
- **Multiple testing:** 10 bank stocks give 45 pairs. At 5%, about 2 will pass by chance. Apply a
Bonferroni-style bar (0.05 / 45 ≈ 0.001), which `screen` reports, and confirm on a later window.
- **Short samples:** under about 250 sessions, the test has little power and β is noisy.
- **Results season:** a quarterly result on one leg alone can blow through the stop. Know both dates.
## Related skills
Size the risk-to-stop rupee figure with `position-sizing`; compare broker costs in `trading-costs`;
ban and margin rules in `indian-market-structure`; expiries in `fno-options-analysis`; sector
backdrop in `sector-rotation`.
## Output
```
Pair A / B: N sessions [from → to] | corr r | β (OLS / TLS) | EG t = x vs 5% crit y → reject? p≈
Half-life H sessions | z now Z → zone | β stability: stable/drifting/unstable | verdict
Signal (in-sample): trades n, hit rate h%, avg r% | now: flat / open / signal
Plan: SELL A fut n lots / BUY B fut m lots | mismatch ±x% | margin ₹ | charges ₹ | roll by date
Risks: F&O ban, lot revision, results dates, structural break
```
_Educational analysis, not investment advice._
© Shubham Kumar · MIT · Shubhamkumartrichy/claude-trading-skills-india