|
| 1 | +# CLAUDE.md — Fintool Development Guide |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +Fintool is a suite of Rust CLI tools for agentic trading and market intelligence across multiple exchanges. Each exchange has its own dedicated binary. All CLIs support `--json` mode for scripting and AI agent integration. |
| 6 | + |
| 7 | +**Supported exchanges**: Hyperliquid, Binance, Coinbase, OKX, Polymarket (prediction markets) |
| 8 | +**Asset classes**: Crypto, stocks, commodities, indices, prediction markets |
| 9 | +**License**: MIT |
| 10 | + |
| 11 | +## Repository Structure |
| 12 | + |
| 13 | +``` |
| 14 | +fintool/ |
| 15 | +├── src/ |
| 16 | +│ ├── lib.rs # Library root — exports all modules |
| 17 | +│ ├── bin/ # Binary entry points (one per exchange + fintool + backtest) |
| 18 | +│ │ ├── fintool.rs # Market intelligence CLI (quotes, news, SEC filings) |
| 19 | +│ │ ├── hyperliquid.rs # Hyperliquid (spot, perp, HIP-3, deposits, withdrawals) |
| 20 | +│ │ ├── binance.rs # Binance (spot, perp, deposits, withdrawals) |
| 21 | +│ │ ├── coinbase.rs # Coinbase (spot, deposits, withdrawals) |
| 22 | +│ │ ├── okx.rs # OKX (spot, perp, deposits, withdrawals, transfers) |
| 23 | +│ │ ├── polymarket.rs # Polymarket (prediction market trading) |
| 24 | +│ │ └── backtest.rs # Historical simulation with forward PnL analysis |
| 25 | +│ ├── commands/ # Shared command implementations used by binaries |
| 26 | +│ │ ├── quote.rs # Multi-source price quotes + LLM enrichment |
| 27 | +│ │ ├── news.rs # News via Google News RSS |
| 28 | +│ │ ├── report.rs # SEC EDGAR filings |
| 29 | +│ │ ├── order.rs # Spot order placement |
| 30 | +│ │ ├── perp.rs # Perpetual futures trading |
| 31 | +│ │ ├── deposit.rs # Deposit flows (bridging, address generation) |
| 32 | +│ │ ├── withdraw.rs # Withdrawal flows |
| 33 | +│ │ ├── balance.rs # Account balances |
| 34 | +│ │ ├── positions.rs # Open positions |
| 35 | +│ │ ├── orders.rs # Order listing |
| 36 | +│ │ ├── cancel.rs # Order cancellation |
| 37 | +│ │ ├── orderbook.rs # Orderbook depth |
| 38 | +│ │ ├── transfer.rs # Internal account transfers |
| 39 | +│ │ ├── options.rs # Options trading |
| 40 | +│ │ ├── predict.rs # Polymarket prediction operations |
| 41 | +│ │ └── bridge_status.rs # Cross-chain bridge status |
| 42 | +│ ├── config.rs # Config loading (~/.fintool/config.toml) |
| 43 | +│ ├── signing.rs # Hyperliquid EIP-712 wallet signing |
| 44 | +│ ├── hip3.rs # HIP-3 builder-deployed perps (collateral tokens) |
| 45 | +│ ├── backtest.rs # Historical data providers + simulated portfolio |
| 46 | +│ ├── binance.rs # Binance REST API client |
| 47 | +│ ├── coinbase.rs # Coinbase API client |
| 48 | +│ ├── okx.rs # OKX API client |
| 49 | +│ ├── polymarket.rs # Polymarket SDK helpers |
| 50 | +│ ├── bridge.rs # Across Protocol cross-chain bridging |
| 51 | +│ ├── unit.rs # HyperUnit bridge (ETH/BTC/SOL) |
| 52 | +│ └── format.rs # Color formatting + number formatting helpers |
| 53 | +├── tests/ # E2E shell script tests organized by exchange |
| 54 | +│ ├── helpers.sh # Shared test utilities (build checks, assertions) |
| 55 | +│ ├── backtest/ # Backtest CLI tests |
| 56 | +│ ├── hyperliquid/ # Hyperliquid E2E tests |
| 57 | +│ ├── binance/ # Binance E2E tests |
| 58 | +│ ├── okx/ # OKX E2E tests |
| 59 | +│ └── polymarket/ # Polymarket E2E tests |
| 60 | +├── examples/ # Complete example scripts (see Examples section below) |
| 61 | +│ ├── funding_arb/ # Funding rate arbitrage bot |
| 62 | +│ ├── metal_pair/ # Metal pairs trading bot |
| 63 | +│ ├── catalyst_hedger/ # Prediction market hedging bot |
| 64 | +│ └── backtest/ # Historical backtest strategy examples |
| 65 | +├── skills/ # AI agent skill definitions (for OpenClaw / Claude) |
| 66 | +│ ├── SKILL.md # Main skill definition (commands, workflows, capabilities) |
| 67 | +│ ├── install.md # Installation guide for agents |
| 68 | +│ └── bootstrap.sh # Automated installer script |
| 69 | +├── docs/ # Additional documentation and screenshots |
| 70 | +├── .github/workflows/ # CI/CD (ci.yml for lint+test, release.yml for builds) |
| 71 | +├── Cargo.toml # Rust dependencies and binary targets |
| 72 | +├── config.toml.default # Default config template |
| 73 | +└── README.md # User-facing documentation |
| 74 | +``` |
| 75 | + |
| 76 | +## Building |
| 77 | + |
| 78 | +```bash |
| 79 | +# Debug build |
| 80 | +cargo build |
| 81 | + |
| 82 | +# Release build (used for testing and deployment) |
| 83 | +cargo build --release |
| 84 | +``` |
| 85 | + |
| 86 | +Binaries are output to `target/release/` (or `target/debug/`): |
| 87 | +`fintool`, `hyperliquid`, `binance`, `coinbase`, `okx`, `polymarket`, `backtest` |
| 88 | + |
| 89 | +## Testing |
| 90 | + |
| 91 | +### Lint (must pass before submitting PRs) |
| 92 | + |
| 93 | +```bash |
| 94 | +# Format check — CI runs this exact command |
| 95 | +cargo fmt -- --check |
| 96 | + |
| 97 | +# Auto-fix formatting |
| 98 | +cargo fmt |
| 99 | + |
| 100 | +# Clippy — CI runs with warnings as errors |
| 101 | +cargo clippy --release -- -D warnings |
| 102 | +``` |
| 103 | + |
| 104 | +### Unit tests |
| 105 | + |
| 106 | +```bash |
| 107 | +cargo test --release |
| 108 | +``` |
| 109 | + |
| 110 | +### E2E tests |
| 111 | + |
| 112 | +Shell script tests in `tests/` organized by exchange. Each exchange directory has an `e2e_*.sh` script that runs the full workflow: |
| 113 | + |
| 114 | +```bash |
| 115 | +# Run backtest E2E tests (no API keys needed) |
| 116 | +bash tests/backtest/e2e_backtest.sh |
| 117 | + |
| 118 | +# Run individual tests |
| 119 | +bash tests/backtest/quote_btc.sh |
| 120 | +bash tests/backtest/buy_spot.sh |
| 121 | +``` |
| 122 | + |
| 123 | +Exchange tests (hyperliquid, binance, okx, polymarket) require API keys configured in `~/.fintool/config.toml`. |
| 124 | + |
| 125 | +### Examples |
| 126 | + |
| 127 | +```bash |
| 128 | +# Backtest examples (no API keys needed) |
| 129 | +python3 examples/backtest/covid_crash_hedge.py |
| 130 | +python3 examples/backtest/nvda_earnings_alpha.py |
| 131 | + |
| 132 | +# Trading bot examples (require API keys) |
| 133 | +python3 examples/funding_arb/bot.py --dry-run |
| 134 | +python3 examples/metal_pair/bot.py --dry-run |
| 135 | +``` |
| 136 | + |
| 137 | +## Examples Directory Conventions |
| 138 | + |
| 139 | +The `examples/` directory contains **complete, runnable examples and use cases**. Each example must follow these rules: |
| 140 | + |
| 141 | +1. **Every example directory MUST have a `README.md`** explaining the strategy, setup, usage, configuration, and dependencies. |
| 142 | + |
| 143 | +2. **Scripts must be in Python** (3.10+, stdlib only — no third-party packages). Use `subprocess` to call CLI binaries in `--json` mode. Do NOT call web APIs directly from Python. |
| 144 | + |
| 145 | +3. **Use CLI binaries, not raw APIs.** If an example needs to call a web API that isn't wrapped in a CLI binary, that's a sign the CLI is missing a feature. Add the feature to the CLI first, then call it from Python. |
| 146 | + |
| 147 | +4. **Follow existing patterns** — see `examples/funding_arb/bot.py` for the canonical pattern: |
| 148 | + - `SCRIPT_DIR` / `REPO_DIR` path resolution |
| 149 | + - `cli(cmd, binary)` helper using `subprocess.run([binary, "--json", json.dumps(cmd)])` |
| 150 | + - `argparse` for CLI flags (binary path overrides, `--dry-run`, etc.) |
| 151 | + - `DEFAULTS` dict with environment variable overrides |
| 152 | + |
| 153 | +## PR and Documentation Requirements |
| 154 | + |
| 155 | +### Every new feature or breaking change MUST update: |
| 156 | + |
| 157 | +1. **`README.md`** — Add/update command reference, capability matrix, JSON mode examples, and any affected quick guides. |
| 158 | + |
| 159 | +2. **`skills/SKILL.md`** — Update the tools table, exchange capabilities matrix, JSON command reference, and workflows so AI agents can discover and use the new feature. |
| 160 | + |
| 161 | +3. **`skills/bootstrap.sh`** and **`skills/install.md`** — If adding a new binary, add it to the binary download lists. |
| 162 | + |
| 163 | +### Submitting changes |
| 164 | + |
| 165 | +- **Do not push directly to `main`**. Create a feature branch and submit a PR. |
| 166 | +- All PRs must pass CI: `cargo fmt -- --check` and `cargo clippy --release -- -D warnings` |
| 167 | +- Sign commits with DCO: `Signed-off-by: Michael Yuan <michael@secondstate.io>` |
| 168 | +- Add co-author: `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>` |
| 169 | + |
| 170 | +## Key Architecture Notes |
| 171 | + |
| 172 | +- **One binary per exchange** — no `--exchange` flag. Use the right binary (`hyperliquid`, `binance`, etc.). |
| 173 | +- **All I/O is JSON** in `--json` mode. Every binary supports `<binary> --json '<JSON>'` for programmatic use. |
| 174 | +- **Config file**: `~/.fintool/config.toml` — API keys, wallet credentials, exchange settings. |
| 175 | +- **`backtest` is config-free** — no API keys or wallet needed. Uses public Yahoo Finance / CoinGecko data. |
| 176 | +- **HIP-3 collateral tokens** — each HIP-3 perp dex has its own collateral token (e.g., USDT0 for `cash` dex, USDC for `xyz`/`abcd`). See `src/hip3.rs` and `src/signing.rs`. |
0 commit comments