lp-agent

lp-agent

このスキルは、Hummingbot API を使用して集中流動性（CLMM）DEX 上で自動流動性供給戦略を実行するのに役立ちます。

コマンド（/lp-agent <command> として実行）：

コマンド	説明
start	オンボーディングウィザード — セットアップ状況を確認して開始します
deploy-hummingbot-api	Hummingbot API トレーディングインフラストラクチャをデプロイします
setup-gateway	Gateway を起動し、ネットワーク RPC エンドポイントを設定します
add-wallet	Solana ウォレットを追加またはインポートします
explore-pools	Meteora DLMM プールを検索して探索します
select-strategy	LP Executor または Rebalancer Controller を選択します
run-strategy	LP 戦略を実行、監視、管理します
analyze-performance	LP ポジションのパフォーマンスを可視化します

初めての方へ /lp-agent start を実行してセットアップを確認し、ガイド付きのウォークスルーを受けましょう。

典型的なワークフロー： start → deploy-hummingbot-api → setup-gateway → add-wallet → explore-pools → select-strategy → run-strategy → analyze-performance

---

コマンド: start

ユーザーを歓迎し、セットアップをガイドします。これは会話形式のオンボーディングウィザードです — インフラストラクチャの状態を確認し、結果を解釈し、各ステップを案内します。

ステップ 1: 歓迎と説明

自己紹介し、lp-agent が何をするかを説明します：

私はあなたの LP エージェントです — Meteora DLMM プール（Solana）上で自動流動性供給戦略を実行するお手伝いをします。できることは：

• インフラストラクチャのデプロイ — DEX トレーディング用の Hummingbot API + Gateway
• ウォレットの管理 — Solana ウォレットの追加、残高の確認
• プールの探索 — Meteora DLMM プールの検索、APR/出来高/TVL の比較
• 戦略の実行 — 自動リバランス LP コントローラーまたは単一ポジション実行者
• パフォーマンスの分析 — PnL、手数料、ポジション履歴を含むダッシュボード

ステップ 2: インフラストラクチャの状態を確認

以下のスクリプトを実行し、JSON 出力を解釈します：

bash scripts/check_api.sh --json      # Is Hummingbot API running?
bash scripts/check_gateway.sh --json  # Is Gateway running?
python scripts/add_wallet.py list     # Any wallets connected?

結果の解釈：

スクリプト	成功時の出力	失敗時の出力
check_api.sh --json	{"running": true, "url": "http://localhost:8000", ...}	{"running": false, ...} または接続エラー
check_gateway.sh --json	{"running": true, ...}	{"running": false, ...}
add_wallet.py list	[solana] ABC123... のようなウォレットアドレスを表示	No wallets found. または空のリスト []

ステップ 3: 進捗を表示

スクリプトの出力に基づいて、完了した項目と残っている項目を示すチェックリストを提示します：

Setup Progress:
  [x] Hummingbot API    — Running at http://localhost:8000
  [x] Gateway           — Running
  [ ] Wallet            — No wallet connected

Next step: Add a Solana wallet so you can start trading.

チェックリストは実際の状態に合わせて調整してください。すべてが未チェックの場合は、最初から始めてください。すべてがチェック済みの場合は、LP ライフサイクルの概要に進んでください。

ステップ 4: 次のアクションをガイド

最初の未チェック項目に基づいて、支援を提案します：

不足しているもの	伝える内容
Hummingbot API	「まず API をデプロイしましょう — これはトレーディングのバックエンドです。Docker がインストールされている必要があります。インストーラーを実行しましょうか？」→ /lp-agent deploy-hummingbot-api
Gateway	「API は動作しています！次に DEX 接続のために Gateway が必要です。起動しましょうか？」→ /lp-agent setup-gateway
ウォレット	以下のウォレットの追加を参照してください
すべて準備完了	ステップ 5 に進みます

ウォレットの追加：

ウォレットが次のステップである場合、ユーザーに伝えます：

インフラストラクチャの準備ができました。トランザクション手数料（LP ポジションあたり約 0.06 SOL）用の SOL を持つ Solana ウォレットが必要です。

ウォレットを追加するには、次を実行してください：

python scripts/add_wallet.py add

秘密鍵を貼り付けるよう求められます（安全で、シェル履歴には保存されません）。

add_wallet.py の出力の解釈：

出力	意味
✓ Wallet added successfully + アドレス	成功 — ウォレットが接続されました
Enter private key (base58): の後に ✓ Wallet added	プロンプト後に成功
Error: HTTP 400 または検証エラー	無効な秘密鍵の形式
Error: Cannot connect to API	API が動作していません — 先に check_api.sh を実行してください

ウォレットが追加されたら、python scripts/add_wallet.py list で確認してください — 新しいアドレスが表示されるはずです。

ステップ 5: LP ライフサイクルの概要

インフラストラクチャの準備が整ったら（または、ユーザーが先にフローを理解したい場合）、LP ライフサイクルについて説明します。

LP 戦略の仕組み:

1. プールを探す (/lp-agent explore-pools) — Meteora DLMM プールを見つけます。出来高、APR、手数料/TVL 比率を確認して、適切なものを選びます。

2. 戦略を選択する (/lp-agent select-strategy) — 以下から選択します:

   • Rebalancer Controller（推奨） — 価格がレンジ外に動いたときに自動的にポジションを再配置します。設定したらそのまま放置できます。
   • LP Executor — 単一の固定ポジション。クローズ/再オープンのタイミングは自分で制御します。テストや指値注文スタイルの LP に適しています。

3. 戦略を実行する (/lp-agent run-strategy) — パラメータ（金額、幅、価格制限）を設定してデプロイします。ステータスを監視し、完了したら停止します。

4. 分析する (/lp-agent analyze-performance) — PnL ダッシュボード、獲得した手数料、ポジション履歴を表示します。実行中および停止済みの両方の戦略で機能します。

始めるにあたって、いくつかのプールを探してみますか？

---

コマンド: deploy-hummingbot-api

Hummingbot API トレーディングインフラストラクチャをデプロイします。これは、LP 機能を使用する前の最初のステップです。

インストールされるもの

Hummingbot API — トレーディング、マーケットデータ、および CEX と DEX 全体にわたるボット戦略のデプロイのための REST API を公開するパーソナルトレーディングサーバーです。

• リポジトリ: hummingbot/hummingbot-api

使用方法

# Check if already installed
bash scripts/deploy_hummingbot_api.sh status

# Install (interactive, prompts for credentials)
bash scripts/deploy_hummingbot_api.sh install

# Install with defaults (non-interactive: admin/admin)
bash scripts/deploy_hummingbot_api.sh install --defaults

# Upgrade existing installation
bash scripts/deploy_hummingbot_api.sh upgrade

# View container logs
bash scripts/deploy_hummingbot_api.sh logs

# Reset (stop and remove everything)
bash scripts/deploy_hummingbot_api.sh reset

前提条件

• Docker および Docker Compose
• Git

出力の解釈

出力	意味	次のステップ
✓ Hummingbot API deployed successfully	成功	setup-gateway に進む
✓ Already installed and running	セットアップ済み	setup-gateway に進む
Error: Docker not found	Docker がインストールされていない	まず Docker をインストールする
Error: Port 8000 already in use	ポートで別のサービスが動作中	競合するサービスを停止するか、別のポートを使用する

インストール後

API が実行されたら:

1. Swagger UI は http://localhost:8000/docs にあります
2. デフォルトの認証情報: admin/admin
3. setup-gateway に進んで DEX トレーディングを有効にします

---

コマンド: setup-gateway

Gateway サービスを起動し、ステータスを確認し、RPC ノード URL などの主要なネットワークパラメータを設定します。Gateway は、DEX 上のすべての LP 操作に必要です。

前提条件: Hummingbot API が実行されている必要があります（deploy-hummingbot-api）。スクリプトはこれを自動的にチェックします。

⚠️ カスタム RPC は必須です — オプションではありません。 パブリック Solana RPC はレート制限があり、「Insufficient funds」や「Transaction simulation failed」のように見えるトランザクション失敗を引き起こします。ボットをデプロイする前に、必ずカスタム RPC を設定してください。https://helius.dev で無料のキーを取得できます。

使用方法

# Check Gateway status
bash scripts/setup_gateway.sh --status

# Start Gateway with defaults
bash scripts/setup_gateway.sh

# Start Gateway with custom image (e.g., development build)
bash scripts/setup_gateway.sh --image hummingbot/gateway:development

# Start with custom Solana RPC (recommended to avoid rate limits)
bash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com

# Configure RPC for a different network
bash scripts/setup_gateway.sh --network ethereum-mainnet --rpc-url https://your-eth-rpc.com

# Start with custom passphrase and port
bash scripts/setup_gateway.sh --passphrase mypassword --port 15888

オプション

オプション	デフォルト	説明
--status		Gateway のステータスのみを確認する（起動しない）
--image IMAGE	hummingbot/gateway:development	使用する Docker イメージ
--passphrase TEXT	hummingbot	Gateway のパスフレーズ
--rpc-url URL		--network 用のカスタム RPC エンドポイント
--network ID	solana-mainnet-beta	RPC を設定するネットワーク
--port PORT	15888	Gateway のポート

応用: manage_gateway.py

より細かい制御（停止、再起動、ログ、ネットワークごとの設定）には、manage_gateway.py を使用します:

python scripts/manage_gateway.py status                    # Check status
python scripts/manage_gateway.py start                     # Start Gateway
python scripts/manage_gateway.py stop                      # Stop Gateway
python scripts/manage_gateway.py restart                   # Restart Gateway
python scripts/manage_gateway.py logs                      # View logs
python scripts/manage_gateway.py networks                  # List all networks
python scripts/manage_gateway.py network solana-mainnet-beta                          # Get network config
python scripts/manage_gateway.py network solana-mainnet-beta --node-url https://...   # Set RPC node

出力の解釈

出力	意味	次のステップ
✓ Gateway is running または ✓ Gateway started	成功	add-wallet に進む
✓ Gateway is already running	セットアップ済み	add-wallet に進む
✗ Cannot connect to Hummingbot API	API が実行されていない	まず /lp-agent deploy-hummingbot-api を実行する
✗ Failed to start Gateway	Docker の問題	Docker が実行中であることを確認し、ログを確認する
✓ RPC configured + ✓ Gateway restarted	カスタム RPC 設定済み	使用可能

カスタム RPC ノード

Gateway はデフォルトでパブリック RPC ノードを使用するため、レート制限に達する可能性があります。これを避けるには、ネットワークごとにカスタムの nodeUrl を設定してください。

人気の Solana RPC プロバイダー:

• Helius — 無料プランあり
• QuickNode
• Alchemy
• Triton

---

コマンド: add-wallet

取引用の Solana ウォレットを追加します。

必要条件: 先に deploy-hummingbot-api と setup-gateway を完了している必要があります。

ウォレットの追加

python scripts/add_wallet.py add

秘密鍵 (base58 形式) を貼り付けるよう求められます。鍵は安全に入力され、シェル履歴には残りません。

出力の解釈:

出力	意味	次のステップ
✓ Wallet added successfully + Address: ABC...	成功	list コマンドで確認
Error: HTTP 400 - Bad Request	秘密鍵の形式が無効	鍵が base58 でエンコードされているか確認
Error: HTTP 503	Gateway が利用不可	bash scripts/check_gateway.sh を実行
Error: Cannot connect to API	API が実行されていない	/lp-agent deploy-hummingbot-api を実行

ウォレットの一覧表示

python scripts/add_wallet.py list

出力の解釈:

出力	意味
[solana] ABC123...XYZ	Solana でウォレットが接続されている
No wallets found.	まだウォレットが追加されていない
空のリスト [] (--json 指定時)	まだウォレットが追加されていない

残高の確認

# Check all balances
python scripts/add_wallet.py balances

# Filter by account
python scripts/add_wallet.py balances --account master_account

# Show zero balances too
python scripts/add_wallet.py balances --all

Gateway へのカスタムトークンの追加

非標準のトークン (例: ミームコイン) を使用する場合は、まず Gateway に追加してください:

# Use exact symbol from the pool (check with get_meteora_pool.py)
python scripts/add_wallet.py add-token \
  --symbol Percolator \
  --address 8PzFWyLpCVEmbZmVJcaRTU5r69XKJx1rd7YGpWvnpump \
  --decimals 6

⚠️ シンボルはプールと完全に一致する必要があります。 get_meteora_pool.py を使用して正確なトークンシンボルを確認してください。プールに Percolator と表示されている場合は、Percolator を使用してください — PRCLT やその他の略称は使用しないでください。一致しない場合、ボットが価格データを取得しようとすると「No CLMM pool found」エラーが発生します。

その後、トークンが認識されるように Gateway を再起動してください。

要件

• 手数料用の SOL: ウォレットにはトランザクション手数料用の SOL が必要です (LP ポジションごとに rent として約 0.06 SOL)
• デプロイ前に実際の残高を確認: balances コマンドを使用してください — SPL トークンアカウントで利用可能な額は、オンチェーンの合計と異なる場合があります (複数アカウント、ステーキングなど)
• デフォルトチェーン: Solana mainnet-beta

---

コマンド: explore-pools

LP ポジションを作成する前に、Meteora DLMM プールを検索して調査します。

注意: プール一覧 (list_meteora_pools.py) は前提条件なしで動作します — Meteora API に直接クエリを実行します。プール詳細 (get_meteora_pool.py) は、リアルタイムの価格と流動性チャートのためにオプションで Gateway を使用します。

プールの一覧表示

名前、トークン、またはアドレスでプールを検索して一覧表示します:

# Top pools by 24h volume
python scripts/list_meteora_pools.py

# Search by token symbol
python scripts/list_meteora_pools.py --query SOL
python scripts/list_meteora_pools.py --query USDC

# Search by pool name
python scripts/list_meteora_pools.py --query SOL-USDC

# Sort by different metrics
python scripts/list_meteora_pools.py --query SOL --sort tvl
python scripts/list_meteora_pools.py --query SOL --sort apr
python scripts/list_meteora_pools.py --query SOL --sort fees

# Pagination
python scripts/list_meteora_pools.py --query SOL --limit 50 --page 2

出力列:

• Pool: 取引ペア名
• Pool Address: プールのコントラクトアドレス (短縮表示、完全なアドレスは get_meteora_pool.py を使用)
• Base (mint): ベーストークンのシンボルと短縮された mint アドレス
• Quote (mint): クォートトークンのシンボルと短縮された mint アドレス
• TVL: ロックされた資産の総額
• Vol 24h: 24 時間の取引量
• Fees 24h: 過去 24 時間で獲得した手数料
• APR: 年間利率
• Fee: 基本手数料率
• Bin: ビンステップ (ポジションの最大幅に影響)

注意: トークンの mint は、複数のトークンが同じ名前を共有している場合 (例: 複数の「PERCOLATOR」トークン) に正しいトークンを識別するのに役立ちます。

プール詳細の取得

特定のプールに関する詳細情報を取得します。Meteora API (履歴データ) と Gateway (リアルタイムデータ) の両方から取得します:

python scripts/get_meteora_pool.py <pool_address>

# Example
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms

# Output as JSON for programmatic use
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --json

# Skip Gateway (faster, no bin distribution)
python scripts/get_meteora_pool.py ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms --no-gateway

データソース:

• Meteora API: 履歴の取引量、手数料、APR、トークン情報、時価総額
• Gateway (Gateway の実行が必要): リアルタイムの価格、ビンごとの流動性分布

表示される詳細:

• トークン情報 (シンボル、mint、小数桁、価格)
• プール設定 (ビンステップ、手数料、最大レンジ幅)
• Gateway からのリアルタイム価格 (SOL/トークン比率)
• 現在価格周辺のビンを示す流動性分布チャート
• 流動性とリザーブ
• 時間枠ごとの取引量 (30m、1h、4h、12h、24h)
• 時間枠ごとの獲得手数料
• 利回り (APR、APY、ファーム報酬)
• 手数料/TVL 比率 (収益性の指標)

プールの選択

プールを選ぶ際は、次の点を検討してください。

1. TVL: TVL が高い = より安定しているが、その分競争も激しい
2. 出来高: 出来高が多い = 手数料を得る機会が増える
3. 手数料/TVL 比率: 高い = 流動性 1 ドルあたりの収益性が高い
4. Bin Step: ポジションの最大幅を決定します
   • bin_step=1 → 最大約 0.69% の幅（狭いレンジ）
   • bin_step=10 → 最大約 6.9% の幅（中程度のレンジ）
   • bin_step=100 → 最大約 69% の幅（広いレンジ）

---

コマンド: select-strategy

ユーザーが適切な LP 戦略を選ぶのを支援します。詳細なガイドについては references/ を参照してください。

LP Rebalancer Controller（推奨）

参照: references/lp_rebalancer_guide.md

リバランスロジックを用いて LP ポジションを自動管理するコントローラーです。

機能	説明
自動リバランス	価格がレンジを外れたときにポジションをクローズして再オープンします
価格リミット	アンカーポイントで BUY/SELL ゾーンを設定できます
KEEP ロジック	最適なポジションにあるときは不要なリバランスを回避します
手放し運用	設定したらそのまま - コントローラーがすべてを管理します

最適な用途: 長期的な LP 戦略、レンジ相場、自動での手数料回収。

LP Executor（単一ポジション）

参照: references/lp_executor_guide.md

固定した価格範囲で 1 つの流動性ポジションを作成します。自動リバランスは行いません。

機能	説明
固定範囲	ポジションは設定した価格レンジに留まります
手動コントロール	クローズ/再オープンのタイミングはユーザーが判断します
指値注文	価格がレンジを外れたときに自動クローズできます（指値注文のように）
シンプル	単一ポジションを直接コントロールできます

最適な用途: 短期ポジション、指値注文スタイルの LP、手動管理、テスト。

簡単な比較

項目	Rebalancer Controller	LP Executor
リバランス	自動	手動
ポジション数	一度に 1 つ、自動管理	1 つ、固定
価格リミット	あり（アンカーポイント）	なし（ただし自動クローズあり）
複雑さ	高い（設定項目が多い）	低い（よりシンプル）
用途	設定したらそのまま	精密なコントロール

---

コマンド: run-strategy

LP 戦略を実行、監視、管理します。

必要条件: 先に deploy-hummingbot-api、setup-gateway、add-wallet を完了している必要があります。

LP リバランサーコントローラー（推奨）

参照: 完全な設定の詳細、リバランスロジック、KEEP と REBALANCE のシナリオについては、references/lp_rebalancer_guide.md を参照してください。

価格が範囲外に動いたときにポジションを自動でリバランスします。手放しでの LP 管理に最適です。

主要な概念:

• --amount（total_amount_quote）= クオート資産（ペアの 2 番目のトークン）での金額。Percolator-SOL → SOL。SOL-USDC → USDC。サイドに関係なく、常にクオートです。
• すべての *_pct パラメータはすでにパーセント単位です。position_width_pct: 10 = 幅 10%。小数（0.10 など）を渡さないでください。
• 価格制限（--buy-min/max、--sell-min/max）のデフォルトは null = 制限なし。ストップゾーンを設定したい場合にのみ指定してください。

# 1. Create LP Rebalancer config (pool and pair are required)
python scripts/manage_controller.py create-config my_lp_config \
    --pool <pool_address> \
    --pair SOL-USDC \
    --amount 10 \       # 10 USDC (quote asset for SOL-USDC)
    --side 0 \          # 0=BOTH, 1=BUY (quote only), 2=SELL (base only)
    --width 10 \        # 10% range around current price
    --offset 1 \        # center range 1% from current price
    --rebalance-seconds 300 \
    --rebalance-threshold 1

# Side=2 example: deploy base token only (e.g. 110k PRCLT ≈ 1.33 SOL)
python scripts/manage_controller.py create-config percolator_sell \
    --pool ATrBUW2reZiyftzMQA1hEo8b7w7o8ZLrhPd7M7sPMSms \
    --pair Percolator-SOL \
    --amount 1.33 \     # 1.33 SOL worth (quote for Percolator-SOL pair)
    --side 2

# 2. Deploy bot with the config
python scripts/manage_controller.py deploy my_lp_bot --configs my_lp_config

# 3. Monitor status
python scripts/manage_controller.py status

主要パラメータ:

パラメータ	フィールド	デフォルト	説明
--amount	total_amount_quote	必須	クオート資産（2 番目のトークン）での金額。X-SOL ペアなら SOL、X-USDC ペアなら USDC。
--side	side	0	0=BOTH、1=BUY（クオートのみ）、2=SELL（ベースのみ）
--width	position_width_pct	10	範囲幅（%）（例: 10 = 価格を中心に ±10%）。すでに % 単位 — 小数は使用しないでください。
--offset	position_offset_pct	0.1	現在価格からの中心オフセット（%）。すでに % 単位。
--rebalance-seconds	rebalance_seconds	300	クローズして再度オープンするまでの範囲外秒数
--rebalance-threshold	rebalance_threshold_pct	1	リバランスをトリガーする最小価格変動（%）。すでに % 単位。
--sell-max/--sell-min	sell_price_max/min	null	SELL サイドの価格制限（null = 制限なし）
--buy-max/--buy-min	buy_price_max/min	null	BUY サイドの価格制限（null = 制限なし）
--strategy-type	strategy_type	0	Meteora シェイプ: 0=Spot（均等）、1=Curve（中央重視）、2=Bid-Ask（端重視）

単一 LP エグゼキューター（代替）

参照: ステートマシン、片側/両側ポジション、指値範囲注文については、references/lp_executor_guide.md を参照してください。

固定された境界で 1 つのポジションを作成します。自動リバランスは行いません。

python scripts/manage_executor.py create \
    --pool <pool_address> \
    --pair SOL-USDC \
    --quote-amount 100 \
    --lower 180 \
    --upper 185 \
    --side 1

主要パラメータ:

パラメータ	説明
--connector	/clmm サフィックスを含める必要があります（デフォルト: meteora/clmm）
--lower/--upper	ポジションの価格境界
--base-amount/--quote-amount	トークン量（片側にする場合はいずれかを 0 に設定）
--side	0=BOTH、1=BUY、2=SELL
--auto-close-above	価格が範囲を上回ったときに自動クローズ（指値注文用）
--auto-close-below	価格が範囲を下回ったときに自動クローズ（指値注文用）

監視と管理

ステータスの確認:

# Bot status
python scripts/manage_controller.py status

# Executor list
python scripts/manage_executor.py list --type lp_executor

# Executor details
python scripts/manage_executor.py get <executor_id>

# Executor summary
python scripts/manage_executor.py summary

エグゼキューターの状態:

• OPENING - オンチェーンでポジションを作成中
• IN_RANGE - ポジションが有効で、手数料を獲得中
• OUT_OF_RANGE - 価格がポジションの境界外
• CLOSING - ポジションを削除中
• FAILED - トランザクションが失敗

停止:

# Stop bot (stops all its controllers)
python scripts/manage_controller.py stop my_lp_bot

# Stop individual executor (closes position)
python scripts/manage_executor.py stop <executor_id>

# Stop executor but keep position on-chain
python scripts/manage_executor.py stop <executor_id> --keep-position

停止後 — 結果の分析

ユーザーが LP エグゼキューターを実行した場合（manage_executor.py create または直接 API 経由）、すぐに分析を提案してください:

エグゼキューターが停止されました。パフォーマンスダッシュボードを生成しましょうか？

次に実行します:

python scripts/visualize_lp_executor.py --id <executor_id>

エグゼキューター ID はエグゼキューターの作成時に返されます（Executor ID: <id> として出力されます）。ユーザーが手元に持っていない場合は、API から取得します:

curl -s -u admin:admin -X POST http://localhost:8000/executors/search \
  -H "Content-Type: application/json" \
  -d '{"type":"lp_executor"}' | python3 -c "
import json,sys
data=json.load(sys.stdin)
items=data.get('data',data) if isinstance(data,dict) else data
for ex in (items if isinstance(items,list) else [items]):
    print(ex.get('executor_id') or ex.get('id'), ex.get('trading_pair'), ex.get('status'))
"

生データを CSV にもエクスポートするには:

python scripts/export_lp_executor.py --id <executor_id>

ユーザーがリバランサーコントローラーボットを実行した場合、データは SQLite ファイルに保存されています — 代わりに SQLite ベースのスクリプトで analyze-performance を使用してください。

---

コマンド: analyze-performance

LP ポジションのイベントからデータをエクスポートし、ビジュアルダッシュボードを生成します。スクリプトはこのスキルの scripts/ ディレクトリにあります。

どのスクリプトを使うべきか？

常に自問してください：このポジションは LP Executor（manage_executor.py または直接 API 経由）としてデプロイされたのか、それとも Rebalancer Controller ボット経由でデプロイされたのか？

デプロイ方法	使用するスクリプト
LP Executor — manage_executor.py create または直接 POST /executors/ API	visualize_lp_executor.py --id <executor_id> ✅
Rebalancer Controller — manage_controller.py deploy（ボットコンテナ、SQLite）	visualize_lp_positions.py --pair <pair>
わからない場合	curl -s -u admin:admin -X POST http://localhost:8000/executors/search -H "Content-Type: application/json" -d '{"type":"lp_executor"}' を実行 — executor ID が表示されたら、executor スクリプトを使用してください

ユーザーがこのセッションで LP Executor を実行している場合（executor ID がコンテキストからわかる場合）、質問をスキップして直接次に進んでください：

python scripts/visualize_lp_executor.py --id <executor_id>

利用可能なスクリプト

スクリプト	目的
scripts/export_lp_positions.py	LP ポジションイベントを CSV にエクスポート（SQLite／ボットコンテナベース）
scripts/visualize_lp_positions.py	ポジションイベントから HTML ダッシュボードを生成（SQLite／ボットコンテナベース）
scripts/export_lp_executor.py	--id で単一の LP executor を CSV にエクスポート（REST API、SQLite 不使用）
scripts/visualize_lp_executor.py	--id で単一の LP executor の HTML ダッシュボードを生成（REST API）

LP ポジションの可視化

ブロックチェーンからのポジション ADD/REMOVE イベントを表示します。実行中および停止中の両方のボットで機能します。

# Basic usage (auto-detects database in data/)
python scripts/visualize_lp_positions.py --pair SOL-USDC

# Specify database explicitly
python scripts/visualize_lp_positions.py --db data/my_bot.sqlite --pair SOL-USDC

# Filter by connector
python scripts/visualize_lp_positions.py --pair SOL-USDC --connector meteora/clmm

# Last 24 hours only
python scripts/visualize_lp_positions.py --pair SOL-USDC --hours 24

ダッシュボードの機能：

• KPI カード（合計 PnL、手数料、IL、勝敗数）
• 累積 PnL と手数料のチャート
• LP レンジ境界を含むオープン／クローズ時の価格
• ポジションごとの PnL 棒グラフ
• 保有期間と PnL の散布図
• Solscan リンク付きのソート可能なポジションテーブル

CSV へのエクスポート

# Export all position events
python scripts/export_lp_positions.py --db data/my_bot.sqlite

# Filter by trading pair
python scripts/export_lp_positions.py --pair SOL-USDC --output exports/positions.csv

# Show summary without exporting
python scripts/export_lp_positions.py --summary

Executor パフォーマンス（API ベース）

これらのスクリプトは Hummingbot REST API から直接動作します — SQLite データベースは不要です。 executor が API 経由で直接デプロイされた場合（例：manage_executor.py 経由）に使用してください。 そのような場合、ボットコンテナのように常に SQLite レコードが生成されるとは限らないためです。

単一の LP executor を CSV にエクスポート：

python scripts/export_lp_executor.py --id <executor_id>
python scripts/export_lp_executor.py --id <executor_id> --output exports/my_run.csv
python scripts/export_lp_executor.py --id <executor_id> --print   # JSON to stdout

CSV の列（LP executor スキーマ）：

• 識別情報： id, account_name, controller_id, connector_name, trading_pair
• 状態： status, close_type, is_active, is_trading, error_count
• タイミング： created_at, closed_at, close_timestamp, duration_seconds
• PnL： net_pnl_quote, net_pnl_pct, cum_fees_quote, filled_amount_quote
• 設定（デプロイ）： pool_address, lower_price, upper_price, base_amount_config, quote_amount_config, side, position_offset_pct, auto_close_above_range_seconds, auto_close_below_range_seconds, keep_position
• custom_info（ライブ／最終）： state, position_address, current_price, lower_price_actual, upper_price_actual, base_amount_current, quote_amount_current, base_fee, quote_fee, fees_earned_quote, total_value_quote, unrealized_pnl_quote, position_rent, position_rent_refunded, tx_fee, out_of_range_seconds, max_retries_reached, initial_base_amount, initial_quote_amount

単一の LP executor を可視化（HTML ダッシュボード）：

python scripts/visualize_lp_executor.py --id <executor_id>
python scripts/visualize_lp_executor.py --id <executor_id> --output report.html
python scripts/visualize_lp_executor.py --id <executor_id> --no-open

ダッシュボードのパネル：

• KPI カード：ステータス、純 PnL、獲得手数料、保有期間、LP レンジ
• LP の下限／上限境界とオープン／クローズマーカー付きの価格チャート（5 分足 KuCoin ローソク足、エキゾチックペアでは自動スキップ）
• トークン残高バー：初期と最終の base + quote 量
• PnL 内訳：獲得手数料と IL／価格インパクトと純 PnL
• プールおよびポジションアドレスの Solscan リンク付きの完全なポジションサマリーテーブル
• ダークテーマ（#0d1117 / #161b27）、レスポンシブレイアウト、CDN からの Chart.js
• 認証は .env または ~/.hummingbot/.env または ~/.env から自動ロード（キー：HUMMINGBOT_API_URL、API_USER、API_PASS）

---

クイックリファレンス

一般的なワークフロー

完全なセットアップ（初回）：

# 1. Deploy API
bash scripts/deploy_hummingbot_api.sh install

# 2. Start Gateway
bash scripts/setup_gateway.sh --rpc-url https://your-rpc-endpoint.com

# 3. Add wallet
python scripts/add_wallet.py add

# 4. Find pool
python scripts/list_meteora_pools.py --query SOL-USDC

# 5. Check bin_step
python scripts/get_meteora_pool.py <pool_address>

# 6. Create config and deploy
python scripts/manage_controller.py create-config my_lp --pool <pool_address> --pair SOL-USDC --amount 100
python scripts/manage_controller.py deploy my_bot --configs my_lp

# 7. Verify
python scripts/manage_controller.py status

LP ポジションの分析：

# Visualize
python scripts/visualize_lp_positions.py --pair SOL-USDC

# Export CSV
python scripts/export_lp_positions.py --pair SOL-USDC

前提条件の確認

API または Gateway を必要とするコマンドを実行する前に、それらが実行中であることを確認してください：

bash scripts/check_api.sh       # Is Hummingbot API running?
bash scripts/check_gateway.sh   # Is Gateway running? (also checks API)

どちらも --json 出力をサポートしています。これらのスクリプトは setup_gateway.sh によって内部的にも使用されており、他のシェルスクリプトからも source できます。

スクリプトリファレンス

スクリプト	目的
check_api.sh	Hummingbot API が実行中かどうかを確認する（共有）
check_gateway.sh	Gateway が実行中かどうかを確認する（共有）
deploy_hummingbot_api.sh	Hummingbot API のインストール/アップグレード/管理
setup_gateway.sh	Gateway の起動と RPC の設定
add_wallet.py	ウォレットの追加と残高の確認
manage_gateway.py	高度な Gateway 管理
list_meteora_pools.py	プールの検索と一覧表示
get_meteora_pool.py	流動性チャート付きでプールの詳細を取得
manage_executor.py	LP エグゼキューターの作成、一覧表示、停止
manage_controller.py	設定の作成、ボットのデプロイ、ステータスの取得
export_lp_positions.py	ポジションイベントを CSV にエクスポート（SQLite/bot-container）
visualize_lp_positions.py	HTML ダッシュボードを生成（SQLite/bot-container）
export_lp_executor.py	--id で単一の LP エグゼキューターを CSV にエクスポート（REST API）
visualize_lp_executor.py	--id で単一の LP エグゼキューター用の HTML ダッシュボード（REST API）

エラーのトラブルシューティング

エラー	原因	解決策
"InvalidRealloc"	ポジション範囲が広すぎる	--width を減らす（bin_step の制限を確認）
状態が "OPENING" のまま固まる	トランザクションが失敗した	エグゼキューターを停止し、範囲を縮小して再試行
"Insufficient funds"（ウォレットに資金がある）	RPC のレート制限、または金額の単位が誤っている	カスタム RPC キーを追加する。--amount がクオート資産単位であることを確認する
"Transaction simulation failed"	RPC のレート制限がシミュレーション失敗として現れている	カスタム RPC キーを追加する（Helius/QuickNode）
'meteora/clmm' KeyError	Gateway コネクターがまだ登録されていない	hummingbot-api PR #120+（feat/lp-executor ブランチ）を使用する
"No CLMM pool found for X-Y"	トークンシンボルの不一致	プールの正確なシンボルを使用する（例：PRCLT ではなく Percolator）
"meteora/clmm is not ready"	ボットが Gateway に到達できない	Gateway を --network host 付きの Docker コンテナとして実行する。macOS 上の開発モード Gateway はコンテナから到達できない
"Failed to load strategy" / パスワードエラー	ボットの conf に .password_verification がない	bots/credentials/master_account/.password_verification から bots/bots/instances/<bot>/conf/ にコピーする
candles_config / markets extra inputs	古いスクリプト設定フォーマット	最小限の設定を使用する：controllers_config と script_file_name のみ
ボットが API では "stopped" と表示されるが Docker では実行中	MQTT が接続されていない	ボットは実行中だが、API が MQTT 経由で認識できていない。ボットのログを直接確認する

---

重要な注意点

これらは本番環境で実際に混乱を引き起こしました — デプロイ前に必ず読んでください。

1. total_amount_quote は常にクオート資産単位です

クオート資産は取引ペアの2番目のトークンです：

ペア	クオート資産	例：約 $100 相当の 100k ベーストークンをデプロイ
Percolator-SOL	SOL	--amount 1.33（1.33 SOL ≈ $108）
SOL-USDC	USDC	--amount 108（108 USDC）
RAY-SOL	SOL	--amount 2.5（2.5 SOL）

--side 2（SELL/ベースのみ）の場合でも、価値はクオート単位で表現します。換算：base_tokens × price_in_quote = total_amount_quote。

2. すべての *_pct パラメータはすでにパーセント単位です

パラメータ	正しい	誤り
position_width_pct: 10	10% の範囲	0.10
position_offset_pct: 1	1% のオフセット	0.01
rebalance_threshold_pct: 1	1% のしきい値	0.01

3. トークンシンボルはプールと完全に一致させる必要があります

Gateway にトークンを追加して --pair を設定する際は、プールの正確なシンボル（get_meteora_pool.py または Meteora UI から取得）を使用してください：

# Check pool token symbols first
python scripts/get_meteora_pool.py <pool_address>
# Look at "Symbol" column — use that exact string in --pair and when adding token to Gateway

例：Percolator トークンのシンボルは Percolator です（PRCLT ではありません）。--pair Percolator-SOL を使用してください。

4. デプロイ前にカスタム RPC が必須です（任意ではありません）

公開 Solana RPC（api.mainnet-beta.solana.com）はボットに対してレート制限をかけ、以下の問題が発生します：

• 「残高不足」エラー（ウォレットに資金がある場合でも）
• 「トランザクションシミュレーション失敗」
• 10 回のリトライ後にポジションのオープンが失敗

デプロイ前に必ずカスタム RPC を設定してください：

# Edit Gateway conf
GATEWAY_DIR=~/.openclaw/workspace/hummingbot-gateway  # or your gateway dir
nano "$GATEWAY_DIR/conf/chains/solana/mainnet-beta.yml"
# Set: nodeURL: https://mainnet.helius-rpc.com/?api-key=YOUR_KEY

https://helius.dev で無料のキーを取得できます。その後、Gateway を再起動してください。

5. macOS では Gateway を Docker（開発モードではなく）で実行する必要があります

macOS では、Docker コンテナはホスト上で実行されているプロセスに到達できません（--network host を使用しても同様です）。ボットコンテナは、開発モード（pnpm start）で実行されている Gateway に接続できません。

必ず Gateway を Docker として実行してください：

docker run -d --name gateway \
  --network host \
  -e GATEWAY_PASSPHRASE=hummingbot \
  -v ~/.openclaw/workspace/hummingbot-gateway/conf:/home/gateway/conf \
  -v ~/.openclaw/workspace/hummingbot-gateway/certs:/home/gateway/certs \
  hummingbot/gateway:development

その後、ボットの conf_client.yml で：gateway_api_host: localhost（macOS の Docker 内では、gateway も host ネットワークを使用する Docker である場合、ホストネットワーキングが正しく解決されます）。

6. latest ではなく hummingbot:development イメージを使用してください

latest イメージには LP エグゼキューターのサポートが含まれていない可能性があります。必ず以下でデプロイしてください：

python scripts/manage_controller.py deploy my_bot --configs my_config
# manage_controller.py defaults to hummingbot/hummingbot:development

7. --amount を計算する前にウォレット残高を確認してください

python scripts/add_wallet.py balances

どのトークンアカウントに資金があるかを確認してください — ウォレットには複数の SPL トークンアカウントがあり、残高が想定と異なる場合があります。特定のトークンアカウントの利用可能残高のみがデプロイできます。

8. ポジションのクローズ

プール上のすべてのポジションをクローズするには：

# List open positions
curl -s "http://localhost:15888/connectors/meteora/clmm/positions-owned?network=mainnet-beta&walletAddress=<WALLET>" 

# Close each position
curl -s -X POST http://localhost:15888/connectors/meteora/clmm/close-position \
  -H "Content-Type: application/json" \
  -d '{"network":"mainnet-beta","address":"<WALLET>","positionAddress":"<POSITION>"}'

注意：Gateway にアクセスできる必要があります。macOS で Gateway が host ネットワーキングを使用する Docker 内にある場合は、docker run --rm --network host alpine/curl ... を使用してください。 | 「残高不足」 | トークンが足りない | ウォレットにトークン + レント用の 0.06 SOL があるか確認してください |