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（token-aeusdc）を使用するのは、ユーザーが明示的に aeUSDC を指定した場合に限ります。
• get-quote、get-routes --amount-in、swap --amount-in は、人が読みやすいトークン数量を使用します
• HODLMM の reserve_x と reserve_y はオンチェーンの最小単位を使用します。このスキルでは、人が読みやすいトークン単位で表示します
• HODLMM の bin.price は API の生の値です。このスキルでは、おおよその人が読みやすい tokenY per tokenX の解釈も表示します
• USD を考慮する場合は、外部の BTC/USD または token/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 は、エージェントが解釈しやすいようにアクティブなビンの周辺を簡潔に表示します
• 自然言語で回答する場合は、rawPrice より approxPrice を優先してください

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 sats の 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

2 つのトークン間で可能なすべてのスワップルートを取得します。--amount-in を指定すると、ルートは予想出力に基づいて順位付けされ、SDK のルートとともに HODLMM の見積もりも含まれます。

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 sats の 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 req/min のパブリックエンドポイントを使用します。
• より高いレート制限を利用するには、BITFLOW_API_KEY と BITFLOW_API_HOST の環境変数を設定してください。
• 価格への影響が 5% を超えるスワップには、安全対策として明示的な --confirm-high-impact フラグが必要です。
• 価格への影響は、ルート内のすべてのホップについて XYK 定積積公式を使用して計算されます。
• Keeper 機能を使うと、自動スワップやスケジュール設定したスワップを実行できます。まず get-keeper-contract を使用してください。
• ウォレット操作には、ロック解除済みのウォレットが必要です（最初に bun run wallet/wallet.ts unlock を使用してください）。