Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add Shubhamkumartrichy/claude-trading-skills-india
/plugin install india-trading-skills@india-trading-skills
Open on GitHub

What 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-skills

This 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-code

3Manually: put the files in place

~/.claude/skills/pair-trading/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pair-trading/

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

Similar skills

All skills for Finance and business →

From the same set36

The whole set →
event-calendar The event-calendar Claude Code skill tracks events that can affect Indian markets. It responds to questions about expiries, RBI meetings, economic releases, and event risk over a trade window. CX Codex +1 ★ 69repo stars thesis-tracker The thesis-tracker Claude Code skill records Indian stock and F&O ideas as testable trade theses. Ask it to log an idea, check open positions, or review a closed trade. CX Codex +1 ★ 69repo stars sector-rotation The sector-rotation Claude Code skill compares NSE sectors with the NIFTY 50 using returns and relative strength. It runs for questions about sector leadership, rotation, and shifts between cyclical and defensive groups. CX Codex +1 ★ 69repo stars market-breadth This Claude Code skill measures how many NSE and BSE stocks are moving with an index. It runs for questions about market breadth, advances versus declines, or midcap participation. CX Codex +1 ★ 69repo stars exhaustion-reversal exhaustion-reversal is a Claude Code skill that scores fading NSE/BSE stock moves and maps entry or exit plans. It activates for questions about rallies, reversals, or news reactions. CX Codex +1 ★ 69repo stars macro-regime The macro-regime Claude Code skill classifies the structural regime of Indian equities from monthly market and macro data. It runs for questions about breadth, rates, the rupee, or crude. CX Codex +1 ★ 69repo stars market-valuation The market-valuation Claude Code skill measures valuation and speculative heat in Indian equities using NSE index history and other market figures. It activates for questions about NIFTY valuations, IPO activity or a possible bubble. CX Codex +1 ★ 69repo stars fii-dii-flows The fii-dii-flows Claude Code skill reads Indian equity flow data for FII/FPI and DII from downloaded CSVs. It responds to requests about institutional selling, futures positions, holdings changes, and stock deals. CX Codex +1 ★ 69repo stars

Project sponsors

Companies that keep this analytics open