fintool

fintool — Financial Trading Skill

A suite of CLI tools for market intelligence and trading across multiple exchanges. Each exchange has its own binary.

Tools

Binary	Purpose	Path
fintool	Market intelligence (quotes, news, SEC filings)	{baseDir}/scripts/fintool
hyperliquid	Hyperliquid trading (spot, perp, HIP-3, deposits)	{baseDir}/scripts/hyperliquid
binance	Binance trading (spot, perp, deposits)	{baseDir}/scripts/binance
coinbase	Coinbase trading (spot, deposits)	{baseDir}/scripts/coinbase
okx	OKX trading (spot, perp, deposits, withdrawals)	{baseDir}/scripts/okx
polymarket	Polymarket prediction markets	{baseDir}/scripts/polymarket
backtest	Historical simulation + forward PnL (no keys needed)	{baseDir}/scripts/backtest

• Config: ~/.fintool/config.toml
• Mode: Always use JSON mode — <binary> --json '<JSON>'. All input and output is structured JSON.
• No exchange field: Each binary handles one exchange. No "exchange" parameter needed.

Setup Check (MANDATORY — do this FIRST)

Before running any command, verify the user's configuration:

cat ~/.fintool/config.toml 2>/dev/null

If the file doesn't exist, run:

{baseDir}/scripts/fintool --json '{"command":"init"}'

Check for these requirements:

1. OpenAI API key — Required for enriched quotes (trend/momentum analysis).

   • Look for: openai_api_key = "sk-..." (uncommented) in [api_keys]
   • If missing: Ask the user for their OpenAI API key, or tell them to add it to ~/.fintool/config.toml under [api_keys]

2. At least one exchange — Required for trading commands.

   • Hyperliquid: private_key or wallet_json + wallet_passcode in [wallet] (spot + perps)
   • Binance: binance_api_key + binance_api_secret in [api_keys] (spot + perps)
   • Coinbase: coinbase_api_key + coinbase_api_secret in [api_keys] (spot only)
   • OKX: okx_api_key + okx_secret_key + okx_passphrase in [api_keys] (spot + perps)
   • Polymarket: Uses wallet.private_key (same as Hyperliquid) for prediction market trading
   • If none configured: Ask the user which exchange they want to use and request the credentials.

Exception — backtest: The backtest binary requires no configuration — no API keys, no wallet. It uses public Yahoo Finance and CoinGecko data. You can use it immediately.

If the user provides credentials, edit ~/.fintool/config.toml directly to add them.

Exchange Capabilities

Feature	hyperliquid	binance	coinbase	okx	polymarket	backtest
Spot orders	buy, sell	buy, sell	buy, sell	buy, sell	—	simulated buy/sell
Perp orders	perp buy/sell	perp buy/sell	—	perp buy/sell	—	simulated perp buy/sell
Prediction markets	—	—	—	—	buy, sell, list, quote	—
Orderbook	spot + perp	spot + perp	spot	spot + perp	—	—
Deposit	Unit + Across	API	API	API	bridge	—
Withdraw	Bridge2 + Unit + Across	API	API	API	bridge	—
Transfer	spot ↔ perp ↔ dex	spot ↔ futures	—	funding ↔ trading	—	—
Balance	balance	balance	balance	balance	balance	simulated
Open orders	orders	orders	orders	orders	—	—
Cancel	cancel	cancel	cancel	cancel	—	—
Positions	positions	positions	—	positions	positions	simulated
Funding rate	—	—	—	perp funding_rate	—	—
Historical quote	—	—	—	—	—	quote
Forward PnL	—	—	—	—	—	+1d/+2d/+4d/+7d
SEC filings (dated)	—	—	—	—	—	report list/annual/quarterly

Error Handling

• All errors are returned as {"error": "..."}. Check for an error key in every response.
• If a command fails with insufficient balance or invalid symbol, relay the error clearly.
• If the exchange is not configured, tell the user which credentials are needed and offer to add them to config.

JSON Command Reference

Market Data (fintool)

// fintool --json '<JSON>'
{"command": "quote", "symbol": "BTC"}
{"command": "news", "symbol": "AAPL"}
{"command": "report_list", "symbol": "AAPL", "limit": 5}
{"command": "report_annual", "symbol": "AAPL"}
{"command": "report_quarterly", "symbol": "AAPL"}
{"command": "report_get", "symbol": "AAPL", "accession": "0000320193-24-000123"}

Hyperliquid Trading (hyperliquid)

// hyperliquid --json '<JSON>'
{"command": "address"}
{"command": "buy", "symbol": "ETH", "amount": 0.1, "price": 3800}
{"command": "sell", "symbol": "ETH", "amount": 0.1, "price": 4000}
{"command": "orderbook", "symbol": "HYPE"}
{"command": "orderbook", "symbol": "BTC", "levels": 10}
{"command": "quote", "symbol": "ETH"}
{"command": "perp_orderbook", "symbol": "BTC"}
{"command": "perp_buy", "symbol": "ETH", "amount": 0.5, "price": 3800}
{"command": "perp_sell", "symbol": "BTC", "amount": 0.01, "price": 100000}
{"command": "perp_buy", "symbol": "ETH", "amount": 0.5, "price": 3900, "close": true}
{"command": "perp_sell", "symbol": "BTC", "amount": 0.01, "price": 95000, "close": true}
{"command": "perp_leverage", "symbol": "ETH", "leverage": 5, "cross": true}
{"command": "perp_set_mode", "mode": "unified"}
{"command": "balance"}
{"command": "positions"}
{"command": "orders"}
{"command": "orders", "symbol": "BTC"}
{"command": "cancel", "order_id": "BTC:91490942"}
{"command": "deposit", "asset": "ETH", "amount": 0.01}
{"command": "deposit", "asset": "ETH", "amount": 0.05, "dry_run": true}
{"command": "deposit", "asset": "BTC", "amount": 0.001}
{"command": "deposit", "asset": "USDC", "amount": 100, "from": "base"}
{"command": "deposit", "asset": "USDC", "amount": 100, "from": "ethereum", "dry_run": true}
{"command": "withdraw", "asset": "USDC", "amount": 100}
{"command": "withdraw", "asset": "USDC", "amount": 100, "to": "base"}
{"command": "withdraw", "asset": "ETH", "amount": 0.5}
{"command": "transfer", "asset": "USDT0", "amount": 50, "from": "spot", "to": "cash"}
{"command": "transfer", "asset": "USDT0", "amount": 50, "from": "cash", "to": "spot"}
{"command": "bridge_status"}

Binance Trading (binance)

// binance --json '<JSON>'
{"command": "buy", "symbol": "BTC", "amount": 0.01, "price": 95000}
{"command": "sell", "symbol": "BTC", "amount": 0.01, "price": 100000}
{"command": "orderbook", "symbol": "BTC"}
{"command": "perp_buy", "symbol": "ETH", "amount": 0.5, "price": 3800}
{"command": "perp_sell", "symbol": "ETH", "amount": 0.5, "price": 4000, "close": true}
{"command": "perp_leverage", "symbol": "ETH", "leverage": 5}
{"command": "balance"}
{"command": "positions"}
{"command": "orders"}
{"command": "cancel", "order_id": "binance_spot:BTCUSDT:123"}
{"command": "deposit", "asset": "USDC", "from": "ethereum"}
{"command": "withdraw", "asset": "USDC", "amount": 100, "to": "0x...", "network": "ethereum"}

OKX Trading (okx)

// okx --json '<JSON>'
{"command": "quote", "symbol": "BTC"}
{"command": "buy", "symbol": "ETH", "amount": 0.01, "price": 2000}
{"command": "sell", "symbol": "ETH", "amount": 0.01, "price": 2100}
{"command": "orderbook", "symbol": "BTC"}
{"command": "perp_orderbook", "symbol": "ETH"}
{"command": "perp_buy", "symbol": "ETH", "amount": 0.1, "price": 2000}
{"command": "perp_sell", "symbol": "ETH", "amount": 0.1, "price": 2100, "close": true}
{"command": "perp_leverage", "symbol": "ETH", "leverage": 5, "cross": true}
{"command": "perp_funding_rate", "symbol": "BTC"}
{"command": "balance"}
{"command": "positions"}
{"command": "orders"}
{"command": "cancel", "inst_id": "BTC-USDT", "order_id": "12345"}
{"command": "deposit", "asset": "USDC", "network": "base"}
{"command": "deposit", "asset": "ETH", "network": "ethereum"}
{"command": "withdraw", "asset": "USDC", "amount": 100, "network": "base"}
{"command": "withdraw", "asset": "USDC", "amount": 100, "to": "0x...", "network": "ethereum"}
{"command": "transfer", "asset": "USDT", "amount": 100, "from": "funding", "to": "trading"}
{"command": "transfer", "asset": "USDT", "amount": 100, "from": "trading", "to": "funding"}

OKX Notes:

• quote and orderbook are public endpoints — no API keys needed.
• OKX uses instrument IDs: spot = BTC-USDT, perp = BTC-USDT-SWAP. The CLI auto-formats from symbol.
• OKX has funding (for deposits/withdrawals) and trading (unified) accounts. Use transfer to move between them.
• Withdrawal fee is auto-fetched if --fee is not specified.
• Cancel requires both inst_id (e.g. BTC-USDT) and order_id.

Coinbase Trading (coinbase)

// coinbase --json '<JSON>'
{"command": "buy", "symbol": "ETH", "amount": 0.1, "price": 3800}
{"command": "sell", "symbol": "ETH", "amount": 0.1, "price": 4000}
{"command": "orderbook", "symbol": "BTC"}
{"command": "balance"}
{"command": "orders"}
{"command": "cancel", "order_id": "coinbase:uuid-here"}
{"command": "deposit", "asset": "ETH"}
{"command": "withdraw", "asset": "USDC", "amount": 100, "to": "0x..."}

Polymarket Prediction Markets (polymarket)

// polymarket --json '<JSON>'
{"command": "list", "query": "bitcoin"}
{"command": "list", "query": "election", "limit": 5}
{"command": "list", "query": "bitcoin", "min_end_days": 7}
{"command": "list", "query": "bitcoin", "min_end_days": 0}
{"command": "quote", "market": "will-bitcoin-hit-100k"}
{"command": "buy", "market": "will-bitcoin-hit-100k", "outcome": "yes", "amount": 10, "price": 0.65}
{"command": "sell", "market": "will-bitcoin-hit-100k", "outcome": "yes", "amount": 10, "price": 0.70}
{"command": "positions"}
{"command": "balance"}
{"command": "deposit", "amount": 100, "from": "base"}
{"command": "withdraw", "amount": 50}

Notes:

• list defaults to min_end_days: 3, filtering out markets that close within 3 days (whi

---

Content truncated.