okx-defi-invest

OKX DeFi 投資

マルチチェーン DeFi プロダクトの検索と投資の実行に対応します。CLI は、精度変換、複数ステップのオーケストレーション、検証を内部で処理します。

CLI パラメーターの詳細については、references/cli-reference.md を参照してください。

スキルの振り分け

• DApp 名が指定された投資／レンディング／ステーキングの場合 → okx-dapp-discovery を使用
• DeFi のポジション／保有資産の場合 → okx-defi-portfolio を使用
• トークン価格／チャートの場合 → okx-dex-market を使用
• 名前／コントラクトによるトークン検索の場合 → okx-dex-token を使用
• DEX の現物スワップ実行の場合 → okx-agentic-wallet を使用
• ウォレットのトークン残高の場合 → okx-agentic-wallet を使用
• 署名済みトランザクションのブロードキャストの場合 → okx-agentic-wallet を使用
• Agentic Wallet のログイン、残高、コントラクト呼び出しの場合 → okx-agentic-wallet を使用

コマンド一覧

#	コマンド	説明
1	defi support-chains	DeFi でサポートされているチェーンを取得
2	defi support-platforms	DeFi でサポートされているプラットフォームを取得
3	defi list	APY 上位の DeFi プロダクトを一覧表示
4	defi search --token <tokens> [--platform <names>] [--chain <chain>] [--product-group <group>]	DeFi プロダクトを検索
5	defi detail --investment-id <id>	プロダクトの詳細情報を取得
6	defi invest --investment-id <id> --address <addr> --token <symbol_or_addr> --amount <minimal_units> [--chain <chain>] [--slippage <pct>] [--tick-lower <n>] [--tick-upper <n>] [--token-id <nft>]	1 ステップで預け入れ（CLI が準備＋精度変換＋calldata の処理を行います）
7	defi withdraw --investment-id <id> --address <addr> --chain <chain> [--ratio <0-1>] [--amount <minimal_units>] [--token-id <nft>] [--platform-id <pid>] [--slippage <pct>]	1 ステップで出金（CLI がポジション検索＋calldata の処理を行います）
8	defi collect --address <addr> --chain <chain> --reward-type <type> [--investment-id <id>] [--platform-id <pid>] [--token-id <nft>] [--principal-index <idx>]	1 ステップで報酬を請求（CLI が報酬確認＋calldata の処理を行います）
9	defi positions --address <addr> --chains <chains>	プラットフォーム別に DeFi ポジションを一覧表示
10	defi position-detail --address <addr> --chain <chain> --platform-id <pid>	ポジションの詳細情報を取得
11	defi rate-chart --investment-id <id> [--time-range <range>]	APY の過去のチャートデータ
12	defi tvl-chart --investment-id <id> [--time-range <range>]	TVL の過去のチャートデータ
13	defi depth-price-chart --investment-id <id> [--chart-type <type>] [--time-range <range>]	V3 Pool の深度または価格履歴チャート

投資の種類

productGroup	説明
SINGLE_EARN	単一トークンの利回り（貯蓄、ステーキング、ボールト）
DEX_POOL	流動性プール（Uniswap V2/V3、PancakeSwap など）
LENDING	レンディング／借り入れ（Aave、Compound など）

チェーンのサポート

CLI はチェーン名を自動的に解決します（例：ethereum → 1、bsc → 56、solana → 501）。

操作フロー

ステップ 0：アドレスの解決

ユーザーがウォレットアドレスを指定していない場合は、defi コマンドを実行する前に、Agentic Wallet から自動的に解決します。

1. onchainos wallet status          → check if logged in, get active account
2. onchainos wallet addresses       → get addresses grouped by chain category:
                                       - XLayer addresses
                                       - EVM addresses (Ethereum, BSC, Polygon, etc.)
                                       - Solana addresses
3. Match address to target chain:
   - EVM chains → use EVM address
   - Solana     → use Solana address
   - XLayer     → use XLayer address

ルール：

• ユーザーが明示的にアドレスを指定した場合は、そのアドレスを直接使用し、このステップをスキップします
• ウォレットにログインしていない場合は、最初にログインする（→ okx-agentic-wallet）か、アドレスを手動で指定するようユーザーに依頼します
• ユーザーが「すべてのアカウントを確認」または「すべてのウォレット」と言った場合は、wallet balance --all を使用してすべてのアカウント ID を取得し、その後、各アカウントに対して wallet switch <id> ＋ wallet addresses を実行します
• 同じ種類のアドレスが複数あるアカウントの場合は、処理を進める前に、解決したアドレスを必ずユーザーに確認します

入金（投資）

1. defi search --token USDC --chain ethereum       → pick investmentId
2. defi detail --investment-id <id>                 → confirm APY/TVL, get underlyingToken[].tokenAddress
3. token search --query <tokenAddress> --chains <chain>  → get decimal (e.g. 6) for amount conversion
4. Ask user for amount → convert: userAmount × 10^decimal (e.g. 100 USDC → 100000000)
5. Check wallet balance (okx-agentic-wallet) → if insufficient, warn user and stop
6. defi invest --investment-id <id> --address <addr> --token USDC --amount 100000000
   → CLI returns calldata (APPROVE + DEPOSIT steps)
7. User signs and broadcasts each step in order

トークンの小数桁数：defi detail → underlyingToken[].tokenAddress から tokenAddress を取得し、token search --query <tokenAddress> を使って decimal を取得します。DEX スワップと同じ方法です。

重要 — defi invest を呼び出す前に、残高の確認が必須です。 calldata を生成する前に、必ず okx-agentic-wallet を呼び出して、ユーザーが入金トークンの十分な残高を持っていることを確認してください。残高が不足している場合は、処理を中止してユーザーに警告してください。残高を確認せずに defi invest に進んではいけません。この手順を省略すると、ガス代が無駄になり、オンチェーン取引が失敗します。

出金

重要 — 出金の前に position-detail を実行することが必須です。 以前の呼び出しでポジションデータを取得済みの場合でも、defi withdraw を実行するたびに、その直前に必ず defi position-detail を呼び出してください。古い position-detail の結果を再利用してはいけません。

1. defi positions --address <addr> --chains ethereum
2. defi position-detail --address <addr> --chain ethereum --platform-id <pid>
   → MUST be called fresh — get investmentId, tokenPrecision, coinAmount (current balance)
3. Full exit:
   defi withdraw --investment-id <id> --address <addr> --chain ethereum --ratio 1 --platform-id <pid>
   Partial exit (convert coinAmount to minimal units: amount × 10^tokenPrecision):
   defi withdraw --investment-id <id> --address <addr> --chain ethereum --amount <minimal_units> --platform-id <pid>
4. User signs and broadcasts

一部出金の --amount：position-detail は、coinAmount を人間が読みやすい形式（例：「2.3792」）、tokenPrecision を（例：6）で返します。最小単位に変換します：floor(2.3792 × 10^6) = 2379200 → --amount 2379200。

報酬の請求

重要 — 報酬の受け取り前に position-detail を実行することが必須です。 会話内の以前の呼び出しでポジションデータを取得済みの場合でも、defi collect を実行するたびに、その直前に必ず defi position-detail を呼び出してください。ポジションデータ（報酬、investmentId、platformId、tokenId）は各オンチェーン操作（出金、以前の報酬受け取りなど）の後に変化するため、古いデータを使うとパラメーターを誤ったり、取引に失敗したりします。この手順を省略してはいけません。会話の以前の時点で取得した position-detail の結果を再利用してはいけません。

1. defi positions --address <addr> --chains ethereum
2. defi position-detail --address <addr> --chain ethereum --platform-id <pid>
   → MUST be called fresh — do NOT reuse prior results
3. defi collect --address <addr> --chain ethereum --reward-type REWARD_INVESTMENT --investment-id <id> --platform-id <pid>
   → CLI returns calldata (or skips if no rewards)
4. User signs and broadcasts

V3 プールへの入金

1. defi search --token USDT --platform PancakeSwap --chain bsc --product-group DEX_POOL
2. defi detail --investment-id <id>
3. (Optional) defi depth-price-chart --investment-id <id>
   → show liquidity depth distribution to help user pick tick range
4. Ask user for amount and tick range
5. Check wallet balance (okx-agentic-wallet) → if insufficient, warn user and stop
6. defi invest --investment-id <id> --address <addr> --token USDT --amount 100000000 --range 5
   → CLI handles calculate-entry internally, returns calldata
7. User signs and broadcasts

チャートデータの表示

投資前にプロダクトの傾向を分析したり、既存のポジションを監視したりするには、チャートコマンドを使います。

APY 履歴 — 入金前に利回りの傾向を確認します：

defi rate-chart --investment-id <id> --time-range MONTH

• 期間：WEEK（デフォルト）、MONTH、SEASON（3 か月）、YEAR。DAY は V3 プールのみです。
• 戻り値：timestamp、rate（APY）、bonusRate（追加報酬）、limitValue（1=ピーク、-1=谷）。

TVL 履歴 — プール規模の安定性を評価します：

defi tvl-chart --investment-id <id> --time-range SEASON

• 期間：rate-chart と同じです。
• 戻り値：timestamp、tvl（USD）、limitValue を含む chartVos[]。

V3 デプスチャート — 流動性の集中状況を確認し、最適なティック範囲を選びます：

defi depth-price-chart --investment-id <id>

• ティックごとの戻り値：tick、liquidity、liquidityNet、token0Price、token1Price。
• --time-range パラメーターはありません。DEPTH モードは常に現在のスナップショットを返します。
• V3 プールへの入金前にこのチャートを使い、流動性の集中箇所を特定して、それに応じて tickLower／tickUpper を選択します。

V3 価格履歴 — token0 と token1 の過去の相対価格を確認します：

defi depth-price-chart --investment-id <id> --chart-type PRICE --time-range WEEK

• チャートタイプ：DEPTH（デフォルト）、PRICE。
• --time-range は PRICE モードにのみ適用されます：DAY（デフォルト）、WEEK。
• データポイントごとの戻り値：token0Price、token1Price、timestamp。

ステップ 3：Calldata に署名してブロードキャストする

invest／withdraw／collect が dataList を返したら、次の 2 つの方法のいずれかで各ステップを実行します。

方法 A（ユーザー提供のウォレット）： ユーザーが外部で署名し、ゲートウェイ経由でブロードキャストします

# For each dataList step:
# 1. User signs the tx externally using dataList[N].to, dataList[N].serializedData, dataList[N].value
# 2. Broadcast:
onchainos gateway broadcast --signed-tx <signed_hex> --address <addr> --chain <chain>
# 3. Poll until confirmed:
onchainos gateway orders --address <addr> --chain <chain> --order-id <orderId>
# → wait for txStatus=2, then proceed to next step

方法 B（Agentic Wallet）： wallet contract-call で署名してブロードキャストします

EVM チェーン（Ethereum、BSC、Polygon、Arbitrum、Base など）：

onchainos wallet contract-call \
  --to <dataList[N].to> \
  --chain <chainIndex> \
  --input-data <dataList[N].serializedData> \
  --value <value_in_UI_units> \
  --biz-type defi

EVM（XLayer）：

onchainos wallet contract-call \
  --to <dataList[N].to> \
  --chain 196 \
  --input-data <dataList[N].serializedData> \
  --value <value_in_UI_units> \
  --biz-type defi

Solana：

onchainos wallet contract-call \
  --to <dataList[N].to> \
  --chain 501 \
  --unsigned-tx <dataList[N].serializedData> \
  --biz-type defi

contract-call は TEE での署名とブロードキャストを内部で処理するため、別途ブロードキャストする必要はありません。

--value の単位変換： dataList[].value は最小単位（wei）です。contract-call --value には UI 単位を指定します。次のように変換します：value_UI = value / 10^nativeToken.decimal（例：ETH／POL は 18、SOL は 9）。value が ""、"0"、または "0x0" の場合は、"0" を使用します。

--chain のマッピング： contract-call と gateway broadcast には realChainIndex が必要です（例：1＝Ethereum、137＝Polygon、56＝BSC、501＝Solana、196＝XLayer）。

実行ルール：

• 最初に dataList[0] を実行し、次に dataList[1] などを実行します。並列実行はしないでください。
• 次のステップに進む前に、オンチェーンでの確認を待ちます（方法 A：txStatus=2、方法 B：contract-call が txHash を返す）。
• いずれかのステップが失敗した場合は、残りのステップをすべて停止し、成功／失敗したステップを報告します。

invest／withdraw／collect が返すのは未署名の calldataのみであり、ブロードキャストは行いません。CLI が秘密鍵を保持することはありません。

検索結果／一覧結果の表示

#	プラットフォーム	チェーン	investmentId	名前	APY	TVL
1	Aave V3	ETH	9502	USDC	1.89%	$3.52B

• すべての行に investmentId が必須です。
• rate は小数値です。100 を掛けて % を付けます。
• tvl は読みやすい USD 表記（$3.52B、$537M）にします。
• データはそのまま表示してください。APY 値について独自の見解を加えないでください。

rewardType のリファレンス

rewardType	使用するタイミング	必須パラメーター
REWARD_PLATFORM	プロトコルレベルの報酬（例：AAVE トークン）	--platform-id
REWARD_INVESTMENT	プロダクトのマイニング／ステーキング報酬	--investment-id + --platform-id
V3_FEE	V3 の取引手数料の受け取り	--investment-id + --token-id
REWARD_OKX_BONUS	OKX ボーナス報酬	--investment-id + --platform-id
REWARD_MERKLE_BONUS	Merkle プルーフに基づくボーナス	--investment-id + --platform-id
UNLOCKED_PRINCIPAL	ロック解除後の元本	--investment-id + --principal-index

主なプロトコルルール

• Aave の借入： 内部的に callDataType=WITHDRAW を使用します。ユーザーには表示しないでください。
• Aave の返済： 内部的に callDataType=DEPOSIT を使用します。ユーザーには表示しないでください。
• V3 Pool の退出： --token-id と --ratio を渡します（例：全額退出の場合は --ratio 1）。
• 一部引き出し（V3 以外）： 退出する金額を --amount で渡します。
• 全額引き出し： --ratio 1

実行後の提案

直前に完了した操作	提案
defi list ／ defi search	詳細を表示 → defi detail、または入金フローを開始
defi detail	推移を確認 → defi rate-chart ／ defi tvl-chart、または次へ進む → defi invest
defi detail（V3 Pool）	深度を表示 → defi depth-price-chart、価格履歴を確認 → defi depth-price-chart --chart-type PRICE
defi invest 成功	ポジションを表示 → okx-defi-portfolio、またはさらに検索
defi withdraw 成功	ポジションを確認 → okx-defi-portfolio、または残高を確認 → okx-agentic-wallet
defi collect 成功	ポジションを確認 → okx-defi-portfolio、または報酬をスワップ → okx-agentic-wallet

エラーコード

コード	シナリオ	対処方法
84400	パラメーターが null	必須パラメーターを確認してください。一部だけを退出する場合は --amount または --ratio が必要です
84021	資産を同期中	「ポジションデータを同期中です。しばらくしてから再試行してください」
84023	expectOutputList が無効	CLI が position-detail から自動構築します。再試行するか、--platform-id を渡してください
84014	残高チェックに失敗	残高が不足しています。okx-agentic-wallet で確認してください
84018	バランス調整に失敗	V3 のバランス調整に失敗しました。価格範囲を調整するか、スリッページを増やしてください
84010	トークンが未対応	defi detail で対応トークンを確認してください
84001	プラットフォームが未対応	DeFi プラットフォームは未対応です
84016	コントラクトの実行に失敗	パラメーターを確認して再試行してください
84019	アドレス形式が一致しない	このチェーンではアドレス形式が無効です
50011	レート制限	待ってから再試行してください

全般的な注意事項

• --amount は最小単位（整数）で指定する必要があります。換算式：ユーザー指定額 × 10^トークン精度。例：0.1 USDC（精度=6）→ --amount 100000。tokenPrecision は defi detail または defi position-detail から取得してください
• すべての defi コマンドでウォレットアドレスを指定するパラメーターは --address です
• --slippage のデフォルト値は "0.01"（1%）です。価格変動の大きい V3 プールでは "0.03"～"0.05" を推奨してください
• 重大 — Solana トランザクションの有効期限：Solana の DeFi トランザクションでは、有効期限が約 60 秒のブロックハッシュを含む、base58 でエンコードされた VersionedTransaction を使用します。calldata を受け取った後、必ず次の警告をユーザーに伝えてください。「この Solana トランザクションは、60 秒以内に署名してブロードキャストしないと有効期限が切れます。すぐに署名してください。」この警告を伝える前に、ほかの会話に進んではいけません。
• 重大 — 高 APY のリスク警告：検索結果または一覧結果を表示する際、APY が 50% を超える商品（rate > 0.5）がある場合、必ず次の警告をユーザーに伝えてください。「警告：この商品の APY は 50% を超えています。これはリスクが高いこと（インパーマネントロス、スマートコントラクトのリスク、または持続不可能な報酬の可能性）を示します。慎重にご利用ください。」この警告なしに、高 APY の商品を表示してはいけません。
• 重大 — アドレスとチェーンの互換性：defi positions または defi position-detail を呼び出す場合、--address とチェーンのパラメーターは互換性がなければなりません。EVM アドレス（0x…）で照会できるのは EVM チェーンのみです。Solana アドレス（base58）で照会できるのは solana のみです。混在させてはいけません。API はエラー 84019（アドレス形式エラー）を返します。
  • 0x… アドレス → EVM チェーンのみを渡してください：ethereum,bsc,polygon,arbitrum,base,xlayer,avalanche,optimism,fantom,linea,scroll,zksync
  • base58 アドレス → solana のみを渡してください
  • ユーザーが EVM と Solana の両方のポジションを希望する場合は、それぞれのアドレスを使用して2 回に分けて呼び出してください
• 投資、出金、報酬受け取りを実行する前に、毎回ユーザーの確認が必要です
• calldata の生成に使用するアドレスは、署名に使用するアドレスと一致していなければなりません