Skip to content

rust-api.md

Latest commit

 

History

History
129 lines (103 loc) · 6.05 KB

rust-api.md

File metadata and controls

129 lines (103 loc) · 6.05 KB
Raw

Rust API guide

This repository is still CLI-first. The workspace crates are internal and not published as stable crates.io APIs, but several crates are intentionally shaped for reuse by other Rust applications in the same workspace or local tooling.

Current boundary

  • tradingview-core contains shared error and JSON envelope contracts.
  • tradingview-model contains I/O-free request interpretation, validation, selector resolution, payload shaping, and fallback policy.
  • tradingview-market contains credential-free, Desktop-free market reads for symbol search, symbol metadata, single-symbol quotes, batch quotes, and browserless historical bars.
  • tradingview-scanner contains credential-free, Desktop-free scanner hotlist, scan, and field metadata reads.
  • tradingview-pine contains Desktop-free Pine source analysis and check helpers.
  • tradingview-cdp contains TradingView Desktop / Chrome DevTools Protocol connection primitives.

Desktop-free means the crate does not connect to the locally running TradingView Desktop app and does not use chart state, UI automation, cookies, session export, or account mutation.

Authenticated official MCP boundary

tradingview-mcp is an internal workspace service for tv mcp, not a stable external Rust API. Its client owns OAuth, native credentials, admission and transport; tradingview-model::mcp_bars, mcp_data and mcp_technicals own pure request/response shaping. Consumers should use the separate CLI and versioned MCP contracts in Official MCP commands. This does not change the credential-free market/scanner APIs or the existing tv bars contract.

tradingview_model::mcp_error::provider_error_hints classifies an optional provider error string into a closed, public-safe clue list with unconfirmed root cause. It is I/O-free and does not preserve arbitrary strings or nested values. Data/bar normalizers use it for declared failures; transport error policy is unchanged.

Market reads

Prefer the typed functions from tradingview-market for Rust callers:

  • search_symbols_typed(query)
  • symbol_info_typed(symbol)
  • fundamentals_symbol_typed(symbol, fields)
  • quote_symbol_typed(symbol)
  • quote_symbols_typed(symbols)

The JSON-returning functions symbol_search, symbol_info, fundamentals_symbol, quote_symbol, quote_symbols, and bars_symbol remain public for CLI payload compatibility. New Rust code should not parse those JSON payloads unless it is specifically preserving the tv command contract.

Example shape:

let quote = tradingview_market::quote_symbol_typed("NYSE:IONQ").await?;
println!("{} {:?}", quote.symbol, quote.last);

Market quote reads use TradingView scanner data. They are useful for screening and Desktop-free checks, but they are not execution-grade realtime guarantees. Use Quote::time, Quote::update_mode, and Quote::delay_seconds when the caller needs to show feed timing or delayed-streaming metadata. Desktop-free market typed results expose source_category: "desktop_free_read", requires_desktop: false, and non_mutating: true. bars_symbol currently exposes the CLI-compatible bars.v1 JSON contract for bounded historical OHLCV reads; typed bars structs are intentionally not a stable Rust API yet.

Snapshot and comparison follow-up hints serialize an additive effects object without adding required fields to SnapshotFollowUpHint or CompareFollowUpHint. Existing struct-literal construction remains valid. chart_mutation is the inverse of the hint's chart-only non_mutating flag; built-in chart_quote hints now set that flag false. local_file_write is true for screenshot, false for other built-in kinds, and null for unknown caller-defined kinds. Producing a packet does not execute its hints or authorize those effects.

Scanner reads

Prefer the typed functions from tradingview-scanner for Rust callers:

  • scanner_hotlist_typed(slug, limit)
  • scanner_scan_typed(request)
  • scanner_scan_page_typed(request)
  • scanner_scan_aggregate_typed(request)
  • scanner_metainfo_typed(request)

The JSON-returning functions scanner_hotlist, scanner_scan, scanner_scan_page, scanner_scan_aggregate, and scanner_metainfo remain public for CLI payload compatibility. Explicit-offset reads return a separate ScannerPageScanResult wrapper so ScannerScanResult and the default first-page JSON contract remain source- and payload-compatible.

ScannerScanResult::symbols[].field_values intentionally remains a JSON value because scanner columns can contain numbers, strings, booleans, or nulls depending on the requested column and market state. A later internal API review may introduce stronger field-value enums if downstream consumers need that. Scanner typed results expose source_category: "desktop_free_read", requires_desktop: false, and non_mutating: true.

ScannerAggregateScanRequest wraps a ScannerScanRequest plus page_size and max_results. The aggregate API reuses one configured HTTP client, keeps each page at 100 rows or fewer, requires an integer provider total on every page, and returns ScannerAggregateScanResult only after bounded completion. Its deduplicated symbols and drift metadata describe a sequential observation, not an atomic snapshot.

Example shape:

let request = tradingview_scanner::ScannerMetainfoRequest {
    market: "america".to_string(),
    fields: vec!["close".to_string(), "premarket_close".to_string()],
};
let metainfo = tradingview_scanner::scanner_metainfo_typed(request).await?;
println!("{} fields", metainfo.field_count);

What stays in the CLI package

The tradingview-cli package owns the tv command surface, JSON envelopes, target selection, TradingView Desktop runtime orchestration, UI automation, and account mutation workflows. It may keep using JSON wrappers when that preserves the public CLI contract.

Do not move chart fallback quote reads, tv ohlcv, Screener UI operations, watchlist/alert mutations, Pine Editor operations, or generic UI automation into tradingview-market or tradingview-scanner. Those paths are not Desktop-free read APIs.