leftcurve

Thin async IQFeed client for downloading historical futures data. Fills gaps in IB's limited history for expired contracts.

Installation

uv sync

Usage

Test connection

leftcurve test-connection

Download individual contracts

leftcurve download @ESH25 @ESM25 --days 500

Download contract chain

leftcurve chain ES --years 5

Build continuous contract (download + construct)

leftcurve build ES --years 5 --adjust none --roll-window 2

Build from cached data

leftcurve continuous ES --adjust difference

Symbol Translation

Use familiar Globex/CME symbols - leftcurve automatically translates to IQFeed format for API calls while preserving your symbols for file storage.

You Type	IQFeed API	Files Saved As
leftcurve build ZB	@USH25	data/ZB/ZBH25_daily.csv
leftcurve build EUR	@EUH25	data/EUR/EURH25_daily.csv
leftcurve download @ZBH26	@USH26	data/ZB/ZBH26_daily.csv

Symbol Mappings

Globex/CME	IQFeed	Product
ZB	US	30-Year Treasury Bond
ZN	TY	10-Year Treasury Note
ZF	FV	5-Year Treasury Note
ZT	TU	2-Year Treasury Note
EUR, 6E	EU	Euro FX
JPY, 6J	JY	Japanese Yen
GBP, 6B	BP	British Pound
AUD, 6A	AD	Australian Dollar
CAD, 6C	CD	Canadian Dollar
CHF, 6S	SF	Swiss Franc
ZC	C	Corn
ZS	S	Soybeans
ZW	W	Wheat
ZM	SM	Soybean Meal
ZL	BO	Soybean Oil
GC	QGC	Gold
SI	QSI	Silver
MGC	QMGC	Micro Gold

Most symbols (ES, NQ, CL, UB, NKD, MBT, etc.) are identical and pass through unchanged.

Output

data/ES/
├── ESH24_daily.csv          # Individual contracts
├── ESM24_daily.csv
├── ...
├── ES_continuous_unadj.csv  # Continuous contract
└── ES_rolls.csv             # Roll metadata

Continuous contract columns

• date, open, high, low, close, volume, open_interest
• contract: Source contract symbol
• roll_window: 0=normal, negative=before roll, positive=after roll

Roll metadata columns

• roll_date: Date of OI crossover
• from_contract, to_contract: Contract transition
• from_oi, to_oi: Open interest at crossover
• price_gap: Close price difference
• ratio: Close price ratio

Price Adjustment Methods

• none: Raw prices with gaps (default, best for volume analysis)
• difference: Back-adjusted by constant (preserves dollar moves)
• ratio: Back-adjusted by ratio (preserves percentage moves)

Roll Detection

Rolls detected via open interest crossover: when next contract's OI exceeds front contract's OI.

Use roll_window != 0 to exclude roll periods from trading signals.

Supported Products

Category	Symbols
Equity indices	ES, NQ, RTY, YM
Treasuries	ZB, ZN, ZF, ZT
Energy	CL, NG, RB, HO
Metals	GC, SI, HG
Currencies	EUR, JPY, GBP, AUD, CAD, CHF (or BP, EU, JY, AD, CD, SF)
Grains	ZC, ZS, ZW, ZM, ZL
Softs	SB, KC, CT, CC, OJ
Livestock	LE, HE

Symbol lookup: https://ws1.dtn.com/IQ/Search/

Configuration

Environment variables (or .envrc):

• IQFEED_PRODUCT_ID: Your IQFeed developer product ID (required for IQConnect)
• IQFEED_HOST: IQFeed host (default: 127.0.0.1)
• IQFEED_LOOKUP_PORT: Lookup port (default: 9100)
• IQFEED_LEVEL1_PORT: Level 1 port (default: 5009)

Requirements

• IQFeed subscription with futures data
• IQConnect running and authenticated

License

MIT License - see LICENSE for details.

---