agent-finance

English | 简体中文 | 日本語 | 한국어

Market intelligence for AI agents that need evidence, not guesswork.

agent-finance is a terminal-native finance toolkit built for AI agents and automation workflows. It gives an agent a compact command surface for prices, sessions, history, indicators, crypto market structure, prediction-market sentiment, public-company research data, URL extraction, provider capability discovery, and guarded signed trading workflows.

It also includes agent-finance tui, a selected-symbol terminal with live quotes, a full OHLCV chart, capability-driven context, account views, diagnostics, and staged trade preparation.

Install once, then let agents discover the command surface from the CLI itself.

npm install -g agent-finance-cli
npx skills add https://github.com/M4n5ter/agent-finance
agent-finance skills get core

What It Helps Agents Do

• Answer "what is it trading at now?" with current observable price, session, regular-market basis, and local/UTC timestamps.
• Separate regular, premarket, postmarket, and overnight signals instead of mixing them into one stale quote.
• Pull OHLCV history and local indicators before making order-quality or trend claims.
• Cross-check crypto spot, swaps, futures, order books, trades, candles, funding, open interest, and market breadth across Binance, Coinbase, OKX, and CoinGecko.
• Use Polymarket markets as quantifiable sentiment and event-probability evidence.
• Fetch no-key research payloads from Binance Stocks, Yahoo, SEC EDGAR, Robinhood, CNBC, Stooq, and fallback URL readers.
• Ask the CLI what each provider can actually do instead of guessing from provider names.
• Open the live terminal when the work is monitoring, comparing, or steering an investigation rather than extracting one parseable payload.
• Keep signed Binance account/order/transfer workflows behind profiles, intents, risk checks, explicit live confirmation, and append-only audit logs.
• Teach agents how to use the tool through built-in runtime skills that ship with the binary.

Why This Exists

Finance research agents fail when they rely on a single quote, a search snippet, or a provider name that sounds authoritative. They need a repeatable way to collect fresh data, know which session a price came from, understand provider limits, and leave an audit trail when touching live accounts.

agent-finance is intentionally CLI-first because AI agents are already good at shells:

• commands are stable and scriptable;
• JSON output is available where agents need structure;
• terminal output stays readable when another agent or automation layer inspects a run;
• provider capabilities are discoverable at runtime;
• skills are embedded, so agent guidance can evolve with the installed version.

Install

Install the CLI and the discovery skill:

npm install -g agent-finance-cli
npx skills add https://github.com/M4n5ter/agent-finance

The project is agent-finance. The npm package is published as agent-finance-cli because agent-finance is not available on npm. Do not install an npm package named agent-finance; it is not this project.

The npm package installs a prebuilt binary on supported platforms:

• macOS arm64 / x64
• Linux arm64 / x64
• Windows x64

Rust is not required for the normal npm install path. If no prebuilt package is available, npm attempts a local source build as a fallback; most users should stay on the supported prebuilt platforms.

Update the CLI and refresh the installed discovery skill:

npm install -g agent-finance-cli@latest
npx skills add https://github.com/M4n5ter/agent-finance
agent-finance --version

Source install is mainly for contributors and unsupported platforms:

cargo install --git https://github.com/M4n5ter/agent-finance agent-finance-cli

From a checkout:

cargo install --path crates/cli --locked
cargo run --bin agent-finance -- skills get core

The Agent Entry Point

If you are wiring this into an AI agent, do not start by memorizing flags. Let the installed CLI describe itself:

agent-finance skills list
agent-finance skills get core --full

The repository also ships a standard discovery skill at:

skills/agent-finance/SKILL.md

Install it with npx skills add https://github.com/M4n5ter/agent-finance. It points agents back to runtime skills emitted by the local binary, so command guidance stays aligned with the installed version.

Use the installed discovery skill as the coarse entry point, then let agent-finance skills get ... provide command-specific guidance from the local binary.

Useful runtime skills:

agent-finance skills get price
agent-finance skills get history-indicators
agent-finance skills get crypto
agent-finance skills get research-data
agent-finance skills get providers
agent-finance skills get prediction-markets
agent-finance skills get profile
agent-finance skills get tui

Localization

Human-facing CLI and TUI text supports en-US, zh-CN, ja-JP, and ko-KR.

agent-finance --locale zh market price AAPL
agent-finance --locale ja --help
AGENT_FINANCE_LOCALE=ko agent-finance skills get core

Locale precedence is: --locale, TUI config, AGENT_FINANCE_LOCALE, system locale, then en-US.

In the TUI, open Settings and change language for an immediate UI switch. Saving the config persists the language. JSON output, command names, flags, provider identifiers, schema keys, numeric formats, timestamps, and provider-returned content stay stable and are not localized.

Quick Tour

Current price and session context:

agent-finance market price CRDO
agent-finance market price CRDO MRVL --json
agent-finance market sessions CRDO
agent-finance market sessions LITE --proxy-symbol LITEUSDT

History and indicators:

agent-finance market history CRDO --range 1mo --interval 1d
agent-finance market history CRDO --range 5d --interval 1m --session extended --adjustment raw --no-actions
agent-finance market indicators CRDO MRVL --limit 120

Crypto market structure:

agent-finance market crypto quote BTC/USDT
agent-finance market crypto book BTC/USDT --limit 20
agent-finance market crypto candles BTC/USDT --interval 1h --limit 48
agent-finance market crypto funding BTCUSDT --instrument swap --provider auto --limit 8
agent-finance market crypto open-interest BTCUSDT --instrument swap --provider okx
agent-finance market crypto discover --provider coingecko --kind trending

Public-company research and discovery:

agent-finance market fundamentals CRDO
agent-finance market fundamentals CRDO --provider binance-stocks
agent-finance market fundamentals CRDO --provider sec-edgar
agent-finance market analysis CRDO
agent-finance market options CRDO --provider robinhood --count 80
agent-finance market ownership CRDO
agent-finance market events CRDO --provider binance-stocks
agent-finance market events CRDO --provider sec-edgar
agent-finance market news CRDO
agent-finance market search "optical interconnect"
agent-finance market screen day_gainers

Prediction-market sentiment:

agent-finance market polymarket search "spacex ipo" --limit 5
agent-finance market polymarket market MARKET_ID_OR_SLUG --json

Streams, polling, and URL extraction:

agent-finance market stream CRDO --messages 5
agent-finance market watch CRDO --interval-seconds 15 --iterations 4
agent-finance market read-url "https://www.sec.gov/Archives/edgar/data/0001807794/000162828026014017/crdo-20260131.htm"

Provider capability discovery:

agent-finance market providers
agent-finance market provider-health binance-stocks --symbol LITE --json
agent-finance market provider-health binance-stocks --symbol LITE --deep --json
agent-finance market provider-endpoints add --provider binance-stocks usnbweb.net --json
agent-finance market provider-endpoints probe --provider binance-stocks --symbol LITE --json
agent-finance market provider-endpoints remove --provider binance-stocks usnbweb.net --json
agent-finance capabilities

Interactive terminal:

agent-finance tui --symbols AAPL,CRDO,BTCUSDT
agent-finance tui --symbols CRDO,LITE,AAOI --chart-preset auto

The TUI opens on a selected-symbol Market terminal: a large OHLCV chart, compact watchlist, symbol quote/header, and a capability-driven right rail. Hover preserves the candle while showing O/H/L/C/V, wheel or drag changes the visible window, and toolbar controls set range, interval, and glyph mode. Orders focuses on open orders, Portfolio on balances and holdings, and Account Setup plus Profile / Risk open as focused overlays. Press p for combined health, route, realtime, and task Diagnostics.

Trade opens as a staged drawer from a symbol, chart reference, watchlist row, holding, or open order. Chart clicks only prefill a draft; the workflow remains validation, risk summary, stage, review, confirmation, submit, and audit. Unsupported operations stay hidden or disabled by capability. Use agent-finance skills get tui for the interaction model and agent-finance tui --dump-state --json or market ... --json for structured data.

Chart presets are provider-aware. The source line reports the actual provider, session, range, interval, and bar count after fallback. For US equities and ETFs, realtime auto prefers Binance Stocks WebSocket when available; the header and Diagnostics expose provider, latency, fallback, gaps, and route evidence. It persists watchlist, refresh cadence, provider preferences, chart preferences, theme, locale, and trading profile selection to TOML unless --no-persist is used. The terminal starts from a clean Market workspace instead of restoring obsolete window geometry.

Signed Trading Workflows

agent-finance includes guarded Binance Spot and USD-M workflows for account reads, order intents, internal transfer intents, futures state changes, risk checks, and audit logs.

The important design choice: live writes are not exposed as casual one-liners. They go through profiles, risk policy, whitelists, intent files, explicit --live confirmation, provider permission checks, and append-only audit events.

Start here:

agent-finance skills get profile --full
agent-finance profile template --profile default
agent-finance profile doctor --profile default

Command families:

agent-finance account balances --profile default
agent-finance order create BTCUSDT --profile default --market spot --side buy --kind limit --quantity 0.001 --price 50000
agent-finance risk check INTENT_ID --profile default
agent-finance order submit INTENT_ID --profile default
agent-finance audit tail --limit 20

Provider Notes

• market price SYMBOL is the default answer to "what is it trading at now?"
• market sessions SYMBOL is for explicit regular/pre/post/overnight/provider comparisons.
• market history defaults to adjusted prices and includes corporate actions unless disabled.
• market providers is the source-of-truth capability matrix. Do not infer coverage from provider names.
• Crypto commands are capability-first. Force --provider binance|coinbase|okx|coingecko only when cross-checking or auditing.
• Binance and OKX are best for exchange and derivatives microstructure. Coinbase is a spot exchange cross-check. CoinGecko is aggregate breadth, trending, and metadata.
• Binance USD-M futures and TradFi proxy symbols are derivatives/proxies, not legal equity, broker fills, or pre-IPO ownership prices.
• Polymarket is useful for implied probabilities, spread, volume, liquidity, open interest, holder preview rows, and probability history. It is not a primary-source fact feed.
• market 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 still be verified with a real browser tool such as agent-browser or OpenCLI.

Network And Local State

Proxy precedence:

1. --proxy
2. AGENT_FINANCE_PROXY
3. ALL_PROXY
4. HTTPS_PROXY
5. HTTP_PROXY

Examples:

agent-finance --proxy socks5h://127.0.0.1:7890 market price CRDO
agent-finance --no-proxy market price CRDO

Local profile/data roots can be overridden for tests, sandboxes, and agent workspaces:

AGENT_FINANCE_CONFIG_HOME=/tmp/agent-finance/config \
AGENT_FINANCE_DATA_HOME=/tmp/agent-finance/data \
agent-finance profile template --profile default

SEC EDGAR requests use AGENT_FINANCE_SEC_USER_AGENT when set, otherwise a project-level user agent.

Set AGENT_FINANCE_SKILL_DATA_DIR to test or override runtime skill documents. The npm wrapper sets AGENT_FINANCE_PACKAGE_ROOT automatically for prebuilt platform binaries.

Safety

This tool is not investment advice. Market data can be delayed, incomplete, or wrong. Provider payloads can change. Social and prediction-market signals are evidence, not truth. Verify important facts against primary sources and follow source terms.