second-state/fintool

fintool — Habilidad de Trading Financiero

Un conjunto de herramientas CLI para inteligencia de mercados y trading en múltiples exchanges. Cada exchange tiene su propio binario.

Herramientas

Binario	Propósito	Ruta
fintool	Inteligencia de mercados (cotizaciones, noticias, presentaciones SEC)	{baseDir}/scripts/fintool
hyperliquid	Trading en Hyperliquid (spot, perpetuo, HIP-3, depósitos)	{baseDir}/scripts/hyperliquid
binance	Trading en Binance (spot, perpetuo, depósitos)	{baseDir}/scripts/binance
coinbase	Trading en Coinbase (spot, depósitos)	{baseDir}/scripts/coinbase
okx	Trading en OKX (spot, perpetuo, depósitos, retiros)	{baseDir}/scripts/okx
polymarket	Mercados de predicción de Polymarket	{baseDir}/scripts/polymarket
backtest	Simulación histórica + PnL forward (sin claves necesarias)	{baseDir}/scripts/backtest

• Configuración: ~/.fintool/config.toml
• Modo: Siempre usa modo JSON — <binary> --json '<JSON>'. Toda la entrada y salida es JSON estructurado.
• Sin campo exchange: Cada binario maneja un exchange. No se necesita el parámetro "exchange".

Verificación de Configuración (OBLIGATORIO — haz esto PRIMERO)

Antes de ejecutar cualquier comando, verifica la configuración del usuario:

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

Si el archivo no existe, ejecuta:

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

Verifica los siguientes requisitos:

1. Clave API de OpenAI — Necesaria para cotizaciones enriquecidas (análisis de tendencia/momentum).

   • Busca: openai_api_key = "sk-..." (sin comentar) en [api_keys]
   • Si falta: Pídele al usuario su clave API de OpenAI, o indícale que la agregue en ~/.fintool/config.toml bajo [api_keys]

2. Al menos un exchange — Necesario para comandos de trading.

   • Hyperliquid: private_key o wallet_json + wallet_passcode en [wallet] (spot + perpetuos)
   • Binance: binance_api_key + binance_api_secret en [api_keys] (spot + perpetuos)
   • Coinbase: coinbase_api_key + coinbase_api_secret en [api_keys] (solo spot)
   • OKX: okx_api_key + okx_secret_key + okx_passphrase en [api_keys] (spot + perpetuos)
   • Polymarket: Usa wallet.private_key (igual que Hyperliquid) para trading en mercados de predicción
   • Si ninguno está configurado: Pregunta al usuario qué exchange quiere usar y solicita las credenciales.

Excepción — backtest: El binario de backtesting no requiere ninguna configuración — sin claves API, sin wallet. Usa datos públicos de Yahoo Finance y CoinGecko. Puedes usarlo de inmediato.

Si el usuario proporciona credenciales, edita ~/.fintool/config.toml directamente para agregarlas.

Capacidades de los Exchanges

Función	hyperliquid	binance	coinbase	okx	polymarket	backtest
Órdenes spot	comprar, vender	comprar, vender	comprar, vender	comprar, vender	—	comprar/vender simulados
Órdenes perpetuas	comprar/vender perpetuo	comprar/vender perpetuo	—	comprar/vender perpetuo	—	comprar/vender perpetuo simulados
Mercados de predicción	—	—	—	—	comprar, vender, listar, cotizar	—
Libro de órdenes	spot + perpetuo	spot + perpetuo	spot	spot + perpetuo	—	—
Depósito	Unit + Across	API	API	API	puente	—
Retiro	Bridge2 + Unit + Across	API	API	API	puente	—
Transferencia	spot ↔ perpetuo ↔ dex	spot ↔ futuros	—	financiamiento ↔ trading	—	—
Saldo	balance	balance	balance	balance	balance	simulado
Órdenes abiertas	orders	orders	orders	orders	—	—
Cancelar	cancel	cancel	cancel	cancel	—	—
Posiciones	positions	positions	—	positions	positions	simulado
Tasa de financiamiento	—	—	—	perpetuo funding_rate	—	—
Cotización histórica	—	—	—	—	—	quote
PnL forward	—	—	—	—	—	+1d/+2d/+4d/+7d
Presentaciones SEC	—	—	—	—	—	report list/annual/quarterly

Manejo de Errores

• Todos los errores se devuelven como {"error": "..."}. Verifica la clave error en cada respuesta.
• Si un comando falla con saldo insuficiente o símbolo inválido, transmite el error claramente.
• Si el exchange no está configurado, indícale al usuario qué credenciales necesita y ofrécete a agregarlas en la configuración.

Referencia de Comandos JSON

Datos 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"}

Trading en 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"}

Trading en 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"}

Trading en 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 de OKX:

• quote y orderbook son endpoints públicos — no se necesitan claves API.
• OKX usa IDs de instrumento: spot = BTC-USDT, perpetuo = BTC-USDT-SWAP. El CLI autoformatea desde el símbolo.
• OKX tiene cuentas funding (para depósitos/retiros) y trading (unificadas). Usa transfer para mover entre ellas.
• La tarifa de retiro se obtiene automáticamente si no se especifica --fee.
• Cancelar requiere tanto inst_id (ej. BTC-USDT) como order_id.

Trading en 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 Predicción 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 por defecto usa min_end_days: 3, filtrando mercados que cierran en 3 días (que a menudo tienen probabilidades cercanas a 1:0). Ponlo en 0 para ver todos los mercados.
• list y quote son de solo lectura y no requieren credenciales de Polymarket.
• Los comandos de trading (buy, sell, deposit, withdraw) requieren wallet.private_key en la configuración.
• Usa el slug del mercado (de list) o el ID de condición como valor de market.

Backtesting (backtest)

Importante: El binario backtest requiere --at YYYY-MM-DD como una bandera CLI (no en el cuerpo JSON). No se necesitan claves API ni wallet.

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

// Precio histórico
{"command": "quote", "symbol": "BTC"}
{"command": "quote", "symbol": "AAPL"}
{"command": "quote", "symbol": "GOLD"}

// Operaciones spot simuladas — devuelve PnL forward a +1/+2/+4/+7 días
{"command": "buy", "symbol": "ETH", "amount": 0.5}
{"command": "buy", "symbol": "AAPL", "amount": 10, "price": 237}
{"command": "sell", "symbol": "BTC", "amount": 0.01, "price": 105000}

// Operaciones perpetuas simuladas — devuelve PnL forward apalancado
{"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}

// Presentaciones SEC filtradas por fecha
{"command": "report_list", "symbol": "AAPL", "limit": 5}
{"command": "report_annual", "symbol": "TSLA"}
{"command": "report_quarterly", "symbol": "AAPL"}

// Gestión de cartera
{"command": "balance"}
{"command": "positions"}
{"command": "reset"}

// Noticias (no hay noticias históricas disponibles)
{"command": "news", "symbol": "BTC"}

Notas:

• Si se omite price en compra/venta, se usa automáticamente el precio de cierre histórico en la fecha --at.
• El estado de la cartera persiste en ~/.fintool/backtest_portfolio.json. Usa reset para limpiarlo.
• balance devuelve cashBalance (solo operaciones spot), positions, totalTrades, leverageSettings.
• La salida de cada operación incluye un arreglo pnl con precio forward, PnL en dólares y porcentaje de PnL en cada desfase.
• Fuentes de datos: Yahoo Finance (acciones, cripto, materias primas, índices) con fallback a CoinGecko para cripto.

Flujos de Trabajo

Flujo 1: Trading Spot

Objetivo: Investigar un símbolo y ejecutar una operación spot.

Paso 1 — Cotizar precio con análisis:

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

Devuelve: precio, cambios en 24h/7d/30d, tendencia (alcista/neutral/bajista), momentum, análisis de volumen, resumen.

Paso 1b — Ver profundidad del libro de órdenes y spread:

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

Devuelve: bids, asks, spread, spreadPct, midPrice. Úsalo para evaluar liquidez antes de operar.

Paso 2 — Ver noticias recientes:

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

Paso 3 — Ejecutar la operación:

# Comprar 0.01 BTC a precio máximo $95000 en Hyperliquid
{baseDir}/scripts/hyperliquid --json '{"command":"buy","symbol":"BTC","amount":0.01,"price":95000}'

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

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

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

Paso 4 — Verificar:

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

Flujo 2: Trading de Futuros Perpetuos

Objetivo: Investigar y tomar una posición apalancada mediante futuros perpetuos.

Paso 1 — Obtener cotización con financiamiento/OI:

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

Paso 1b — Ver profundidad del libro de órdenes perpetuas y spread:

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

Paso 2 — Ver precio spot para contexto:

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

Paso 3 — Ver noticias:

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

Paso 4 — Configurar apalancamiento:

# Apalancamiento 5x cruzado en Hyperliquid
{baseDir}/scripts/hyperliquid --json '{"command":"perp_leverage","symbol":"ETH","leverage":5,"cross":true}'

# Apalancamiento 5x en Binance (por defecto cruzado)
{baseDir}/scripts/binance --json '{"command":"perp_leverage","symbol":"ETH","leverage":5}'

# Apalancamiento 5x cruzado en OKX
{baseDir}/scripts/okx --json '{"command":"perp_leverage","symbol":"ETH","leverage":5,"cross":true}'

Paso 5 — Ejecutar la operación perpetua:

# Comprar 0.5 ETH perpetuo a $3800 en Hyperliquid
{baseDir}/scripts/hyperliquid --json '{"command":"perp_buy","symbol":"ETH","amount":0.5,"price":3800}'

# Vender 0.5 ETH perpetuo a $4000 (con orden close) en Hyperliquid
{baseDir}/scripts/hyperliquid --json '{"command":"perp_sell","symbol":"ETH","amount":0.5,"price":4000,"close":true}'

# Comprar 0.5 ETH perpetuo en Binance
{baseDir}/scripts/binance --json '{"command":"perp_buy","symbol":"ETH","amount":0.5,"price":3800}'

Paso 6 — Verificar posiciones:

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

Flujo 3: Mercados de Predicción

Objetivo: Encontrar y operar un mercado en Polymarket.

Paso 1 — Listar mercados disponibles:

{baseDir}/scripts/polymarket --json '{"command":"list","query":"bitcoin","limit":5}'

Devuelve: slug, condición, fechas de cierre, resultados, volumen.

Paso 2 — Obtener cotización de un mercado específico:

{baseDir}/scripts/polymarket --json '{"command":"quote","market":"will-bitcoin-hit-100k"}'

Devuelve: mejor oferta, mejor demanda, precio medio.

Paso 3 — Comprar/Vender:

# Comprar 10 contratos de "Sí" a $0.65 cada uno
{baseDir}/scripts/polymarket --json '{"command":"buy","market":"will-bitcoin-hit-100k","outcome":"yes","amount":10,"price":0.65}'

# Vender 10 contratos de "Sí" a $0.70
{baseDir}/scripts/polymarket --json '{"command":"sell","market":"will-bitcoin-hit-100k","outcome":"yes","amount":10,"price":0.70}'

Paso 4 — Verificar posiciones y saldo:

{baseDir}/scripts/polymarket --json '{"command":"positions"}'
{baseDir}/scripts/polymarket --json '{"command":"balance"}'

Flujo 4: Backtesting

Objetivo: Simular operaciones históricamente y ver el PnL forward.

Paso 1 — Establecer la fecha y consultar:

{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"quote","symbol":"BTC"}'

Devuelve: precio de cierre histórico.

Paso 2 — Ejecutar operaciones simuladas:

# Comprar spot (usando precio de cierre automático si se omite price)
{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"buy","symbol":"ETH","amount":0.5}'

# O con un precio específico
{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"buy","symbol":"AAPL","amount":10,"price":237}'

# Vender cripto
{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"sell","symbol":"BTC","amount":0.01,"price":105000}'

Paso 3 — Ver cartera y PnL:

{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"balance"}'
{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"positions"}'

Paso 4 — Reiniciar para nueva simulación:

{baseDir}/scripts/backtest --at 2024-01-15 --json '{"command":"reset"}'