bullet-bots AGENTS.md

bullet-bots

Event-driven trading bot framework in Rust. Typed event bus, typed feeds per event kind, strategies implemented as actors. Pluggable exchange adapters and strategies connect through a shared harness that handles lifecycle, shutdown, and multi-source event dispatch.

Build & Test

cargo build                # full workspace
cargo nextest run          # unit + integration tests (default runner)
cargo test --doc           # doctests only (nextest doesn't run these)
cargo clippy               # lints (pedantic enabled)
cargo +nightly fmt         # format (nightly required for import grouping)

First-time setup:

cargo install cargo-nextest --locked

The nextest config lives at .config/nextest.toml. CI should use the ci profile (cargo nextest run --profile ci) which retries once and doesn't fail-fast.

Validate a config without connecting:

cargo run --bin bb-bot -- validate --config config/simple-mm-example.toml

Generate a keypair (first time):

cargo run --bin bb-bot -- keygen --network testnet
# → writes ~/.config/bullet/id.key (base58 secret, 0600), prints address + faucet curl

Fund and onboard the account (first time). The faucet credits the on-chain wallet (testnet only — on mainnet you fund the wallet with real bridged/deposited assets instead); deposit then moves funds into the perp margin account and initializes the trading account. Skipping the deposit makes order placement fail with user_variants not found:

# Run the faucet curl printed by keygen, then:
cargo run --bin bb-bot -- deposit --network testnet --asset USDC --amount 5000

Run a bot (default: reads ~/.config/bullet/id.key):

cargo run --bin bb-bot -- run --config config/simple-mm-example.toml

Or point at an explicit key file / pass a key string for CI:

export BB_BULLET_KEY_FILE="/path/to/id.key"          # preferred
# OR (base58 from Phantom/delegation export, or hex)
export BB_BULLET_PRIVATE_KEY="<base58-or-hex>"        # fallback