---

name: fintool description: "Financial trading CLIs — spot and perp trading on Hyperliquid, Binance, Coinbase, OKX. Prediction markets on Polymarket. Deposit and withdraw across chains. LLM-enriched price quotes with trend analysis. News and SEC filings. Historical backtesting with forward PnL analysis. Use when: user asks about stock/crypto prices, wants to trade, deposit, withdraw, check portfolio, or backtest a strategy." homepage: https://github.com/second-state/fintool metadata: { "openclaw": { "emoji": "📈", "requires": { "bins": ["curl"] } } }

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 (which often have odds near 1:0). Set to 0 to see all markets.
• list and quote are read-only and don't require Polymarket credentials.
• Trading commands (buy, sell, deposit, withdraw) require wallet.private_key in config.
• Use the market slug (from list) or condition ID as the market value.

Backtesting (backtest)

Important: The backtest binary requires --at YYYY-MM-DD as a CLI flag (not in the JSON body). No API keys or wallet needed.

# backtest --at <DATE> --json '<JSON>'

// Historical price
{"command": "quote", "symbol": "BTC"}
{"command": "quote", "symbol": "AAPL"}
{"command": "quote", "symbol": "GOLD"}

// Simulated spot trades — returns forward PnL at +1/+2/+4/+7 days
{"command": "buy", "symbol": "ETH", "amount": 0.5}
{"command": "buy", "symbol": "AAPL", "amount": 10, "price": 237}
{"command": "sell", "symbol": "BTC", "amount": 0.01, "price": 105000}

// Simulated perp trades — returns leveraged forward PnL
{"command": "perp_leverage", "symbol": "ETH", "leverage": 5}
{"command": "perp_buy", "symbol": "ETH", "amount": 0.5, "price": 3300}
{"command": "perp_sell", "symbol": "BTC", "amount": 0.01, "price": 100000}

// SEC filings filtered by date
{"command": "report_list", "symbol": "AAPL", "limit": 5}
{"command": "report_annual", "symbol": "TSLA"}
{"command": "report_quarterly", "symbol": "AAPL"}

// Portfolio management
{"command": "balance"}
{"command"