fintool — Skill de Negociação Financeira

Um conjunto de ferramentas CLI para inteligência de mercado e negociação em várias exchanges. Cada exchange possui seu próprio binário.

Ferramentas

Binário	Propósito	Caminho
`fintool`	Inteligência de mercado (cotações, notícias, arquivamentos SEC)	`{baseDir}/scripts/fintool`
`hyperliquid`	Negociação na Hyperliquid (spot, perp, HIP-3, depósitos)	`{baseDir}/scripts/hyperliquid`
`binance`	Negociação na Binance (spot, perp, depósitos)	`{baseDir}/scripts/binance`
`coinbase`	Negociação na Coinbase (spot, depósitos)	`{baseDir}/scripts/coinbase`
`okx`	Negociação na OKX (spot, perp, depósitos, retiradas)	`{baseDir}/scripts/okx`
`polymarket`	Mercados de previsão no Polymarket	`{baseDir}/scripts/polymarket`
`backtest`	Simulação histórica + PnL futuro (sem chaves necessárias)	`{baseDir}/scripts/backtest`

Configuração: ~/.fintool/config.toml
Modo: Sempre use o modo JSON — <binário> --json '<JSON>'. Toda entrada e saída é JSON estruturado.
Sem campo exchange: Cada binário lida com uma exchange. Nenhum parâmetro "exchange" é necessário.

Verificação de Configuração (OBRIGATÓRIO — faça isso PRIMEIRO)

Antes de executar qualquer comando, verifique a configuração do usuário:

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

Se o arquivo não existir, execute:

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

Verifique estes requisitos:

Chave da API OpenAI — Necessária para cotações enriquecidas (análise de tendência/momentum).
- Procure por: openai_api_key = "sk-..." (sem comentários) em [api_keys]
- Se estiver faltando: Peça ao usuário a chave da API OpenAI ou instrua-o a adicioná-la ao ~/.fintool/config.toml em [api_keys]
Pelo menos uma exchange — Necessária para comandos de negociação.
- Hyperliquid: private_key ou wallet_json + wallet_passcode em [wallet] (spot + perps)
- Binance: binance_api_key + binance_api_secret em [api_keys] (spot + perps)
- Coinbase: coinbase_api_key + coinbase_api_secret em [api_keys] (apenas spot)
- OKX: okx_api_key + okx_secret_key + okx_passphrase em [api_keys] (spot + perps)
- Polymarket: Usa wallet.private_key (mesmo da Hyperliquid) para negociação em mercados de previsão
- Se nenhuma estiver configurada: Pergunte ao usuário qual exchange deseja usar e solicite as credenciais.

Exceção — backtest: O binário de backtest não requer nenhuma configuração — sem chaves de API, sem carteira. Ele usa dados públicos do Yahoo Finance e CoinGecko. Você pode usá-lo imediatamente.

Se o usuário fornecer credenciais, edite ~/.fintool/config.toml diretamente para adicioná-las.

Capacidades das Exchanges

Recurso	`hyperliquid`	`binance`	`coinbase`	`okx`	`polymarket`	`backtest`
Ordens spot	comprar, vender	comprar, vender	comprar, vender	comprar, vender	—	comprar/vender simulado
Ordens perp	comprar/vender perp	comprar/vender perp	—	comprar/vender perp	—	comprar/vender perp simulado
Mercados de previsão	—	—	—	—	comprar, vender, listar, cotar	—
Livro de ordens	spot + perp	spot + perp	spot	spot + perp	—	—
Depósito	Unit + Across	API	API	API	bridge	—
Retirada	Bridge2 + Unit + Across	API	API	API	bridge	—
Transferência	spot ↔ perp ↔ dex	spot ↔ futuros	—	financiamento ↔ negociação	—	—
Saldo	saldo	saldo	saldo	saldo	saldo	simulado
Ordens abertas	ordens	ordens	ordens	ordens	—	—
Cancelar	cancelar	cancelar	cancelar	cancelar	—	—
Posições	posições	posições	—	posições	posições	simulado
Taxa de funding	—	—	—	perp funding_rate	—	—
Cotação histórica	—	—	—	—	—	cotação
PnL futuro	—	—	—	—	—	+1d/+2d/+4d/+7d
Arquivamentos SEC (datados)	—	—	—	—	—	lista de relatórios/anual/trimestral

Tratamento de Erros

Todos os erros são retornados como {"error": "..."}. Verifique se há uma chave error em cada resposta.
Se um comando falhar com saldo insuficiente ou símbolo inválido, repasse o erro claramente.
Se a exchange não estiver configurada, informe ao usuário quais credenciais são necessárias e ofereça-se para adicioná-las à configuração.

Referência de Comandos JSON

Dados de Mercado (`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"}

Negociação na Hyperliquid (`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"}

Negociação na Binance (`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"}

Negociação na OKX (`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"}

Notas sobre a OKX:

quote e orderbook são endpoints públicos — nenhuma chave de API é necessária.
A OKX usa IDs de instrumentos: spot = BTC-USDT, perp = BTC-USDT-SWAP. A CLI formata automaticamente a partir do símbolo.
A OKX tem contas funding (para depósitos/retiradas) e trading (unificada). Use transfer para mover entre elas.
A taxa de retirada é buscada automaticamente se --fee não for especificado.
Cancelar requer tanto inst_id (ex.: BTC-USDT) quanto order_id.

Negociação na Coinbase (`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..."}

Mercados de Previsão Polymarket (`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}

Notas:

list usa como padrão min_end_days: 3, filtrando mercados que fecham em até 3 dias (que muitas vezes têm probabilidades próximas de 1:0). Defina como 0 para ver todos os mercados.
list e quote são somente leitura e não requerem credenciais do Polymarket.
Comandos de negociação (buy, sell, deposit, withdraw) requerem wallet.private_key na configuração.
Use o slug do mercado (de list) ou o ID da condição como o valor de market.

Backtesting (`backtest`)

Importante: O binário backtest requer --at YYYY-MM-DD como uma flag CLI (não no corpo JSON). Nenhuma chave de API ou carteira é necessária.

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

// Preço histórico
{"command": "quote", "symbol": "BTC"}
{"command": "quote", "symbol": "AAPL"}
{"command": "quote", "symbol": "GOLD"}

// Negociações spot simuladas — retorna PnL futuro em +1/+2/+4/+7 dias
{"command": "buy", "symbol": "ETH", "amount": 0.5}
{"command": "buy", "symbol": "AAPL", "amount": 10, "price": 237}
{"command": "sell", "symbol": "BTC", "amount": 0.01, "price": 105000}

// Negociações perp simuladas — retorna PnL futuro alavancado
{"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}

// Arquivamentos SEC filtrados por data
{"command": "report_list", "symbol": "AAPL", "limit": 5}
{"command": "report_annual", "symbol": "TSLA"}
{"command": "report_quarterly", "symbol": "AAPL"}

// Gerenciamento de portfólio
{"command": "balance"}
{"command": "positions"}
{"command": "reset"}

// Notícia fictícia (notícias históricas não disponíveis)
{"command": "news", "symbol": "BTC"}

Notas:

Se price for omitido em compra/venda, o preço de fechamento histórico na data --at é usado automaticamente.
O estado do portfólio é persistido em ~/.fintool/backtest_portfolio.json. Use reset para limpar.
balance retorna cashBalance (apenas negociações spot), positions, totalTrades, leverageSettings.
A saída da negociação inclui um array pnl com preço futuro, PnL em dólar e PnL percentual em cada offset.
Fontes de dados: Yahoo Finance (ações, criptomoedas, commodities, índices) com fallback para CoinGecko para criptomoedas.

Fluxos de Trabalho

Fluxo de Trabalho 1: Negociação Spot

Objetivo: Pesquisar um símbolo e realizar uma negociação spot.

Passo 1 — Cotação de preço com análise:

{baseDir}/scripts/fintool --json '{"command":"quote","symbol":"BTC"}'

Retorna: preço, variações de 24h/7d/30d, tendência (altista/baixista/neutra), momentum, análise de volume, resumo.

Passo 1b — Verificar profundidade e spread do livro de ordens:

{baseDir}/scripts/hyperliquid --json '{"command":"orderbook","symbol":"BTC"}'

Retorna: bids, asks, spread, spreadPct, midPrice. Use para avaliar a liquidez antes de negociar.

Passo 2 — Verificar notícias recentes:

{baseDir}/scripts/fintool --json '{"command":"news","symbol":"BTC"}'

Passo 3 — Realizar a negociação:

# Comprar 0.01 BTC ao preço máximo de $95000 na Hyperliquid
{baseDir}/scripts/hyperliquid --json '{"command":"buy","symbol":"BTC","amount":0.01,"price":95000}'

# Ou na Binance
{baseDir}/scripts/binance --json '{"command":"buy","symbol":"BTC","amount":0.01,"price":95000}'

# Ou na Coinbase
{baseDir}/scripts/coinbase --json '{"command":"buy","symbol":"BTC","amount":0.01,"price":95000}'

# Ou na OKX
{baseDir}/scripts/okx --json '{"command":"buy","symbol":"BTC","amount":0.01,"price":95000}'

Passo 4 — Verificar:

{baseDir}/scripts/hyperliquid --json '{"command":"orders"}'
{baseDir}/scripts/hyperliquid --json '{"command":"balance"}'

Fluxo de Trabalho 2: Negociação de Futuros Perpétuos

Objetivo: Pesquisar e assumir uma posição alavancada por meio de futuros perpétuos.

Passo 1 — Obter cotação com funding/OI:

{baseDir}/scripts/hyperliquid --json '{"command":"quote","symbol":"ETH"}'

Passo 1b — Verificar profundidade e spread do livro de ordens perp:

{baseDir}/scripts/hyperliquid --json '{"command":"perp_orderbook","symbol":"ETH"}'

Passo 2 — Verificar preço spot para contexto:

{baseDir}/scripts/fintool --json '{"command":"quote","symbol":"ETH"}'

Passo 3 — Verificar notícias:

(conteúdo truncado para tradução)

second-state/fintool

O que é fintool?

Perguntar na sua IA favorita

Documentação

fintool — Skill de Negociação Financeira

Ferramentas

Verificação de Configuração (OBRIGATÓRIO — faça isso PRIMEIRO)

Capacidades das Exchanges

Tratamento de Erros

Referência de Comandos JSON

Dados de Mercado (`fintool`)

Negociação na Hyperliquid (`hyperliquid`)

Negociação na Binance (`binance`)

Negociação na OKX (`okx`)

Negociação na Coinbase (`coinbase`)

Mercados de Previsão Polymarket (`polymarket`)

Backtesting (`backtest`)

Fluxos de Trabalho

Fluxo de Trabalho 1: Negociação Spot

Fluxo de Trabalho 2: Negociação de Futuros Perpétuos

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Perguntar na sua IA favorita

Documentação

fintool — Skill de Negociação Financeira

Ferramentas

Verificação de Configuração (OBRIGATÓRIO — faça isso PRIMEIRO)

Capacidades das Exchanges

Tratamento de Erros

Referência de Comandos JSON

Dados de Mercado (fintool)

Negociação na Hyperliquid (hyperliquid)

Negociação na Binance (binance)

Negociação na OKX (okx)

Negociação na Coinbase (coinbase)

Mercados de Previsão Polymarket (polymarket)

Backtesting (backtest)

Fluxos de Trabalho

Fluxo de Trabalho 1: Negociação Spot

Fluxo de Trabalho 2: Negociação de Futuros Perpétuos

Habilidades Relacionadas

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me

Dados de Mercado (`fintool`)

Negociação na Hyperliquid (`hyperliquid`)

Negociação na Binance (`binance`)

Negociação na OKX (`okx`)

Negociação na Coinbase (`coinbase`)

Mercados de Previsão Polymarket (`polymarket`)

Backtesting (`backtest`)