Source: offshore-sleeve/research/usd-data-and-futu-poc-v0.md
Last modified: 2026-05-17 10:05:05 · 9,201 bytes

Offshore Sleeve USD Data Source + Futu OpenAPI PoC v0

Scope

RayDario locked the offshore sleeve as a single USD/HKD sleeve. For v0:

- Do Task #4 offshore all-weather.

- Do Task #5 US leader stocks using original Minervini.

- Defer offshore Task #6 sector ETF rotation to v1.

- Do not do offshore convertible bonds.

- Do not apply Task #10 timing to offshore sleeve.

- HKD money-market fund is converted into USD inside offshore sleeve, with FX cost tracked.

This note covers only engineering/data feasibility and PoC design. It does not place real trades.

Futu OpenAPI Findings

Official documentation confirms:

- OpenAPI has OpenD gateway + SDKs for Python, C#, Java, C++, JavaScript, and proto.

- Python SDK install path is pip install futu-api.

- Quote context: OpenQuoteContext(host='127.0.0.1', port=11111).

- Trade context: OpenSecTradeContext(host='127.0.0.1', port=11111).

- Paper trading is available via TrdEnv.SIMULATE.

- US trading account discovery should use OpenSecTradeContext(filter_trdmarket=TrdMarket.US) and get_acc_list().

- Historical daily K-line API: request_history_kline(code, start, end, ktype=KLType.K_DAY, autype=AuType.QFQ, max_count=1000, page_req_key=...).

- Daily historical K-line is supported for the last 20 years; intraday 60-minute and below is restricted to last 8 years.

- Request limit for historical K-line first-page calls: 60 requests per 30 seconds.

Implication:

- Futu is sufficient for execution PoC and likely enough for daily-bar offshore ETF backtests if the account quota is adequate.

- For production research we should still maintain an independent data source or validation source, because broker data quotas and account-bound entitlements can change.

Sources:

- Futu overview: https://openapi.futunn.com/futu-api-doc/en/quote/overview.html

- Futu sample code: https://openapi.futunn.com/futu-api-doc/en/quick/demo.html

- Futu historical K-line: https://openapi.futunn.com/futu-api-doc/en/quote/request-history-kline.html

- Futu trade environment: https://openapi.futunn.com/futu-api-doc/en/trade/trade.html

- Futu trade Q&A: https://openapi.futunn.com/futu-api-doc/en/qa/trade.html

Data Source Options

Source	Role	Pros	Cons	Recommendation
Futu OpenAPI	Broker execution + quote/historical bars	Same stack as execution; supports US stocks/ETFs; daily K-line up to 20 years; paper trading	Requires OpenD running and logged in; quotas account-bound; not ideal as sole research source	Use for execution PoC and broker-side validation
yfinance	Free research bootstrap	Fast, free, broad ETF coverage, easy install	Unofficial Yahoo wrapper; not production-grade; occasional breaks/corporate-action issues	Use for v0 research bootstrap only, cross-check key series
FRED	US macro regime labels	Official/free macro data; appropriate for PMI/ISM/CPI/PPI/Fed Funds/wages	Needs API key for robust use; series revisions/vintages matter	Use as macro source for USD 4-regime labels
IBKR Market Data	Production-grade broker/data fallback	Established broker API, market data subscriptions, snapshots and streaming	Requires IBKR account/subscriptions; not current Kaite execution account	Best production fallback if Futu data/exec is insufficient
Polygon/Massive	Paid market data	Good developer API and broad data products	Paid; terms/plan selection required; may be overkill for daily ETF bars	Consider only if Futu/yfinance validation is insufficient
Tiingo	Paid/low-cost market data	Simple API, ETF/equity data, usually cheaper than institutional vendors	Coverage/production SLA to verify	Candidate low-cost independent validation source
Wind overseas	Institutional terminal/data	Useful if already licensed; China team familiarity	Cost/licensing unclear; API workflow may be heavier	Optional if license already exists

Recommended Stack v0

1. Research/backtest bootstrap: yfinance for daily OHLCV of selected ETFs and leader-stock universe candidates.

2. Macro regime: FRED for US macro series.

3. Execution PoC + data validation: Futu OpenAPI with paper trading and selected ETF historical K-line pulls.

4. Production decision gate: compare yfinance vs Futu adjusted daily returns for core ETFs. If mismatch/outages are material, evaluate Tiingo or Polygon as independent production data source.

Offshore v0 Universe Draft

All-weather ETF universe:

- Equity: SPY, QQQ, IWM

- Long duration: TLT

- Intermediate duration: IEF

- T-bill/cash proxy: SHV

- Gold: GLD or IAU

- Broad commodities: DBC; possibly GSG as energy-heavy alternative

- Credit optional: LQD, HYG

US leader strategy:

- Original Minervini/CANSLIM universe; initial data source must support US listed equities, corporate actions, fundamentals and liquidity filters.

- yfinance can bootstrap price/volume; fundamentals likely need another source for production (Futu stock filters, Polygon/Tiingo, Financial Modeling Prep, or manual vendor).

Futu OpenAPI PoC Plan

Phase 0: Local install only

- Create isolated venv under projects/mini-cypress/offshore-sleeve/.venv-futu.

- Install futu-api.

- Add scripts that do not contain credentials:

- check_futu_connection.py: connect to 127.0.0.1:11111, query OpenD status via quote context.

- fetch_futu_kline.py: pull daily K-line for US.SPY, US.TLT, US.GLD for a short window, write parquet/CSV.

- futu_sim_order_smoke.py: paper-order only, default disabled behind --confirm-sim-order flag.

Phase 1: OpenD connected by Kaite/JimSimons operator

- Start Futu OpenD manually on the machine with account login.

- Confirm get_acc_list() with filter_trdmarket=TrdMarket.US; record only account type/status, never credentials.

- Pull market snapshot for US.SPY and historical K-line for a small ETF set.

- Confirm TrdEnv.SIMULATE paper order path with a deliberately non-marketable limit or tiny simulate order.

Phase 2: Paper portfolio loop

- Generate target weights externally from backtest.

- Translate target weights into US ETF orders in SIMULATE only.

- Validate order preview/submit/cancel lifecycle.

- Add guardrails: no REAL env, max order notional, allowlist symbols, dry-run by default.

Phase 3: Real-trade readiness gate, not yet approved

Required before real trading:

- Explicit Kaite approval.

- Explicit RayDario deployment spec.

- Dedicated real-trade config file with hard notional caps.

- Kill switch / cancel-all tested.

- Reconciliation of positions/cash/FX.

- Daily audit log.

Initial Data Validation Checks

- Adjusted close consistency: compare yfinance vs Futu QFQ daily returns for SPY/TLT/GLD/DBC over 5 years.

- Outlier check: |daily_return| > 15% for ETFs, investigate splits/distributions.

- Calendar alignment: US trading holidays vs Futu/yfinance/FRED macro release calendar.

- FX cost tracking: HKD-to-USD conversion spread as explicit one-time transaction cost.

Open Questions

- Does Kaite's Futu HK account already have OpenAPI enabled and US market quote entitlement?

- Can OpenD run on the cloud VM, or must it run on a local desktop with GUI/login? If local-only, we need a secure operator workflow.

- Is there an existing IBKR account, or is IBKR only a possible fallback?

- Which vendor licenses already exist: Wind overseas, Bloomberg, FactSet, Refinitiv, Tiingo/Polygon?

Price/Plan Notes Verified 2026-05-17

- Polygon stock plans visible on official pricing page: free tier has 5 API calls/min and 2 years historical data; Starter $29/mo has unlimited API calls and 5 years; Developer $79/mo has 10 years; Advanced $199/mo has 20+ years and real-time data plus financials/ratios. Non-pro plans are for individual use; business pricing separate.

- IBKR official market-data pricing page says clients get free real-time streaming data on all US-listed stocks and ETFs from Cboe One and IEX, initially 100 concurrent real-time market data lines, usable through TWS/API. Exchange-specific subscriptions may still be needed depending on use.

- FRED official API supports fred/series/observations with XML/JSON/XLSX/CSV outputs and transformations including YoY percent changes; API key is required for robust use.

- yfinance official docs expose download, Ticker, screen, WebSocket, sector/industry/query helpers. It is convenient but should be treated as a bootstrap/validation source rather than production source because it wraps Yahoo Finance data access rather than a paid SLA data feed.

2026-05-17 T1 Update: Tiingo Switch

RayDario approved replacing yfinance with Tiingo free tier as v0 default after yfinance hit rate limits on SPY in this environment.

Implemented:

- scripts/fetch_offshore_etf_data_tiingo.py

- Reads TIINGO_API_KEY from environment.

- Fetches SPY/QQQ/IWM/TLT/IEF/SHV/GLD/DBC/HYG/LQD from Tiingo daily REST API.

- Writes raw CSV to output/offshore_etf_daily_tiingo_raw.csv.

- Writes per-ticker parquet to ~/data/mini-cypress/offshore/equity_etf/2005-2026/.

- Writes summary and |daily return| > 15% outlier check.

Current blocker:

- TIINGO_API_KEY is not present in this runtime. Script is ready and fails cleanly with TIINGO_API_KEY is required.