bitflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bitflow Skill

Bitflow 技能工具

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 help@bitflow.finance.

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.

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

市场数据 — 通过公开 API 获取所有交易对的行情价格、交易量和流动性数据。
代币发现 — 列出可用于兑换的代币、查找指定代币的可兑换目标、发现多跳兑换路由。
统一报价 — 将 SDK 路由与 HODLMM 报价一起排序，自动展示最优路径。
代币兑换 — 当可直接执行时，选用 SDK 和 HODLMM 中的最优直接路由完成兑换。
HODLMM 流动性管理 — 查看 DLMM 资金池/仓位区间，并通过简易模式的相对仓位偏移量管理流动性。
Keeper 自动化 — 通过 Keeper 合约创建、监控和取消自动化兑换订单。

所有 Bitflow 操作仅支持主网。无需真实的 Bitflow API 密钥 — Bitflow SDK 使用公开端点，单 IP 限制为每分钟 500 次请求。如果调用方或封装工具要求填写 API 密钥字段，可使用任意占位符或等效空值继续操作。如需更高请求限制，请联系 help@bitflow.finance。

写入操作（

swap

、

add-liquidity-simple

、

withdraw-liquidity-simple

、

create-order

）需要钱包。您可以先解锁钱包，或通过

--wallet-password

参数在命令行直接解锁当前托管的钱包。

Usage

使用方法

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

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

```
STX
```
采用6位小数：
```
1 STX = 1,000,000
```
微STX
```
sBTC
```
采用8位小数：
```
1 sBTC = 100,000,000
```
聪
```
USDCx
```
和
```
aeUSDC
```
采用6位小数
命名规则：当用户在 Bitflow 中提及
```
USDC
```
时，默认视为
```
USDCx
```
（
```
token-USDCx-auto
```
）。仅当用户明确要求时才使用
```
aeUSDC
```
（
```
token-aeusdc
```
）。

get-quote

、

get-routes --amount-in

和

swap --amount-in

使用人类可读的代币数量

HODLMM 的
```
reserve_x
```
和
```
reserve_y
```
来自链上原子单位；本技能工具会将其转换为人类可读的代币单位展示
HODLMM 的
```
bin.price
```
是原始 API 值；本技能工具同时会展示近似的人类可读格式，即
```
每单位tokenX对应的tokenY数量
```
如需以美元计价，请使用外部 BTC/USD 或代币/USD 数据源；资金池/仓位区间的输出为池内原生价格，并非通用美元预言机价格

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

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

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

选项：

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

输出：

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

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

bun run bitflow/bitflow.ts get-tokens

输出：

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

获取指定输入代币的可兑换目标代币列表。返回从该代币可兑换的所有代币。

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

选项：

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

输出：

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

从 Bitflow BFF API 列出 HODLMM（DLMM）资金池，以便您选择用于仓位区间操作的

pool_id

。

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

获取某 HODLMM 资金池的所有仓位区间数据，包括储备量、流动性和活跃仓位区间 ID。

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

输出说明：

```
activeBin
```
是首先查看的最优单个仓位区间
```
nearbyBins
```
展示活跃仓位区间附近的紧凑区间窗口，便于工具解读
在自然语言回复中优先使用
```
approxPrice
```
而非
```
rawPrice
```

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]

获取当前钱包在某 HODLMM 资金池中的仓位区间数据。

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

从 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
```
；仅当用户明确要求时才使用
```
token-aeusdc
```
）
```
--amount-in
```
（必填）—— 人类可读的输入代币数量（例如 15,000 聪 sBTC 对应
```
0.00015
```
，21 STX 对应
```
21.0
```
）。SDK 会自动在内部按
```
10^decimals
```
进行缩放。

输出：

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

获取两个代币之间的所有可能兑换路由。当提供

--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
```
（可选）—— 提供该参数时，会根据该交易规模的预期输出量对路由排序

输出：

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

json

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

在 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%的兑换时必须使用该参数

输出：

json

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

json

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

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

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

选项：

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

输出：

json

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

使用简易模式向 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

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.

使用相对于当前活跃仓位区间的偏移量提取 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

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:

json

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

通过 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
```
（可选）—— 根据市场情况自动调整最小接收金额（默认开启）

输出：

json

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

json

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

获取 Bitflow Keeper 订单的详情。

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

选项：

```
--order-id
```
（必填）—— 要查询的订单 ID

输出：

json

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

json

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

在执行前取消 Bitflow Keeper 订单。

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

选项：

```
--order-id
```
（必填）—— 要取消的订单 ID

输出：

json

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

json

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

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

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

选项：

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

输出：

json

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

所有 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
```
）。