bitflow-swap-aggregator

# Bitflow Swap Aggregator ## What it does `bitflow-swap-aggregator` quotes, plans, and executes swaps through Bitflow's aggregator route surface. It resolves tokens from the live Bitflow token registry, asks the Bitflow SDK for the best executable route, prepares the swap call, and broadcasts the transaction only after explicit confirmation. ## Why agents need it Autonomous strategies need a general Bitflow swap primitive that does not force one pool family. This skill gives higher-level controllers a route-aware swap leg that can choose the aggregator's current best supported route and return proof-ready execution details. ## Safety notes - This is a write skill and can move wallet funds. - Mainnet only. - `run` refuses without `--confirm=SWAP`. - The skill uses `PostConditionMode.Deny` with the postconditions produced by Bitflow's swap preparation path. - The skill checks input balance, STX gas reserve, pending transaction depth, signer match, route availability, and mined transaction status. - The skill blocks if the mined transaction status is not `success`. ## Commands ### doctor Checks dependency readiness, Bitflow SDK access, live token registry access, Hiro reachability, and optional wallet readiness. ```bash bun run bitflow-swap-aggregator/bitflow-swap-aggregator.ts doctor --wallet <stacks-address> ``` ### tokens Lists live Bitflow tokens and optionally filters by symbol, token ID, or contract ID. ```bash bun run bitflow-swap-aggregator/bitflow-swap-aggregator.ts tokens --search stx ``` ### quote Fetches the current Bitflow aggregator quote and best route. ```bash bun run bitflow-swap-aggregator/bitflow-swap-aggregator.ts quote --token-in token-stx --token-out token-USDCx-auto --amount-in 1 ``` ### plan Prepares the executable swap call and reports the contract/function, route, postconditions, balances, and safety gates without broadcasting. ```bash bun run bitflow-swap-aggregator/bitflow-swap-aggregator.ts plan --wallet <stacks-address> --token-in token-stx --token-out token-USDCx-auto --amount-in 1 ``` ### run Re-runs fresh quote and preparation checks, resolves the signer, broadcasts the Bitflow aggregator swap, waits for status, and returns proof-ready JSON. ```bash bun run bitflow-swap-aggregator/bitflow-swap-aggregator.ts run --wallet <stacks-address> --token-in token-stx --token-out token-USDCx-auto --amount-in 1 --confirm=SWAP ``` ## Output contract Every command prints exactly one JSON object to stdout. Success: ```json { "status": "success", "action": "plan", "data": {}, "error": null } ``` Blocked: ```json { "status": "blocked", "action": "run", "data": {}, "error": { "code": "CONFIRMATION_REQUIRED", "message": "This write skill requires --confirm=SWAP.", "next": "Re-run with --confirm=SWAP after reviewing plan output." } } ``` ## Known constraints - Uses Bitflow's SDK-supported aggregator route surface. - Does not force HODLMM-only execution. - Does not implement custom direct-pool HODLMM swap calls. - Does not perform DCA scheduling, keeper orders, LP deposits, LP withdrawals, Zest writes, or controller checkpointing. - Requires the wallet to already hold the selected input asset. ## Origin Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @macbotmini-eng Competition PR: https://github.com/BitflowFinance/bff-skills/pull/577