aibtcdev/bitflow

Bitflow Skill

Provides DEX operations on the Bitflow aggregated liquidity protocol:

• Market Data — Ticker prices, volumes, and liquidity for all trading pairs via public API.
• Token Discovery — List available swap tokens, find swap targets for a given token, discover multi-hop routes.
• Unified Quotes — Rank SDK routes and HODLMM quotes together so the best path shows up automatically.
• Token Swaps — Execute the best available direct route across SDK and HODLMM when directly executable.
• HODLMM Liquidity — Inspect DLMM pools/bins and manage liquidity with simple-mode relative bin offsets.
• Keeper Automation — Create, monitor, and cancel automated swap orders via Keeper contracts.

All Bitflow operations are mainnet-only. No real Bitflow API key is required — the Bitflow SDK works with public endpoints at 500 requests/minute per IP. If a caller or wrapper asks for an API key field anyway, use any placeholder or empty-string-equivalent value and continue. For higher rate limits, contact [email protected].

Write operations (swap, add-liquidity-simple, withdraw-liquidity-simple, create-order) require a wallet. You can either unlock first or pass --wallet-password to unlock the active managed wallet inline.

Usage

bun run bitflow/bitflow.ts <subcommand> [options]

Units Reference

• STX uses 6 decimals: 1 STX = 1,000,000 micro-STX
• sBTC uses 8 decimals: 1 sBTC = 100,000,000 sats
• USDCx and aeUSDC use 6 decimals
• Naming convention: when a user says USDC on Bitflow, treat that as USDCx (token-USDCx-auto) by default. Only use aeUSDC (token-aeusdc) when the user explicitly asks for aeUSDC.
• get-quote, get-routes --amount-in, and swap --amount-in use human-readable token amounts
• HODLMM reserve_x and reserve_y come from on-chain atomic units; this skill displays them in human-readable token units
• HODLMM bin.price is a raw API value; this skill also shows an approximate human-readable tokenY per tokenX interpretation
• For USD reasoning, use an external BTC/USD or token/USD source; pool/bin outputs are pool-native prices, not a universal USD oracle

Subcommands

get-ticker

Get market ticker data from Bitflow DEX. Returns price, volume, and liquidity data for all trading pairs. Optionally filter by a specific pair.

bun run bitflow/bitflow.ts get-ticker [--base-currency <contractId>] [--target-currency <contractId>]

Options:

• --base-currency (optional) — Filter by base currency contract ID
• --target-currency (optional) — Filter by target currency contract ID

Output:

{
  "network": "mainnet",
  "pairCount": 42,
  "tickers": [
    {
      "ticker_id": "token-stx_token-sbtc",
      "base_currency": "token-stx",
      "target_currency": "token-sbtc",
      "last_price": "0.000012",
      "base_volume": "5000000",
      "target_volume": "60",
      "bid": "0.000011",
      "ask": "0.000013",
      "high": "0.000014",
      "low": "0.000010",
      "liquidity_in_usd": "1500000"
    }
  ]
}

get-tokens

Get all available tokens for swapping on Bitflow.

bun run bitflow/bitflow.ts get-tokens

Output:

{
  "network": "mainnet",
  "tokenCount": 15,
  "tokens": [
    {
      "id": "token-stx",
      "name": "Stacks",
      "symbol": "STX",
      "contractId": "token-stx",
      "decimals": 6
    },
    {
      "id": "token-USDCx-auto",
      "name": "USDCx",
      "symbol": "USDCx",
      "contractId": "SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx",
      "decimals": 6,
      "aliases": ["USDC"]
    }
  ]
}

get-swap-targets

Get possible swap target tokens for a given input token. Returns all tokens that can be received when swapping from the specified token.

bun run bitflow/bitflow.ts get-swap-targets --token-id <contractId>

Options:

• --token-id (required) — The input token ID (contract address)

Output:

{
  "network": "mainnet",
  "inputToken": "token-stx",
  "targetCount": 8,
  "targets": ["token-sbtc", "token-USDCx-auto", "token-alex"]
}

get-hodlmm-pools

List HODLMM (DLMM) pools from the Bitflow BFF API so you can pick a pool_id for bin operations.

bun run bitflow/bitflow.ts get-hodlmm-pools [--suggested] [--sbtc-incentives] [--limit <number>]

get-hodlmm-bins

Fetch all bins for a HODLMM pool, including reserves, liquidity, and the active bin id.

bun run bitflow/bitflow.ts get-hodlmm-bins --pool-id <poolId> [--allow-fallback]

Output notes:

• activeBin is the best single bin to read first
• nearbyBins shows a compact window around the active bin for easier agent interpretation
• Prefer approxPrice over rawPrice in natural-language answers

get-hodlmm-position-bins

Fetch the active wallet's position bins for a HODLMM pool.

bun run bitflow/bitflow.ts get-hodlmm-position-bins --pool-id <poolId> [--address <stacksAddress>] [--fresh] [--allow-fallback]

get-quote

Get a unified swap quote from Bitflow. Ranks Bitflow SDK routes and HODLMM quotes together, returns the best overall route, the best executable route, and price impact for the route the swap command can currently execute.

bun run bitflow/bitflow.ts get-quote --token-x <tokenId> --token-y <tokenId> --amount-in <decimal>

Options:

• --token-x (required) — Input token ID (e.g. token-stx, token-sbtc)
• --token-y (required) — Output token ID (e.g. token-sbtc, token-USDCx-auto; use token-aeusdc only when the user explicitly wants aeUSDC)
• --amount-in (required) — Amount of input token in human-readable decimal (e.g. 0.00015 for 15,000 sats sBTC, 21.0 for 21 STX). The SDK auto-scales by 10^decimals internally.

Output:

{
  "network": "mainnet",
  "quote": {
    "tokenIn": "token-stx",
    "tokenOut": "token-sbtc",
    "amountIn": "1.0",
    "expectedAmountOut": "0.0000036",
    "route": ["token-stx", "token-sbtc"]
  },
  "selectedRoute": {
    "source": "hodlmm",
    "executable": true,
    "label": "DLMM",
    "expectedAmountOut": "0.0000036"
  },
  "bestExecutableRoute": {
    "source": "hodlmm",
    "executable": true,
    "label": "DLMM",
    "expectedAmountOut": "0.0000036"
  },
  "priceImpact": {
    "combinedImpact": 0.0023,
    "combinedImpactPct": "0.23%",
    "severity": "low",
    "hops": [...],
    "totalFeeBps": 30
  }
}

get-routes

Get all possible swap routes between two tokens. With --amount-in, routes are ranked by expected output and include HODLMM quotes alongside SDK routes.

bun run bitflow/bitflow.ts get-routes --token-x <tokenId> --token-y <tokenId> [--amount-in <decimal>]

Options:

• --token-x (required) — Input token ID
• --token-y (required) — Output token ID (token-USDCx-auto when the user asks for USDC, token-aeusdc only for explicit aeUSDC requests)
• --amount-in (optional) — When provided, ranks routes by expected output for that trade size

Output:

{
  "network": "mainnet",
  "tokenX": "token-stx",
  "tokenY": "token-sbtc",
  "routeCount": 3,
  "routes": [
    {
      "source": "sdk",
      "executable": true,
      "tokenPath": ["token-stx", "token-sbtc"],
      "dexPath": ["BITFLOW_XYK_XY_2"]
    }
  ]
}

swap

Execute a token swap on Bitflow DEX. Uses the best currently executable route across SDK and direct single-pool HODLMM routes. Multi-hop HODLMM routes still show up in quotes but remain quote-only. Includes a high-impact safety gate — swaps with >5% price impact require --confirm-high-impact. Requires an unlocked wallet.

bun run bitflow/bitflow.ts swap \
  --token-x <tokenId> --token-y <tokenId> --amount-in <decimal> \
  [--slippage-tolerance <decimal>] [--fee <value>] [--confirm-high-impact]

Options:

• --token-x (required) — Input token ID (contract address)
• --token-y (required) — Output token ID (contract address)
• --amount-in (required) — Amount of input token in human-readable decimal (e.g. 0.00015 for 15,000 sats sBTC, 21.0 for 21 STX). The SDK auto-scales by 10^decimals internally.
• --slippage-tolerance (optional) — Slippage tolerance as decimal (default 0.01 = 1%)
• --fee (optional) — Fee: low | medium | high preset or micro-STX amount. If omitted, auto-estimated.
• --wallet-password (optional) — Unlock the active managed wallet inline for this command
• --confirm-high-impact (optional) — Required to execute swaps with price impact above 5%

Output:

{
  "success": true,
  "txid": "abc123...",
  "swap": {
    "tokenIn": "token-stx",
    "tokenOut": "token-sbtc",
    "amountIn": "1.0",
    "slippageTolerance": 0.01,
    "priceImpact": { "combinedImpactPct": "0.23%", "severity": "low" },
    "executedRoute": {
      "source": "hodlmm",
      "executable": true,
      "label": "DLMM"
    }
  },
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

get-keeper-contract

Get or create a Bitflow Keeper contract for automated swaps.

bun run bitflow/bitflow.ts get-keeper-contract [--address <stacksAddress>]

Options:

• --address (optional) — Stacks address (uses wallet if not specified)

Output:

{
  "network": "mainnet",
  "address": "SP2...",
  "contractIdentifier": "SP2...keeper-v1",
  "status": "active"
}

add-liquidity-simple

Add liquidity to HODLMM bins using simple mode. You provide bin offsets relative to the current active bin.

bun run bitflow/bitflow.ts add-liquidity-simple \
  --pool-id <poolId> \
  --bins '[{"activeBinOffset":0,"xAmount":"0","yAmount":"100000"}]' \
  [--active-bin-tolerance '{"expectedBinId":500,"maxDeviation":"2"}'] \
  [--slippage-tolerance <percent>] [--fee <value>] [--wallet-password <password>]

Notes:

• Use get-hodlmm-bins first so you know where the active bin is.
• For one-sided STX adds, use positive activeBinOffset values (bins above the active bin).
• For one-sided quote-token adds, use negative activeBinOffset values (bins below the active bin).
• Bins below the active bin should usually get only yAmount.
• Bins above the active bin should usually get only xAmount.
• The active bin can receive one or both token amounts.

withdraw-liquidity-simple

Withdraw HODLMM liquidity using offsets relative to the current active bin.

bun run bitflow/bitflow.ts withdraw-liquidity-simple \
  --pool-id <poolId> \
  --positions '[{"activeBinOffset":5,"amount":"392854","minXAmount":"1999000","minYAmount":"0"}]' \
  [--fee <value>] [--wallet-password <password>]

Notes:

• Use both get-hodlmm-position-bins and get-hodlmm-bins before withdrawing.
• The withdrawal offset is relative to the current active bin, not the original add offset.
• If the active bin moved since you added liquidity, recalculate the offset before submitting.

create-order

Create an automated swap order via Bitflow Keeper. Creates a pending order that will be executed by the Keeper service.

bun run bitflow/bitflow.ts create-order \
  --contract-identifier <id> --action-type <type> \
  --funding-tokens '{"token-stx":"1000000"}' --action-amount <units> \
  [--min-received-amount <units>] [--auto-adjust]

Options:

• --contract-identifier (required) — Keeper contract identifier
• --action-type (required) — Action type (e.g., SWAP_XYK_SWAP_HELPER)
• --funding-tokens (required) — JSON map of token IDs to amounts for funding
• --action-amount (required) — Amount for the action
• --min-received-amount (optional) — Minimum amount to receive (slippage protection)
• --auto-adjust (optional) — Auto-adjust minimum received based on market (default true)

Output:

{
  "success": true,
  "network": "mainnet",
  "orderId": "order-123",
  "status": "pending",
  "order": {
    "contractIdentifier": "SP2...keeper-v1",
    "actionType": "SWAP_XYK_SWAP_HELPER",
    "fundingTokens": { "token-stx": "1000000" },
    "actionAmount": "1000000"
  }
}

get-order

Get details of a Bitflow Keeper order.

bun run bitflow/bitflow.ts get-order --order-id <id>

Options:

• --order-id (required) — The order ID to retrieve

Output:

{
  "network": "mainnet",
  "order": {
    "orderId": "order-123",
    "status": "completed",
    "actionType": "SWAP_XYK_SWAP_HELPER",
    "actionAmount": "1000000"
  }
}

cancel-order

Cancel a Bitflow Keeper order before execution.

bun run bitflow/bitflow.ts cancel-order --order-id <id>

Options:

• --order-id (required) — The order ID to cancel

Output:

{
  "network": "mainnet",
  "orderId": "order-123",
  "cancelled": true
}

get-keeper-user

Get Bitflow Keeper user info and orders. Retrieves user's keeper contracts and order history.

bun run bitflow/bitflow.ts get-keeper-user [--address <stacksAddress>]

Options:

• --address (optional) — Stacks address (uses wallet if not specified)

Output:

{
  "network": "mainnet",
  "userInfo": {
    "stacksAddress": "SP2...",
    "contracts": [{ "identifier": "SP2...keeper-v1", "status": "active" }],
    "orders": [{ "orderId": "order-123", "status": "completed" }]
  }
}

Notes

• All Bitflow operations are mainnet-only. Calls on testnet will return an error.
• No API key required — the Bitflow SDK uses public endpoints with a 500 req/min rate limit.
• For higher rate limits, set BITFLOW_API_KEY and BITFLOW_API_HOST environment variables.
• Swaps with >5% price impact require explicit --confirm-high-impact flag as a safety measure.
• Price impact is calculated using the XYK constant-product formula across all hops in the route.
• Keeper features enable automated/scheduled swaps. Use get-keeper-contract to get started.
• Wallet operations require an unlocked wallet (use bun run wallet/wallet.ts unlock first).