agent-finance-cli 0.1.1 → 0.1.3

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agent-finance-cli"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/M4n5ter/agent-finance-cli"
@@ -29,3 +29,5 @@ zip = { version = "8.6.0", default-features = false, features = ["deflate"] }
 scraper = "0.27.0"
 wreq = { version = "6.0.0-rc.29", default-features = false, features = ["cookies", "deflate", "gzip", "json", "socks", "system-proxy", "tokio-rt", "webpki-roots"] }
 wreq-util = "3.0.0-rc.12"
+iana-time-zone = "0.1"
+polymarket_client_sdk_v2 = { version = "*", features = ["clob", "gamma", "data"] }

package/README.md

@@ -2,7 +2,7 @@
 
 AI Agent-first CLI for no-key financial market data and research context.
 
-`agent-finance` is designed for human-operated AI agents: the CLI can print its own task-specific skills, then provide current quotes, regular/pre/post/overnight session splits, OHLCV history, local indicators, proxy futures data, no-key research payloads, URL text extraction, provider capability notes, polling, and Yahoo WebSocket streams.
+`agent-finance` is designed for human-operated AI agents: the CLI can print its own task-specific skills, then provide current quotes, regular/pre/post/overnight session splits, OHLCV history, local indicators, proxy futures data, prediction-market sentiment, no-key research payloads, URL text extraction, provider capability notes, polling, and Yahoo WebSocket streams.
 
 If you are an AI Agent, start here:
 
@@ -69,6 +69,10 @@ agent-finance read-url "https://www.sec.gov/Archives/edgar/data/0001807794/00016
 agent-finance search "optical interconnect"
 agent-finance screen day_gainers
 agent-finance providers
+
+# Prediction-market sentiment and event probabilities.
+agent-finance polymarket search "spacex ipo" --limit 5
+agent-finance polymarket market MARKET_ID_OR_SLUG --json
 ```
 
 ## Agent Skills
@@ -81,6 +85,7 @@ agent-finance skills get core --full
 agent-finance skills get price
 agent-finance skills get research-data
 agent-finance skills get providers
+agent-finance skills get prediction-markets
 agent-finance skills get history-indicators
 agent-finance skills get futures
 ```
@@ -92,6 +97,7 @@ agent-finance skills get futures
 - `history` defaults to adjusted prices and includes corporate actions unless disabled.
 - `providers` is the source-of-truth capability matrix. Do not infer coverage from provider names.
 - Binance futures / TradFi perps are derivative/proxy prices. They are useful for 24h price discovery, but they are not the legal equity, broker fill, or pre-IPO ownership price.
+- Polymarket is a prediction-market sentiment source. Use it for implied probabilities, orderbook, spread, volume, liquidity, open interest, holder preview rows, and probability history. It is not an equity quote, primary-source fact, or confirmation of insider information.
 - `read-url` is an extraction fallback using direct/Jina/Defuddle readers. It is not a login-capable browser.
 - Dynamic, login-gated, screenshot-sensitive, or noisy pages should be verified with a real browser tool. `agent-browser` and `opencli` are examples, not dependencies.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-finance-cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "AI Agent-first CLI for no-key financial market data and research context.",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -31,11 +31,11 @@
     "check:npm": "node npm/check-package.js"
   },
   "optionalDependencies": {
-    "agent-finance-cli-darwin-arm64": "0.1.1",
-    "agent-finance-cli-darwin-x64": "0.1.1",
-    "agent-finance-cli-linux-arm64": "0.1.1",
-    "agent-finance-cli-linux-x64": "0.1.1",
-    "agent-finance-cli-win32-x64": "0.1.1"
+    "agent-finance-cli-darwin-arm64": "0.1.3",
+    "agent-finance-cli-darwin-x64": "0.1.3",
+    "agent-finance-cli-linux-arm64": "0.1.3",
+    "agent-finance-cli-linux-x64": "0.1.3",
+    "agent-finance-cli-win32-x64": "0.1.3"
   },
   "keywords": [
     "finance",

package/skills/core-full.md

@@ -10,6 +10,7 @@ agent-finance skills get core
 agent-finance skills get price
 agent-finance skills get research-data
 agent-finance skills get providers
+agent-finance skills get prediction-markets
 agent-finance skills get history-indicators
 agent-finance skills get futures
 ```
@@ -67,8 +68,21 @@ agent-finance futures LITEUSDT --json
 
 Use `providers` as the source-of-truth coverage matrix. Binance futures / TradFi perps are derivative/proxy prices, not legal equity or broker-fill prices.
 
+## Prediction Markets
+
+```bash
+agent-finance polymarket search "spacex ipo" --limit 5
+agent-finance polymarket search "spcex" --limit 5
+agent-finance polymarket market MARKET_ID_OR_SLUG --json
+agent-finance skills get prediction-markets
+```
+
+Use Polymarket for quantifiable sentiment and event-probability signals. It does not replace SEC/IR/company releases, verified news, or equity quotes.
+
 ## Network and Browser Boundaries
 
 The CLI respects `--proxy`, `AGENT_FINANCE_PROXY`, and standard proxy environment variables. It does not hardcode a local proxy.
 
+Polymarket uses the official SDK by default. When `--proxy` or `--no-proxy` is explicit, it uses public REST fallback through the CLI HTTP stack so those network controls are honored.
+
 `read-url` is a text extraction fallback. For dynamic, login-gated, screenshot-sensitive, or noisy pages, open the original page with an available real browser tool such as agent-browser or opencli.

package/skills/core.md

@@ -48,6 +48,14 @@ agent-finance search "optical interconnect"
 agent-finance screen day_gainers
 ```
 
+5. Prediction-market sentiment:
+
+```bash
+agent-finance polymarket search "spacex ipo" --limit 5
+agent-finance polymarket market MARKET_ID_OR_SLUG
+agent-finance skills get prediction-markets
+```
+
 ## Rules
 
 - Use `price` for the default "what is the current price?" answer.
@@ -55,5 +63,6 @@ agent-finance screen day_gainers
 - Use both daily and minute history before judging fills, limit-order quality, stop placement, or intraday action.
 - Use `providers --json` when an Agent needs a machine-readable capability matrix.
 - Treat Binance futures / TradFi perps as proxy/derivative price discovery only.
+- Treat Polymarket as quantifiable prediction-market sentiment and event-probability evidence only; it is not an equity quote or primary-source fact.
 - `read-url` is a text extraction fallback, not a real browser. For dynamic, login-gated, screenshot-sensitive, or noisy pages, use an available browser tool such as agent-browser or opencli.
 - JSON output preserves structured fields for downstream computation. Human output is for quick inspection.

package/skills/prediction-markets.md

@@ -0,0 +1,47 @@
+# agent-finance prediction-markets skill
+
+Use this skill when an AI Agent needs prediction-market sentiment, event probabilities, or "what capital is pricing in" for a public event.
+
+## Commands
+
+```bash
+agent-finance polymarket search "spacex ipo" --limit 5
+agent-finance polymarket search "spcex" --limit 5
+agent-finance polymarket market MARKET_ID_OR_SLUG
+agent-finance polymarket market MARKET_ID_OR_SLUG --json
+```
+
+## Search Semantics
+
+- Treat Polymarket search as public relevance search. Do not describe it as guaranteed fuzzy search.
+- Use multiple query fallbacks for important topics:
+  - `spacex`, `space x`, `starship`, `ipo`
+  - `nvidia`, `nvda`, product names, regulatory events
+- The CLI locally filters and sorts by active/closed state, volume, liquidity, and market signal strength. Still inspect source URLs and raw JSON for important decisions.
+
+## Interpretation Rules
+
+- Polymarket prices are implied probabilities backed by user capital.
+- They are useful as quantifiable sentiment and event-probability evidence.
+- They are not facts, confirmed insider information, legal equity prices, broker-fill prices, or official company disclosures.
+- For investment research, pair this signal with primary sources: SEC filings, IR pages, company releases, earnings calls, and verifiable news.
+
+## Useful Flags
+
+```bash
+agent-finance polymarket search "spacex ipo" --include-closed --min-volume 1000 --json
+agent-finance polymarket market MARKET_ID_OR_SLUG --limit 20 --refresh
+```
+
+- `--include-closed`: include resolved/closed markets for historical expectation checks.
+- `--min-volume`: ignore thin markets.
+- `--refresh`: bypass local cache.
+- `--cache-ttl-seconds`: tune freshness for repeated agent workflows.
+- `--json`: preserve full structured payloads for downstream reasoning.
+
+## Boundaries
+
+- This CLI is read-only for Polymarket.
+- It does not accept private keys, derive API keys, place orders, cancel orders, or manage Polymarket positions.
+- Default transport uses the official SDK. Explicit `--proxy` or `--no-proxy` uses public REST fallback through the CLI HTTP stack so those network controls are honored.
+- Holder data is reported as preview rows returned by the API limit, not as a total holder count.

package/skills/providers.md

@@ -19,7 +19,8 @@ agent-finance providers --json
 - Robinhood and CNBC are partial no-key sources; use them as cross-checks, not replacements for official filings or primary disclosures.
 - Stooq live can provide no-key daily/weekly/monthly history; intraday bulk data requires explicit imported ZIP cache.
 - Binance futures / TradFi perps are proxy/derivative instruments.
+- Polymarket is a prediction-market sentiment source. Use `polymarket search` and `polymarket market` for implied probability, orderbook, liquidity, OI, holder preview rows, and probability history; do not use it as an equity quote or primary-source fact.
 
 ## Browser Boundary
 
-The CLI uses HTTP requests with browser-like TLS behavior where possible, but it is not a full browser. Dynamic, login-gated, screenshot-sensitive, or noisy pages require a real browser tool.
+The CLI uses HTTP requests with browser-like TLS behavior where possible, but it is not a full browser. Dynamic, login-gated, screenshot-sensitive, or noisy pages require a real browser tool. Polymarket uses the official SDK by default; explicit `--proxy` or `--no-proxy` uses public REST fallback through the CLI HTTP stack.

package/src/app.rs

@@ -8,8 +8,9 @@ use serde::Serialize;
 
 use crate::cli::{
     Cli, Command, FuturesArgs, HistoryArgs, HistorySession, IndicatorsArgs, NewsArgs, OptionsArgs,
-    OptionsProvider, Provider, ProviderResearchArgs, ProvidersArgs, ReadUrlArgs, ResearchArgs,
-    ScreenArgs, SearchArgs, SessionsArgs, StooqArgs, StooqCommand, WatchArgs,
+    OptionsProvider, PolymarketArgs, PolymarketCommand, Provider, ProviderResearchArgs,
+    ProvidersArgs, ReadUrlArgs, ResearchArgs, ScreenArgs, SearchArgs, SessionsArgs, StooqArgs,
+    StooqCommand, WatchArgs,
 };
 use crate::http::http_client;
 use crate::indicators::compute_indicator;
@@ -21,21 +22,27 @@ use crate::providers::{self, binance_futures, stooq};
 use crate::research;
 use crate::skills;
 use crate::stream;
+use crate::time::resolve_timezone;
 
 pub async fn run() -> Result<()> {
     let cli = Cli::parse();
     let proxy = cli.proxy.as_deref();
     let no_proxy = cli.no_proxy;
-    let timezone = cli.timezone.as_str();
+    let timezone = resolve_timezone(cli.timezone.as_deref())?;
+    let timezone = timezone.as_str();
     let timeout_seconds = cli.timeout_seconds;
     match cli.command {
         Command::Price(args) => run_price(args, proxy, no_proxy, timeout_seconds, timezone).await,
         Command::Sessions(args) => {
             run_sessions(args, proxy, no_proxy, timeout_seconds, timezone).await
         }
-        Command::History(args) => run_history(args, proxy, no_proxy, timeout_seconds).await,
+        Command::History(args) => {
+            run_history(args, proxy, no_proxy, timeout_seconds, timezone).await
+        }
         Command::Indicators(args) => run_indicators(args, proxy, no_proxy, timeout_seconds).await,
-        Command::Futures(args) => run_futures(args, proxy, no_proxy, timeout_seconds).await,
+        Command::Futures(args) => {
+            run_futures(args, proxy, no_proxy, timeout_seconds, timezone).await
+        }
         Command::Fundamentals(args) => {
             run_provider_quote_summary(
                 args,
@@ -88,6 +95,9 @@ pub async fn run() -> Result<()> {
         Command::News(args) => run_news(args, proxy, no_proxy, timeout_seconds, timezone).await,
         Command::ReadUrl(args) => run_read_url(args, proxy, no_proxy, timeout_seconds).await,
         Command::Search(args) => run_search(args, proxy, no_proxy, timeout_seconds, timezone).await,
+        Command::Polymarket(args) => {
+            run_polymarket(args, proxy, no_proxy, timeout_seconds, timezone).await
+        }
         Command::Screen(args) => run_screen(args, proxy, no_proxy, timeout_seconds, timezone).await,
         Command::Stooq(args) => run_stooq(args, proxy, no_proxy, timeout_seconds).await,
         Command::Providers(args) => run_providers(args),
@@ -97,6 +107,57 @@ pub async fn run() -> Result<()> {
     }
 }
 
+async fn run_polymarket(
+    args: PolymarketArgs,
+    proxy: Option<&str>,
+    no_proxy: bool,
+    timeout_seconds: u64,
+    timezone: &str,
+) -> Result<()> {
+    let client = http_client(timeout_seconds, proxy, no_proxy)?;
+    let use_http_transport = proxy.is_some() || no_proxy;
+    match args.command {
+        PolymarketCommand::Search(args) => {
+            let options = providers::polymarket::SearchRequestOptions {
+                query: args.query,
+                limit: args.limit,
+                include_closed: args.include_closed,
+                min_volume: args.min_volume,
+                refresh: args.refresh,
+                cache_ttl_seconds: args.cache_ttl_seconds,
+                timeout_seconds,
+                use_http_transport,
+            };
+            let report = providers::polymarket::search_report(&client, &options, timezone).await?;
+            if args.json {
+                println!("{}", serde_json::to_string_pretty(&report)?);
+            } else {
+                output::print_prediction_search_report(&report);
+            }
+            Ok(())
+        }
+        PolymarketCommand::Market(args) => {
+            let options = providers::polymarket::MarketRequestOptions {
+                identifier: args.identifier,
+                limit: args.limit,
+                include_closed: args.include_closed,
+                min_volume: args.min_volume,
+                refresh: args.refresh,
+                cache_ttl_seconds: args.cache_ttl_seconds,
+                timeout_seconds,
+                use_http_transport,
+            };
+            let report = providers::polymarket::market_report(&client, &options, timezone).await?;
+            if args.json {
+                println!("{}", serde_json::to_string_pretty(&report)?);
+            } else {
+                output::print_prediction_market_report(&report);
+            }
+            Ok(())
+        }
+    }
+}
+
 fn run_skills(args: crate::cli::SkillsArgs) -> Result<()> {
     match args.command {
         crate::cli::SkillsCommand::List => {
@@ -193,6 +254,7 @@ async fn run_history(
     proxy: Option<&str>,
     no_proxy: bool,
     timeout_seconds: u64,
+    timezone: &str,
 ) -> Result<()> {
     let client = http_client(timeout_seconds, proxy, no_proxy)?;
     let provider = effective_history_provider(args.provider, args.session);
@@ -213,7 +275,7 @@ async fn run_history(
     if args.json {
         println!("{}", serde_json::to_string_pretty(&history)?);
     } else {
-        output::print_history_table(&history);
+        output::print_history_table(&history, timezone);
     }
     Ok(())
 }
@@ -291,6 +353,7 @@ async fn run_futures(
     proxy: Option<&str>,
     no_proxy: bool,
     timeout_seconds: u64,
+    timezone: &str,
 ) -> Result<()> {
     let client = http_client(timeout_seconds, proxy, no_proxy)?;
     let stats =
@@ -299,7 +362,7 @@ async fn run_futures(
     if args.json {
         println!("{}", serde_json::to_string_pretty(&stats)?);
     } else {
-        output::print_futures_stats(&stats);
+        output::print_futures_stats(&stats, timezone);
     }
 
     if stats.errors.is_empty() {

package/src/cli.rs

@@ -2,7 +2,6 @@ use std::path::PathBuf;
 
 use clap::{Parser, Subcommand, ValueEnum};
 
-use crate::time::DEFAULT_TIMEZONE;
 pub const HISTORY_INTERVAL_HELP: &str = "Bar interval. Provider-specific values: Yahoo 1m/2m/5m/15m/30m/60m/90m/1h/1d/5d/1wk/1mo/3mo; Robinhood 5m/10m/1h/1d/1w; Stooq live 1d/1w/1mo; Stooq bulk 5m/1h after sync; Binance klines 1m/3m/5m/15m/30m/1h/2h/4h/6h/8h/12h/1d/3d/1w/1M.";
 
 #[derive(Parser, Debug)]
@@ -21,9 +20,10 @@ pub struct Cli {
     #[arg(long, global = true)]
     pub no_proxy: bool,
 
-    /// Human-output timezone. UTC is still preserved in JSON fields.
-    #[arg(long, global = true, default_value = DEFAULT_TIMEZONE)]
-    pub timezone: String,
+    /// Human-output timezone. Defaults to the machine's local IANA timezone.
+    /// UTC is still preserved in JSON fields.
+    #[arg(long, global = true)]
+    pub timezone: Option<String>,
 
     /// HTTP timeout in seconds.
     #[arg(long, global = true, default_value_t = 10)]
@@ -61,6 +61,8 @@ pub enum Command {
     ReadUrl(ReadUrlArgs),
     /// Search Yahoo Finance for tickers and news.
     Search(SearchArgs),
+    /// Inspect Polymarket prediction-market sentiment and event-probability signals.
+    Polymarket(PolymarketArgs),
     /// Run Yahoo predefined screeners.
     Screen(ScreenArgs),
     /// Inspect or import Stooq bulk historical data packages.
@@ -341,6 +343,67 @@ pub struct SearchArgs {
     pub json: bool,
 }
 
+#[derive(Parser, Debug)]
+pub struct PolymarketArgs {
+    #[command(subcommand)]
+    pub command: PolymarketCommand,
+}
+
+#[derive(Subcommand, Debug)]
+pub enum PolymarketCommand {
+    /// Search public Polymarket events and markets by relevance.
+    Search(PolymarketSearchArgs),
+    /// Inspect one Polymarket market by numeric id or slug.
+    Market(PolymarketMarketArgs),
+}
+
+#[derive(Parser, Debug)]
+pub struct PolymarketSearchArgs {
+    pub query: String,
+
+    #[arg(long, default_value_t = 8)]
+    pub limit: usize,
+
+    #[arg(long)]
+    pub include_closed: bool,
+
+    #[arg(long)]
+    pub min_volume: Option<f64>,
+
+    #[arg(long)]
+    pub refresh: bool,
+
+    #[arg(long, default_value_t = 900)]
+    pub cache_ttl_seconds: u64,
+
+    #[arg(long)]
+    pub json: bool,
+}
+
+#[derive(Parser, Debug)]
+pub struct PolymarketMarketArgs {
+    pub identifier: String,
+
+    /// Maximum rows for holder/trade/orderbook detail previews.
+    #[arg(long, default_value_t = 10)]
+    pub limit: usize,
+
+    #[arg(long)]
+    pub include_closed: bool,
+
+    #[arg(long)]
+    pub min_volume: Option<f64>,
+
+    #[arg(long)]
+    pub refresh: bool,
+
+    #[arg(long, default_value_t = 900)]
+    pub cache_ttl_seconds: u64,
+
+    #[arg(long)]
+    pub json: bool,
+}
+
 #[derive(Parser, Debug)]
 pub struct ScreenArgs {
     /// Yahoo predefined screener id, for example most_actives, day_gainers, day_losers.

package/src/model.rs

@@ -325,6 +325,89 @@ pub struct SearchReport {
     pub payload: Value,
 }
 
+#[derive(Debug, Clone, Serialize)]
+pub struct PredictionSearchReport {
+    pub provider: String,
+    pub query: String,
+    pub fetched_at_utc: String,
+    pub fetched_at_local: String,
+    pub cache_status: String,
+    pub source_urls: Vec<String>,
+    pub interpretation_note: String,
+    pub markets: Vec<PredictionMarketSummary>,
+    pub payload: Value,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PredictionMarketReport {
+    pub provider: String,
+    pub identifier: String,
+    pub fetched_at_utc: String,
+    pub fetched_at_local: String,
+    pub cache_status: String,
+    pub enrichment_status: String,
+    pub enrichment_fetched_at_utc: String,
+    pub enrichment_fetched_at_local: String,
+    pub source_urls: Vec<String>,
+    pub interpretation_note: String,
+    pub market: PredictionMarketSummary,
+    pub outcomes: Vec<PredictionOutcome>,
+    pub price_history: Vec<PredictionPricePoint>,
+    pub open_interest: Option<f64>,
+    pub holder_preview_count: Option<usize>,
+    pub data_errors: BTreeMap<String, String>,
+    pub payload: Value,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PredictionMarketSummary {
+    pub id: Option<String>,
+    pub condition_id: Option<String>,
+    pub slug: Option<String>,
+    pub event_id: Option<String>,
+    pub event_slug: Option<String>,
+    pub title: String,
+    pub question: Option<String>,
+    pub active: Option<bool>,
+    pub closed: Option<bool>,
+    pub accepting_orders: Option<bool>,
+    pub end_time_utc: Option<String>,
+    pub end_time_local: Option<String>,
+    pub volume: Option<f64>,
+    pub volume_24hr: Option<f64>,
+    pub liquidity: Option<f64>,
+    pub open_interest: Option<f64>,
+    pub best_bid: Option<f64>,
+    pub best_ask: Option<f64>,
+    pub spread: Option<f64>,
+    pub last_trade_price: Option<f64>,
+    pub one_hour_price_change: Option<f64>,
+    pub one_day_price_change: Option<f64>,
+    pub one_week_price_change: Option<f64>,
+    pub market_url: Option<String>,
+    pub outcomes: Vec<PredictionOutcome>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PredictionOutcome {
+    pub label: String,
+    pub implied_probability: Option<f64>,
+    pub clob_token_id: Option<String>,
+    pub best_bid: Option<f64>,
+    pub best_ask: Option<f64>,
+    pub spread: Option<f64>,
+    pub last_trade_price: Option<f64>,
+    pub bid_count: usize,
+    pub ask_count: usize,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PredictionPricePoint {
+    pub time_utc: Option<String>,
+    pub time_local: Option<String>,
+    pub price: f64,
+}
+
 #[derive(Debug, Clone, Serialize)]
 pub struct StreamQuote {
     pub symbol: String,