bitflow

What this skill does

# 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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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:
```json
{
  "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