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>]	一步存入（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>]	一步提取（CLI 处理仓位查询和 calldata）
8	defi collect --address <addr> --chain <chain> --reward-type <type> [--investment-id <id>] [--platform-id <pid>] [--token-id <nft>] [--principal-index <idx>]	一步领取奖励（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 池深度或价格历史图表

投资类型

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

Token 精度：从 defi detail → underlyingToken[].tokenAddress 获取 tokenAddress，然后使用 token search --query <tokenAddress> 获取 decimal。方法与 DEX swap 相同。

重要 — 调用 defi invest 前必须检查余额。 生成 calldata 前，必须调用 okx-agentic-wallet，确认用户持有足够的存入 Token。若余额不足，请立即停止并警告用户。未确认余额前，请勿继续调用 defi invest。跳过此步骤会浪费 Gas，并导致链上交易失败。

提取

重要 — 提取前必须调用 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。

领取奖励

重要 — collect 前必须调用 position-detail。 每次调用 defi collect 前，都必须立即调用 defi position-detail，即使对话中之前的调用已获取持仓数据也不例外。每次链上操作（提取、之前的 collect 等）后，持仓数据（rewards、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 Pool。
• 返回：每个数据点的 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 深度图 — 查看流动性集中情况，以选择最佳 tick 范围：

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

• 返回每个 tick 的 tick、liquidity、liquidityNet、token0Price、token1Price。
• 没有 --time-range 参数 — DEPTH 模式始终返回当前快照。
• 在存入 V3 Pool 前使用此图，确定流动性集中区域，并据此选择 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 后，通过以下两种方式之一执行每个步骤：

方式 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 → 格式化为易读的美元金额（$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

错误代码

Code	场景	处理方式
84400	参数为空	检查必需参数 — 部分退出需要 --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。可通过 defi detail 或 defi position-detail 获取代币精度
• 所有 DeFi 命令的钱包地址参数均为 --address
• --slippage 默认值为 "0.01"（1%）；对于波动较大的 V3 池，建议使用 "0.03"–"0.05"
• 重要 — Solana 交易过期：Solana DeFi 交易使用 base58 编码的 VersionedTransaction，其中包含的区块哈希约 60 秒后过期。收到 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 上的持仓，请使用对应的地址分别进行两次调用
• 每次执行投资/提现/领取操作前，都必须征得用户确认
• 用于生成 calldata 的地址必须与签名地址一致