bitflow

Bitflow 技能

在 Bitflow 聚合流动性协议上提供 DEX 操作：

• 市场数据 — 通过公共 API 获取所有交易对的行情价格、交易量和流动性。
• 代币发现 — 列出可用的兑换代币、查找指定代币的兑换目标，以及发现多跳路由。
• 统一报价 — 综合排名 SDK 路由和 HODLMM 报价，让最佳路径自动显示。
• 代币兑换 — 在 SDK 和 HODLMM 中执行可直接执行的最佳可用路由。
• HODLMM 流动性 — 查看 DLMM 池和区间，并使用简单模式下的相对区间偏移管理流动性。
• Keeper 自动化 — 通过 Keeper 合约创建、监控和取消自动兑换订单。

所有 Bitflow 操作仅限 主网。无需真实的 Bitflow API 密钥 — Bitflow SDK 可使用公共端点，每个 IP 每分钟可发起 500 次请求。如果调用方或封装程序仍要求填写 API 密钥字段，请使用任意占位值或等效的空字符串，然后继续操作。如需更高的速率限制，请联系 [email protected]。

写入操作（swap、add-liquidity-simple、withdraw-liquidity-simple、create-order）需要钱包。你可以先解锁钱包，也可以传入 --wallet-password，在操作时内联解锁当前托管钱包。

用法

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

单位参考

• STX 使用 6 位小数：1 STX = 1,000,000 micro-STX
• sBTC 使用 8 位小数：1 sBTC = 100,000,000 sats
• USDCx 和 aeUSDC 使用 6 位小数
• 命名约定：用户在 Bitflow 上提到 USDC 时，默认将其视为 USDCx（token-USDCx-auto）。只有用户明确要求 aeUSDC 时，才使用 aeUSDC（token-aeusdc）。
• get-quote、get-routes --amount-in 和 swap --amount-in 使用人类可读的代币数量
• HODLMM 的 reserve_x 和 reserve_y 来自链上原子单位；此技能会以人类可读的代币单位显示
• HODLMM 的 bin.price 是原始 API 值；此技能还会显示近似的人类可读解释，即 tokenY per tokenX
• 进行美元估值时，请使用外部 BTC/USD 或代币/USD 数据源；池和区间的输出是池原生价格，并非通用的美元预言机

子命令

get-ticker

获取 Bitflow DEX 的市场行情数据。返回所有交易对的价格、交易量和流动性数据。可选择按特定交易对筛选。

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

选项：

• --base-currency（可选）— 按基础货币合约 ID 筛选
• --target-currency（可选）— 按目标货币合约 ID 筛选

输出：

{
  "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

获取 Bitflow 上所有可用于兑换的代币。

bun run bitflow/bitflow.ts get-tokens

输出：

{
  "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

获取指定输入代币可能的兑换目标代币。返回从指定代币兑换时可收到的所有代币。

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

选项：

• --token-id（必填）— 输入代币 ID（合约地址）

输出：

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

get-hodlmm-pools

从 Bitflow BFF API 列出 HODLMM（DLMM）池，以便为区间操作选择 pool_id。

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

get-hodlmm-bins

获取 HODLMM 池的所有区间，包括储备、流动性和当前活跃区间 ID。

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

输出说明：

• activeBin 是最适合优先查看的单个区间
• nearbyBins 显示当前活跃区间周围的紧凑窗口，便于 Agent 解读
• 在自然语言回答中，优先使用 approxPrice，而非 rawPrice

get-hodlmm-position-bins

获取当前活跃钱包在 HODLMM 池中的持仓区间。

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

get-quote

从 Bitflow 获取统一的兑换报价。将 Bitflow SDK 路由和 HODLMM 报价放在一起排名，返回总体最佳路由、最佳可执行路由，以及 swap 命令当前可执行路由的价格影响。

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

选项：

• --token-x（必需）— 输入代币 ID（例如 token-stx、token-sbtc）
• --token-y（必需）— 输出代币 ID（例如 token-sbtc、token-USDCx-auto；仅当用户明确需要 aeUSDC 时才使用 token-aeusdc）
• --amount-in（必需）— 以易读的小数格式表示的输入代币数量（例如，15,000 聪的 sBTC 使用 0.00015，21 STX 使用 21.0）。SDK 会在内部自动按 10^decimals 缩放。

输出：

{
  "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

获取两个代币之间所有可能的兑换路由。提供 --amount-in 时，会根据预期输出对路由进行排名，并同时列出 HODLMM 报价和 SDK 路由。

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

选项：

• --token-x（必需）— 输入代币 ID
• --token-y（必需）— 输出代币 ID（用户询问 USDC 时使用 token-USDCx-auto；仅在用户明确要求 aeUSDC 时使用 token-aeusdc）
• --amount-in（可选）— 提供此参数时，会根据该笔交易规模的预期输出对路由进行排名

输出：

{
  "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

在 Bitflow DEX 上执行代币兑换。使用 SDK 和直接单池 HODLMM 路由中当前最佳的可执行路由。多跳 HODLMM 路由仍会显示在报价中，但只能用于报价。包含高价格影响安全门槛——价格影响超过 5% 的兑换需要提供 --confirm-high-impact。需要已解锁的钱包。

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

选项：

• --token-x（必需）— 输入代币 ID（合约地址）
• --token-y（必需）— 输出代币 ID（合约地址）
• --amount-in（必需）— 以易读的小数格式表示的输入代币数量（例如，15,000 聪的 sBTC 使用 0.00015，21 STX 使用 21.0）。SDK 会在内部自动按 10^decimals 缩放。
• --slippage-tolerance（可选）— 滑点容忍度，以小数表示（默认值 0.01 = 1%）
• --fee（可选）— 手续费：low | medium | high 预设值或微 STX 数量。省略时会自动估算。
• --wallet-password（可选）— 在此命令中直接解锁当前使用的钱包
• --confirm-high-impact（可选）— 执行价格影响超过 5% 的兑换时必需

输出：

{
  "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

获取或创建用于自动兑换的 Bitflow Keeper 合约。

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

选项：

• --address（可选）— Stacks 地址（未指定时使用钱包地址）

输出：

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

add-liquidity-simple

使用简单模式向 HODLMM 区间添加流动性。提供相对于当前活跃区间的区间偏移量。

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>]

注意：

• 先使用 get-hodlmm-bins，以确定活跃区间的位置。
• 对于单边 STX 添加，使用正的 activeBinOffset 值（活跃区间上方的区间）。
• 对于单边报价代币添加，使用负的 activeBinOffset 值（活跃区间下方的区间）。
• 活跃区间下方的区间通常只应获得 yAmount。
• 活跃区间上方的区间通常只应获得 xAmount。
• 活跃区间可以接收一种或两种代币数量。

withdraw-liquidity-simple

根据相对于当前活跃区间的偏移量提取 HODLMM 流动性。

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>]

注意：

• 提取前同时使用 get-hodlmm-position-bins 和 get-hodlmm-bins。
• 提取偏移量相对于当前活跃区间，而不是最初添加流动性时的偏移量。
• 如果添加流动性后活跃区间发生移动，请在提交前重新计算偏移量。

create-order

通过 Bitflow Keeper 创建自动兑换订单。创建的待处理订单将由 Keeper 服务执行。

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]

选项：

• --contract-identifier（必需）— Keeper 合约标识符
• --action-type（必需）— 操作类型（例如，SWAP_XYK_SWAP_HELPER）
• --funding-tokens（必需）— 用于注资的代币 ID 与数量的 JSON 映射
• --action-amount（必需）— 操作金额
• --min-received-amount（可选）— 最低接收金额（滑点保护）
• --auto-adjust（可选）— 根据市场自动调整最低接收金额（默认值为 true）

输出：

{
  "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

获取 Bitflow Keeper 订单详情。

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

选项：

• --order-id（必需）— 要检索的订单 ID

输出：

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

cancel-order

在执行前取消 Bitflow Keeper 订单。

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

选项：

• --order-id（必需）— 要取消的订单 ID

输出：

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

get-keeper-user

获取 Bitflow Keeper 用户信息和订单。检索用户的 Keeper 合约和订单历史记录。

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

选项：

• --address（可选）— Stacks 地址（若未指定，则使用钱包）

输出：

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

注意事项

• 所有 Bitflow 操作仅支持 主网。在测试网上调用会返回错误。
• 无需 API 密钥 — Bitflow SDK 使用公共端点，速率限制为每分钟 500 次请求。
• 如需更高的速率限制，请设置 BITFLOW_API_KEY 和 BITFLOW_API_HOST 环境变量。
• 价格影响超过 5% 的兑换需要显式指定 --confirm-high-impact 标志，以确保安全。
• 价格影响根据兑换路径中所有跳转的 XYK 恒定乘积公式计算。
• Keeper 功能支持自动化／定时兑换。使用 get-keeper-contract 开始操作。
• 钱包操作需要已解锁的钱包（请先运行 bun run wallet/wallet.ts unlock）。