Skip to content

CLAUDE.md

Latest commit

 

History

History
184 lines (143 loc) · 8.76 KB

CLAUDE.md

File metadata and controls

184 lines (143 loc) · 8.76 KB

CLAUDE.md — Fintool Development Guide

Project Overview

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.

Supported exchanges: Hyperliquid, Binance, Coinbase, OKX, Polymarket (prediction markets) Asset classes: Crypto, stocks, commodities, indices, prediction markets License: MIT

Repository Structure

fintool/
├── src/
│   ├── lib.rs              # Library root — exports all modules
│   ├── bin/                 # Binary entry points (one per exchange + fintool + backtest)
│   │   ├── fintool.rs       # Market intelligence CLI (quotes, news, SEC filings)
│   │   ├── hyperliquid.rs   # Hyperliquid (spot, perp, HIP-3, deposits, withdrawals)
│   │   ├── binance.rs       # Binance (spot, perp, deposits, withdrawals)
│   │   ├── coinbase.rs      # Coinbase (spot, deposits, withdrawals)
│   │   ├── okx.rs           # OKX (spot, perp, deposits, withdrawals, transfers)
│   │   ├── polymarket.rs    # Polymarket (prediction market trading)
│   │   └── backtest.rs      # Historical simulation with forward PnL analysis
│   ├── commands/            # Shared command implementations used by binaries
│   │   ├── quote.rs         # Multi-source price quotes + LLM enrichment
│   │   ├── news.rs          # News via Google News RSS
│   │   ├── report.rs        # SEC EDGAR filings
│   │   ├── order.rs         # Spot order placement
│   │   ├── perp.rs          # Perpetual futures trading
│   │   ├── deposit.rs       # Deposit flows (bridging, address generation)
│   │   ├── withdraw.rs      # Withdrawal flows
│   │   ├── balance.rs       # Account balances
│   │   ├── positions.rs     # Open positions
│   │   ├── orders.rs        # Order listing
│   │   ├── cancel.rs        # Order cancellation
│   │   ├── orderbook.rs     # Orderbook depth
│   │   ├── transfer.rs      # Internal account transfers
│   │   ├── options.rs       # Options trading
│   │   ├── predict.rs       # Polymarket prediction operations
│   │   └── bridge_status.rs # Cross-chain bridge status
│   ├── config.rs            # Config loading (~/.fintool/config.toml)
│   ├── signing.rs           # Hyperliquid EIP-712 wallet signing
│   ├── hip3.rs              # HIP-3 builder-deployed perps (collateral tokens)
│   ├── backtest.rs          # Historical data providers + simulated portfolio
│   ├── binance.rs           # Binance REST API client
│   ├── coinbase.rs          # Coinbase API client
│   ├── okx.rs               # OKX API client
│   ├── polymarket.rs        # Polymarket SDK helpers
│   ├── bridge.rs            # Across Protocol cross-chain bridging
│   ├── unit.rs              # HyperUnit bridge (ETH/BTC/SOL)
│   └── format.rs            # Color formatting + number formatting helpers
├── tests/                   # E2E shell script tests organized by exchange
│   ├── helpers.sh           # Shared test utilities (build checks, assertions)
│   ├── backtest/            # Backtest CLI tests
│   ├── hyperliquid/         # Hyperliquid E2E tests
│   ├── binance/             # Binance E2E tests
│   ├── okx/                 # OKX E2E tests
│   └── polymarket/          # Polymarket E2E tests
├── examples/                # Complete example scripts (see Examples section below)
│   ├── funding_arb/         # Funding rate arbitrage bot
│   ├── metal_pair/          # Metal pairs trading bot
│   ├── catalyst_hedger/     # Prediction market hedging bot
│   └── backtest/            # Historical backtest strategy examples
├── skills/                  # AI agent skill definitions (for OpenClaw / Claude)
│   ├── SKILL.md             # Main skill definition (commands, workflows, capabilities)
│   ├── install.md           # Installation guide for agents
│   └── bootstrap.sh         # Automated installer script
├── docs/                    # Additional documentation and screenshots
├── .github/workflows/       # CI/CD (ci.yml for lint+test, release.yml for builds)
├── Cargo.toml               # Rust dependencies and binary targets
├── config.toml.default      # Default config template
└── README.md                # User-facing documentation

Building

# Debug build
cargo build

# Release build (used for testing and deployment)
cargo build --release

Binaries are output to target/release/ (or target/debug/): fintool, hyperliquid, binance, coinbase, okx, polymarket, backtest

Testing

Lint (must pass before submitting PRs)

# Format check — CI runs this exact command
cargo fmt -- --check

# Auto-fix formatting
cargo fmt

# Clippy — CI runs with warnings as errors
cargo clippy --release -- -D warnings

Unit tests

cargo test --release

E2E tests

Shell script tests in tests/ organized by exchange. Each exchange directory has an e2e_*.sh script that runs the full workflow:

# Run backtest E2E tests (no API keys needed)
bash tests/backtest/e2e_backtest.sh

# Run individual tests
bash tests/backtest/quote_btc.sh
bash tests/backtest/buy_spot.sh

Exchange tests (hyperliquid, binance, okx, polymarket) require API keys configured in ~/.fintool/config.toml.

Examples

# Backtest examples (no API keys needed)
python3 examples/backtest/covid_crash_hedge.py
python3 examples/backtest/nvda_earnings_alpha.py

# Trading bot examples (require API keys)
python3 examples/funding_arb/bot.py --dry-run
python3 examples/metal_pair/bot.py --dry-run

Examples Directory Conventions

The examples/ directory contains complete, runnable examples and use cases. Each example must follow these rules:

  1. Every example directory MUST have a README.md explaining the strategy, setup, usage, configuration, and dependencies.

  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.

  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.

  4. Follow existing patterns — see examples/funding_arb/bot.py for the canonical pattern:

    • SCRIPT_DIR / REPO_DIR path resolution
    • cli(cmd, binary) helper using subprocess.run([binary, "--json", json.dumps(cmd)])
    • argparse for CLI flags (binary path overrides, --dry-run, etc.)
    • DEFAULTS dict with environment variable overrides

PR and Documentation Requirements

Every new feature or breaking change MUST update:

  1. README.md — Add/update command reference, capability matrix, JSON mode examples, and any affected quick guides.

  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.

  3. skills/bootstrap.sh and skills/install.md — If adding a new binary, add it to the binary download lists.

Submitting changes

  • Do not push directly to main. Create a feature branch and submit a PR.
  • All PRs must pass CI: cargo fmt -- --check and cargo clippy --release -- -D warnings
  • Sign commits with DCO: Signed-off-by: Michael Yuan <michael@secondstate.io>
  • Add co-author: Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Creating a release

  1. Bump the version in Cargo.toml (e.g., "0.1.5" → "0.1.6")
  2. Commit: chore: bump version to 0.1.6
  3. Tag: git tag v0.1.6 && git push origin v0.1.6
  4. Create the GitHub release: gh release create v0.1.6 --title "v0.1.6" --notes "..."
  5. The CI release workflow automatically builds and attaches platform binaries

Key Architecture Notes

  • One binary per exchange — no --exchange flag. Use the right binary (hyperliquid, binance, etc.).
  • All I/O is JSON in --json mode. Every binary supports <binary> --json '<JSON>' for programmatic use.
  • Config file: ~/.fintool/config.toml — API keys, wallet credentials, exchange settings.
  • backtest is config-free — no API keys or wallet needed. Uses public Yahoo Finance / CoinGecko data.
  • 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.