convez.ai
PluginFinanceiroAvançado
aithinkers

Auto Oil Trader

aithinkers/auto-oiltrader

Trading autônomo de opções de petróleo com IA e regras determinísticas

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de trading assistido por IA para opções de crude oil (futuros NYMEX) com regras determinísticas de saída, promoção de estratégias em cinco níveis e gates de segurança com interferência humana. Integrado com Interactive Brokers e Claude, roda em modo paper (simulado) com dashboard Streamlit e CLI para controle operacional.

Instalação

$npx convez-ai aithinkers/auto-oiltrader

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
62%
Último commit
há 7 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Trading sistemático de derivativos (crude oil futures) com aprovação humana
  • Monitoramento automático de estratégias de opções (spreads, iron condors) com P&L em tempo real
  • Backtesting e análise de desempenho semanal com narrativas geradas por LLM

Veredito

Plugin robusto para quem precisa automatizar avaliação e execução de estratégias de opções, mas com forte requisito de conhecimento técnico (Python 3.12+, IB Gateway, APIs) e expertise em trading. Paper trading está maduro; modos live e dashboard não estão prontos para produção.

README

A tradução para o português deste README ainda está na fila.

Autonomous Oil Trader

An LLM-assisted, rules-driven trading system for crude oil futures options (NYMEX CL / LO) built on Interactive Brokers, SQLite, and Claude. Paper-first design with five-tier strategy promotion, deterministic exit rules, and human-in-the-loop safety gates.

Status: Paper trading is fully operational. Draft/live modes, the REST API, and dashboard approval workflows are scaffolded but not yet complete. See Current Limitations below.

What it does

  • Streams live option chain snapshots from IB every 2-5 minutes
  • Evaluates multiple option strategies (credit spreads, debit spreads, iron condors) against configurable entry rules
  • Opens paper (simulated) positions with full leg detail and greek tracking
  • Marks positions every tick and evaluates rule-based exits: profit targets, stop losses, time stops, vol-crush exits, trailing stops, short-strike defense, and wide-spread deferral
  • LLM agents narrate trade rationale, classify news, generate weekly performance reviews, and propose strategy variants -- but never make exit decisions
  • Streamlit dashboard for monitoring positions, P&L, recommendations, and summaries
  • CLI (tradectl) for status, halt, mode changes, and DB management

Quick start

git clone https://github.com/aithinkers/auto-oiltrader.git
cd autonomous-oiltrader

# Install dependencies
uv sync                        # or: pip install -e ".[dev]"

# Configure
cp .env.example .env           # fill in IB + Anthropic credentials
vi config/settings.toml        # review capital limits, IB connection

# Initialize database
python -m cli.tradectl init-db
python -m cli.tradectl migrate
python -m cli.tradectl status  # verify: mode=paper, $20k starting capital

# Start the system
python -m daemons.main --log-level INFO &
streamlit run interfaces/dashboard/app.py --server.port 8511 &

See docs/install.md for full setup including IB Gateway/TWS configuration.

Prerequisites

  • Python 3.12+
  • Interactive Brokers account with TWS or IB Gateway
  • Anthropic API key (for LLM agents -- narration, news, weekly review)
  • macOS or Linux

Architecture

┌─────────────────────────────────────────────────────┐
│                  daemons.main                        │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│  │  stream   │ │  trader   │ │ position │ │summary │ │
│  │  daemon   │ │  daemon   │ │ manager  │ │  izer  │ │
│  └─────┬────┘ └─────┬────┘ └─────┬────┘ └───┬────┘ │
└────────┼────────────┼────────────┼───────────┼──────┘
         │            │            │           │
         ▼            ▼            ▼           ▼
    ┌─────────────────────────────────────────────┐
    │          SQLite WAL (data/trader.db)         │
    └─────────────────────────────────────────────┘
         ▲            ▲            ▲
         │            │            │
    ┌────┴───┐  ┌─────┴────┐  ┌───┴──────┐
    │  CLI   │  │Dashboard │  │  Agents  │
    │tradectl│  │Streamlit │  │ (Claude) │
    └────────┘  └──────────┘  └──────────┘

A single daemons.main process runs 4 worker threads sharing one SQLite WAL-mode database:

  • Stream daemon -- connects to IB, writes option chain snapshots (parquet) and DB updates
  • Trader daemon -- evaluates strategies, generates recommendations, opens paper positions
  • Position manager -- marks open positions, computes greeks, runs exit rules every tick
  • Summarizer -- generates periodic P&L digests with optional LLM narration

LLM agents (narrator, news classifier, trade analyst, weekly evaluator) read the DB, call Claude, and write recommendations/commentary back. They advise -- they don't decide.

Strategies

Defined in config/strategies.yaml. Each strategy has entry rules, exit parameters, and a promotion tier.

StrategyStructureTierDescription
iron_condor_range_loIron condorpaperRange-bound premium collection
bull_put_credit_loBull put spreadpaperBullish credit spread
bear_call_credit_loBear call spreadpaperBearish credit spread
bull_call_debit_loBull call spreadexperimentalBullish debit spread
bear_put_debit_loBear put spreadexperimentalBearish debit spread
butterfly_pin_loButterflyexperimentalPin-risk play
vol_crush_post_eventShort premiumexperimentalPost-event IV collapse
long_strangle_eventLong strangleexperimentalPre-event vol play
eia_wednesdayStrangleexperimentalEIA report straddle

See docs/strategies.md for details on adding and promoting strategies.

Exit rules

All exits are deterministic and rules-based (no LLM in the loop). Evaluated in priority order:

  1. Time stop -- close at configurable DTE threshold
  2. Short-strike defense -- close if underlying breaches short strike buffer (credit trades)
  3. Vol-crush exit -- close profitable credit trades when IV drops significantly from entry
  4. Trailing stop -- lock in profits after reaching activation threshold
  5. Base target/stop -- percentage-based profit target and stop loss
  6. Wide-spread deferral -- delay profit-taking when bid-ask spread is too wide (never defers stops)

Parameters are per-strategy in config/strategies.yaml. Existing positions without entry context gracefully fall back to base rules.

Five-tier strategy promotion

experimental --> shadow --> paper --> draft --> live

Promotion requires human approval at every gate, backed by statistical evidence (Sharpe, drawdown, hit rate). The system proposes; the human decides.

Safety

  • Capital boundary: sizing derived from starting_capital, never current equity
  • Position limits: max 10% risk per position, 50% total book
  • Daily loss halt: auto-halts at configurable drawdown (default -$1,000)
  • Emergency stop: tradectl halt works in any mode, immediately
  • No market orders: combos always use limit orders
  • Cost tracking: every commission and LLM API call logged to costs table

See docs/safety.md for the full safety model.

Dashboard

Streamlit app with 8 pages:

PageWhat it shows
HomeMode, balance, daily P&L, open position count
OverviewEquity curve, system status
PositionsOpen/closing/closed positions with leg details, marks, greeks
RecommendationsStrategy signals, approve/reject UI
StrategiesStrategy library, tiers, performance
News & ObservationsNews feed, user observations
FindingsWeekly performance reports
CostsCommission + LLM spend tracker
SummariesPeriodic P&L digests with AI commentary

CLI

tradectl status              # system mode, capital, daily P&L
tradectl positions           # list open positions
tradectl recommendations     # view pending recommendations
tradectl mode <name>         # set mode (paper|draft|live|halt)
tradectl halt                # emergency stop
tradectl unhalt              # resume in paper mode
tradectl init-db             # initialize database (non-destructive)
tradectl migrate             # apply pending schema migrations
tradectl observe <text>      # submit a market observation
tradectl costs [--month]     # show cost ledger

Project layout

autonomous-oiltrader/
├── core/           Business logic (risk, pricing, sizing, combos, DB)
├── strategies/     Strategy implementations (base class + 9 strategies)
├── daemons/        Worker threads (stream, trader, positions, summarizer)
├── agents/         LLM-powered agents (narrator, critic, evaluator, ...)
├── skills/         Markdown prompt templates loaded by agents
├── interfaces/     Dashboard (Streamlit), API (FastAPI), MCP server
├── cli/            tradectl command-line tool
├── services/       systemd / launchd unit files
├── config/         Settings, strategies, patterns, news sources
├── db/             SQLite schema, seed data, migrations
├── tests/          pytest test suite
└── docs/           Architecture, install, runbook, safety, strategies

Configuration

FilePurpose
.envSecrets (IB credentials, API keys) -- never committed
config/settings.tomlCapital limits, IB connection, mode, display timezone
config/strategies.yamlStrategy definitions, parameters, tiers
config/patterns.yamlTechnical pattern definitions
config/news_sources.yamlRSS/EIA/CME feed URLs

Docs

  • Architecture -- system design, components, phasing
  • Install -- new machine setup, IB configuration
  • Runbook -- operational procedures, failure recovery
  • Safety -- capital limits, hard rules, failure modes
  • Strategies -- strategy catalog, promotion criteria

Tests

python -m pytest -q           # run full suite
python -m pytest tests/test_risk.py -xvs   # run specific test file

Current limitations

This project is under active development. The following features are documented but not yet fully implemented:

FeatureStatus
Paper mode (full cycle)Working
Rules-based exit engine (6 rule families)Working
Streamlit dashboard (monitoring)Working
CLI (tradectl)Working
Strategy tier enforcementWorking (experimental/shadow tiers blocked from execution)
Draft mode (staged orders + human approval)Working for approval tracking; broker-submit path not yet built
Live mode (IB order submission)Not implemented
REST API (interfaces/api.py)Working (status, positions, recommendations, approve/reject, halt, mode, observations)
Dashboard approve/reject buttonsWorking via CLI, API, and dashboard
News-driven DTE policy fieldsPartially wired -- realized_vol_10d and news context not yet populated
Reconciler (IB <-> DB sync)Scaffolded
Learning loop (weekly promotion)Scaffolded

Contributions welcome -- see CONTRIBUTING.md.

Disclaimer

This software is provided as-is for educational and research purposes. It is not financial advice. Trading futures and options involves substantial risk of loss. Use at your own risk. The authors are not responsible for any financial losses incurred through use of this software.

License

MIT License. See LICENSE.

Want something like this for your own strategies?

This repo is a basic reference design, contact us for demo of full working session in live. If you want a tailored version -- different asset class, different broker, your own strategies, production-grade risk controls, or a walkthrough of how this one works -- we can help.

AI Thinkers -- ai_trading@aithinkers.com

Ver o original no GitHub

Bom para

Relacionados