• 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

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

• 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

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.

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

.

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

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

EVM chains (Ethereum, BSC, Polygon, Arbitrum, Base, etc.):
```bash
onchainos wallet contract-call \
  --to <dataList[N].to> \
  --chain <chainIndex> \
  --input-data <dataList[N].serializedData> \
  --value <value_in_UI_units>

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

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

contract-call

--value

dataList[].value

contract-call --value

value_UI = value / 10^nativeToken.decimal

value

""

"0"

"0x0"

"0"

--chain

contract-call

gateway broadcast

realChainIndex

1

137

56

501

196

• 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.

• investmentId

  is MANDATORY in every row

• rate

  is decimal → multiply by 100 and append

  %

• tvl

  → format as human-readable USD ($3.52B, $537M)
• Display data as-is — do NOT editorialize on APY values

• Aave borrow: uses

  callDataType=WITHDRAW

  internally — do not expose to user
• Aave repay: uses

  callDataType=DEPOSIT

  internally — do not expose to user
• V3 Pool exit: pass

  --token-id

  +

  --ratio

  (e.g.

  --ratio 1

  for full exit)
• Partial withdrawal (non-V3): pass

  --amount

  for the exit amount
• Full withdrawal:

  --ratio 1

• --amount

  must be in minimal units (integer). Convert: userAmount × 10^tokenPrecision. Example: 0.1 USDC (precision=6) →

  --amount 100000

  . Get tokenPrecision from

  defi detail

  or

  defi position-detail

• The wallet address parameter for ALL defi commands is

  --address

• --slippage

  default is

  "0.01"

  (1%); suggest

  "0.03"

  –

  "0.05"

  for volatile V3 pools
• CRITICAL — Solana transaction expiry: Solana DeFi transactions use base58-encoded VersionedTransaction with a blockhash that expires in ~60 seconds. After receiving calldata, you MUST warn the user: "This Solana transaction must be signed and broadcast within 60 seconds or it will expire. Please sign immediately." Do NOT proceed to other conversation without delivering this warning first.
• CRITICAL — High APY risk warning: When displaying search/list results, if any product has APY > 50% (rate > 0.5), you MUST warn the user: "WARNING: This product shows APY above 50%, which indicates elevated risk (potential impermanent loss, smart contract risk, or unsustainable rewards). Proceed with caution." Do NOT silently display high-APY products without this warning.
• CRITICAL — Address-chain compatibility: When calling

  defi positions

  or

  defi position-detail

  , the

  --address

  and chain parameters must be compatible. EVM addresses (

  0x…

  ) can only query EVM chains; Solana addresses (base58) can only query

  solana

  . Never mix them — the API will return error 84019 (Address format error).

  • 0x…

    address → only pass EVM chains:

    ethereum,bsc,polygon,arbitrum,base,xlayer,avalanche,optimism,fantom,linea,scroll,zksync

  • base58 address → only pass

    solana

  • If the user wants positions across both EVM and Solana, make two separate calls with the respective addresses
• User confirmation required before every invest/withdraw/collect execution
• Address used for calldata generation MUST match the signing address