Okx Defi Invest

OKX DeFi Invest

Multi-chain DeFi product discovery and investment execution. The CLI handles precision conversion, multi-step orchestration, and validation internally.

For CLI parameter details, see references/cli-reference.md.

Skill Routing

• For DApp-named investing/lending/staking → use okx-dapp-discovery
• For DeFi positions / holdings → use okx-defi-portfolio
• For token price/chart → use okx-dex-market
• For token search by name/contract → use okx-dex-token
• For DEX spot swap execution → use okx-dex-swap
• For wallet token balances → use okx-wallet-portfolio
• For broadcasting signed transactions → use okx-onchain-gateway
• For Agentic Wallet login, balance, contract-call → use okx-agentic-wallet

Command Index

Investment Types

Chain Support

CLI resolves chain names automatically (e.g. ethereum → 1, bsc → 56, solana → 501).

Operation Flow

Step 0: Address Resolution

When the user does NOT provide a wallet address, resolve it automatically from the Agentic Wallet before running any defi command:

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

Rules:

• If the user provides an explicit address, use it directly — skip this step
• If wallet is not logged in, ask the user to log in first (→ okx-agentic-wallet) or provide an address manually
• If the user says "check all accounts" or "all wallets", use wallet balance --all to get all account IDs, then wallet switch <id> + wallet addresses for each account
• Always confirm the resolved address with the user before proceeding if the account has multiple addresses of the same type

Deposit (invest)

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-wallet-portfolio) → 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 decimal: Get tokenAddress from defi detail → underlyingToken[].tokenAddress, then use token search --query <tokenAddress> to get decimal. Same approach as DEX swap.

CRITICAL — Balance check is REQUIRED before calling defi invest. You MUST call okx-wallet-portfolio to verify the user has sufficient balance of the deposit token BEFORE generating calldata. If balance is insufficient, STOP and warn the user. Do NOT proceed to defi invest without confirming balance. Skipping this step wastes gas and results in failed on-chain transactions.

Withdraw

CRITICAL — position-detail is MANDATORY before withdraw. You MUST call defi position-detail immediately before every defi withdraw, even if you already have position data from a previous call. Do NOT reuse stale position-detail results.

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

Partial exit --amount: position-detail returns coinAmount in human-readable (e.g. "2.3792") and tokenPrecision (e.g. 6). Convert to minimal units: floor(2.3792 × 10^6) = 2379200 → --amount 2379200.

Claim Rewards

CRITICAL — position-detail is MANDATORY before collect. You MUST call defi position-detail immediately before every defi collect, even if you already have position data from a previous call in the conversation. Position data (rewards, investmentId, platformId, tokenId) changes after each on-chain operation (withdraw, previous collect, etc.), so stale data leads to wrong parameters or failed transactions. Do NOT skip this step. Do NOT reuse position-detail results from earlier in the conversation.

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 Pool Deposit

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-wallet-portfolio) → 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

View Chart Data

Use chart commands to analyze product trends before investing or to monitor existing positions.

APY History — check yield trend before depositing:

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

• Time ranges: WEEK (default), MONTH, SEASON (3 months), YEAR. DAY is V3 Pool only.
• Returns: timestamp, rate (APY), bonusRate (extra rewards), limitValue (1=peak, -1=trough).

TVL History — evaluate pool size stability:

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

• Time ranges: same as rate-chart.
• Returns: chartVos[] with timestamp, tvl (USD), limitValue.

V3 Depth Chart — see liquidity concentration to pick optimal tick range:

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

• Returns: tick, liquidity, liquidityNet, token0Price, token1Price per tick.
• No --time-range parameter — DEPTH mode always returns current snapshot.
• Use this before V3 Pool deposit to identify where liquidity is concentrated and choose tickLower/tickUpper accordingly.

V3 Price History — see historical relative price between token0 and token1:

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

• Chart types: DEPTH (default), PRICE.
• --time-range only applies to PRICE mode: DAY (default), WEEK.
• Returns: token0Price, token1Price, timestamp per data point.

Step 3: Sign & Broadcast Calldata

After invest/withdraw/collect returns dataList, execute each step via one of two paths:

Path A (user-provided wallet): user signs externally → broadcast via gateway

# 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

Path B (Agentic Wallet): sign & broadcast via wallet contract-call

EVM chains (Ethereum, BSC, Polygon, Arbitrum, Base, etc.):

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 handles TEE signing and broadcasting internally — no separate broadcast step needed.

--value unit conversion: dataList[].value is in minimal units (wei). contract-call --value expects UI units. Convert: value_UI = value / 10^nativeToken.decimal (e.g. 18 for ETH/POL, 9 for SOL). If value is "", "0", or "0x0", use "0".

--chain mapping: contract-call and gateway broadcast require realChainIndex (e.g. 1=Ethereum, 137=Polygon, 56=BSC, 501=Solana, 196=XLayer).

Execution rules:

• Execute dataList[0] first, then dataList[1], etc. Never in parallel.
• Wait for on-chain confirmation before next step (Path A: txStatus=2; Path B: contract-call returns txHash).
• If any step fails, stop all remaining steps and report which succeeded/failed.

invest/withdraw/collect only return unsigned calldata — they do NOT broadcast. The CLI never holds private keys.