Digital Oracle

digital-oracle

Markets are efficient. Price contains all public information. Reading price = reading market consensus.

Methodology

Answer questions using only market trading data — no news, opinions, or statistical reports as causal evidence. If something is true, some market has already priced it in.

Five iron rules:

1. Trading data only — prices, volume, open interest, spreads, premiums. Never cite analyst opinions.
2. Explicit reasoning from price to judgment — explain clearly "why this price answers this question."
3. Multi-signal cross-validation — never conclude from a single signal. At least 3 independent dimensions.
4. Label the time horizon of each signal — options price 3 months, equipment orders price 3 years — don't mix them in the same vote.
5. Structured output — the final report must follow the Step 5 template: layered signal tables → contradiction analysis → probability scenarios → signal consistency assessment. Do not substitute prose for structured reporting.

Workflow

Step 1: Understand the question

Decompose the user's question into:

• Core variable: What event or trend?
• Time window: Is the user asking about 3 months, 1 year, or 5 years?
• Priceability: Is there real money being traded on this outcome?

Step 2: Select signals

Based on question type, select from the signal menu below. Don't use just one category — cover at least 3.

Geopolitical conflict / War risk

• Polymarket: Search for related event contracts (ceasefire, invasion, regime change, declaration of war)
• Kalshi: Search for related binary contracts
• Safe-haven assets: Gold (GC=F), silver (SI=F), Swiss franc (USDCHF=X)
• Conflict proxies: Crude oil (CL=F), natural gas (NG=F), wheat (ZW=F), defense ETF (ITA), defense stocks
• Risk ratios: Copper/Gold ratio (risk-off indicator), Gold/Silver ratio
• CFTC COT: Institutional positioning changes in crude/gold/wheat (which direction is smart money betting)
• BIS: Central bank policy rate trends in relevant countries
• FearGreedProvider: CNN Fear & Greed Index (composite of 7 price signals)
• Web search: VIX, MOVE index, sovereign CDS, war risk premiums, BDI freight rates, high-yield OAS
• Currencies: Currency pairs of relevant countries (e.g. USDRUB=X, USDCNY=X)
• Country ETFs: Asset flows in relevant countries (e.g. FXI, EWY)

Economic recession / Macro cycle

• Treasury: Yield curve shape (10Y-2Y spread, 10Y-3M spread), real rates, breakeven inflation
• YahooPriceProvider: SPY, copper (HG=F), crude oil (CL=F), price trends
• Risk ratios: Copper/Gold ratio
• CFTC COT: Speculative net positions in copper/crude (is managed money bullish or bearish)
• BIS: Credit-to-GDP gap (credit overheating = late cycle), policy rate directions
• World Bank: GDP growth rate historical trends, cross-country comparisons
• Deribit: BTC futures basis (risk appetite proxy)
• CoinGecko: Crypto total market cap + BTC dominance (risk appetite proxy)
• FearGreedProvider: CNN Fear & Greed Index (7 price signals composite → 0-100)
• Kalshi KXFED series: FOMC rate-decision contracts. (Use this for the rate path — CMEFedWatchProvider is currently 403-blocked by CME's bot protection from every host tested.)
• Polymarket: Recession-related contracts, central bank rate path
• Currencies: DXY/dollar strength, emerging market currencies
• Web search: High-yield bond spread (HY OAS), TED spread, MOVE index, TTF gas, BDI freight rates

Industry cycle / Bubble assessment

• YahooPriceProvider: Industry leader stock trends, sector ETFs
• Find the industry's "single-purpose commodity" (e.g. GPU rental price → AI, rebar → construction)
• Upstream equipment maker orders/stock price (e.g. ASML → semiconductors)
• Leader company valuation discount (e.g. TSMC vs peers → Taiwan Strait risk pricing)
• EDGAR: Industry leader insider trading cadence (Form 4) — concentrated selling = bearish signal
• CFTC COT: Institutional positioning changes in related commodities
• CoinGecko: For crypto industry, look at BTC/ETH/altcoin market cap distribution
• Web search: VC funding concentration, leveraged ETF concentration, margin debt levels
• Deribit: Implied volatility of related crypto assets

Asset pricing / Whether to buy

• YahooPriceProvider: Target asset price trend (daily/weekly/monthly)
• Relative price changes of correlated assets (divergence between two commodities = structural signal)
• Treasury: Risk-free rate as valuation anchor
• YFinance: Options chain (IV, put/call ratio, max pain, Greeks, implied move)
• EDGAR: Insider selling cadence (heavy Form 4 selling = insiders bearish)
• CFTC COT: Speculative vs commercial net position divergence for commodity assets
• CoinGecko: For crypto assets, check market cap, ATH/ATL distance, 24h volatility
• Deribit: Crypto options chain (implied volatility = market's expected range)
• Polymarket/Kalshi: Probability pricing of related events
• FearGreedProvider: CNN Fear & Greed composite score (momentum, breadth, VIX, put/call, junk bond demand, volatility, safe haven)
• Web search: VIX, corporate bond issuance volume, analyst rating distribution

Stock/Options analysis / Crash probability

• YFinance: Options chain → ATM IV (expected volatility), IV skew (upside/downside fear asymmetry), put/call ratio (bull/bear sentiment), max pain (market maker profit zone), implied move (expected price range), Greeks (delta ≈ ITM probability)
• YahooPriceProvider: Underlying historical price → realized volatility (compare vs implied volatility to judge options premium)
• Kalshi: SPY/NASDAQ price range markets → direct probability pricing
• CFTC COT: S&P 500/VIX futures positioning → institutional direction
• Defensive rotation: XLY (cyclical) vs XLP (defensive) vs XLU (utilities) relative performance → market defensiveness
• Treasury: Yield curve shape → recession signal
• FearGreedProvider: CNN Fear & Greed Index
• Web search: VIX level, margin debt level, leveraged ETF concentration

China A-share: individual stock / ETF / sector

Mainland listings are quoted in CNY on exchanges no US venue prices, so the usual Polymarket/Kalshi/CFTC layer has nothing to say about them. Route these to Eastmoney.

• Eastmoney get_quote: Live quote for a 6-digit code → last, change %, turnover rate, PE(TTM), PB, market cap. Pass the bare code (600519, 000977) — to_secid resolves the exchange.
• Eastmoney get_fund_flow: The signal with actual skin in the game. Daily net inflow split by order size — extra-large / large (together = 主力, institutional) vs medium / small (retail). Institutions buying while retail sells is a different tape than the reverse, and price alone cannot show it.
• Eastmoney list_sector_fund_flow: Industry or concept boards ranked by institutional net inflow → which sector money is rotating into. Answers "which sector is seeing inflows" directly.
• Eastmoney get_history: OHLCV with forward adjustment (adjust="forward") → realized volatility, trend, volume confirmation.
• YahooPriceProvider: Same listings via 600519.SS / 000977.SZ suffixes — useful as a cross-check, and the only way to put an A-share on the same axis as a US comparable.
• FXI / USDCNY=X: Foreign risk appetite toward Chinese assets and capital-flow direction — the offshore view on the same question.
• Sector read-through: For semiconductors / AI hardware, cross-check US comparables (NVDA, AMD, SOXX) since the supply chain is shared.

Two cautions. Eastmoney publishes fund flow after the close, so intraday questions get yesterday's tape. And no prediction market prices Chinese single names — if the user wants a probability, it has to be reasoned from positioning and volatility, not looked up.

Available trading symbols directory: See references/symbols.md Provider API reference: See references/providers.md

Step 3: Signal routing

Before fetching data, evaluate each candidate signal from Step 2 against three criteria:

1. Relevance: Can this signal actually answer the user's specific question? (e.g., asking about Taiwan → skip CoinGecko)
2. Time match: Does the signal's pricing horizon match the question's time window? (e.g., asking about 3 months → skip World Bank GDP which lags 1-2 years)
3. Information increment: Does this signal provide an independent perspective not already covered by other signals? Avoid redundancy, keep complementary signals.

Only keep signals that pass all three checks. This reduces noise, saves fetch time, and produces cleaner analysis.

Step 4: Fetch data

Use digital-oracle's Python providers to fetch structured data, calling all sources in parallel with gather() (including web search):

from digital_oracle import (
    PolymarketProvider, PolymarketEventQuery,
    KalshiProvider, KalshiMarketQuery,
    YahooPriceProvider, PriceHistoryQuery,   # requires uv pip install yfinance
    DeribitProvider, DeribitFuturesCurveQuery,
    USTreasuryProvider, YieldCurveQuery,
    WebSearchProvider,
    CftcCotProvider, CftcCotQuery,
    CoinGeckoProvider, CoinGeckoPriceQuery,
    EdgarProvider, EdgarInsiderQuery,
    BisProvider, BisRateQuery,
    WorldBankProvider, WorldBankQuery,
    YFinanceProvider, OptionsChainQuery,      # requires uv pip install yfinance
    FearGreedProvider,
    EastmoneyProvider, EastmoneyQuoteQuery, EastmoneyKlineQuery,
    EastmoneyFundFlowQuery, EastmoneySectorFlowQuery,
    gather,
)

pm = PolymarketProvider()
kalshi = KalshiProvider()
yahoo = YahooPriceProvider()  # requires uv pip install yfinance
deribit = DeribitProvider()
treasury = USTreasuryProvider()
web = WebSearchProvider()
cftc = CftcCotProvider()
coingecko = CoinGeckoProvider()
edgar = EdgarProvider()  # set EDGAR_USER_EMAIL to identify yourself to SEC; a contact is required or it 403s
bis = BisProvider()
wb = WorldBankProvider()
yf = YFinanceProvider()  # requires uv pip install yfinance
fear_greed = FearGreedProvider()
eastmoney = EastmoneyProvider()  # China A-share: quotes, OHLCV, fund flow, sector rotation

result = gather({
    "pm_events": lambda: pm.list_events(PolymarketEventQuery(slug_contains="...", limit=10)),
    "yield_curve": lambda: treasury.latest_yield_curve(),
    "gold": lambda: yahoo.get_history(PriceHistoryQuery(symbol="GC=F", limit=30)),
    # Institutional positioning
    "gold_cot": lambda: cftc.list_reports(CftcCotQuery(commodity_name="GOLD", limit=4)),
    # Crypto market sentiment
    "crypto": lambda: coingecko.get_prices(CoinGeckoPriceQuery(coin_ids=("bitcoin", "ethereum"))),
    # Insider trades
    "insider": lambda: edgar.get_insider_transactions(EdgarInsiderQuery(ticker="AAPL", limit=10)),
    # Central bank policy rates
    "rates": lambda: bis.get_policy_rates(BisRateQuery(countries=("US", "CN"), start_year=2023)),
    # GDP data
    "gdp": lambda: wb.get_indicator(WorldBankQuery(indicator="NY.GDP.MKTP.CD", countries=("US", "CN"))),
    # BTC futures term structure (risk appetite proxy)
    "btc_futures": lambda: deribit.get_futures_term_structure(DeribitFuturesCurveQuery(currency="BTC")),
    # Kalshi event markets (use event_ticker or series_ticker, not keyword search)
    "kalshi_fed": lambda: kalshi.list_markets(KalshiMarketQuery(series_ticker="KXFED", limit=10)),
    # Options chain (with Greeks)
    "spy_options": lambda: yf.get_chain(OptionsChainQuery(ticker="SPY", expiration="2026-04-17")),
    # CNN Fear & Greed (composite of 7 price signals)
    "fear_greed": lambda: fear_greed.get_index(),
    # China A-share: institutional vs retail flow, and which sector money rotated into
    "cn_stock": lambda: eastmoney.get_quote(EastmoneyQuoteQuery(symbol="002156")),
    "cn_flow": lambda: eastmoney.get_fund_flow(EastmoneyFundFlowQuery(symbol="002156", limit=10)),
    "cn_sectors": lambda: eastmoney.list_sector_fund_flow(EastmoneySectorFlowQuery(limit=15)),
    # Web search runs in parallel with structured providers
    "vix": lambda: web.search("VIX index current level"),
    "hy_spread": lambda: web.search("US high yield bond spread OAS"),
})

# Partial failures don't affect other results
curve = result.get("yield_curve")
vix_info = result.get_or("vix", None)  # WebSearchResult — use .text() to render

# Options data usage
chain = result.get_or("spy_options", None)
if chain:
    print(f"ATM IV: {chain.atm_iv:.1%}, Implied move: {chain.implied_move():.1%}")
    print(f"Put/Call OI ratio: {chain.put_call_oi_ratio:.2f}")
    print(f"Max pain: {chain.max_pain()}")

All 14 Providers:

13 out of 15 providers have zero external dependencies and zero API keys. YahooPriceProvider and YFinanceProvider require pip install yfinance.

WebSearchProvider usage:

• web.search("query") → returns WebSearchResult (search summary) — render with .text()
• web.fetch_page("url") → returns WebPageContent (page body extraction)
• Search engine is DuckDuckGo, zero API keys needed

Data not available via structured providers — use web search instead: VIX, MOVE, CDS spreads, TTF natural gas, BDI freight rates, war risk premiums, high-yield OAS — these need to be fetched from financial web pages. They are still trading data and comply with the methodology.