/binance-agentic-wallet

DeFi Commands

Query DeFi protocols, investment opportunities, and the user's DeFi positions. Execute DeFi transactions (deposit, redeem, LP, claim).

Sign-in required: All DeFi commands require an active Agentic Wallet session. If the user is not signed in, ask them to sign in first (auth signin) before running any defi command.

Preview before executing: Before running any state-changing command (deposit, redeem, lp-add, lp-remove, claim), call defi preview --action <action> ... with the same parameters first. Show the user the estimated fee, balance changes, and any warnings. Only proceed after the user confirms, unless the user explicitly asks to skip confirmation.

Post-trade verification

After a successful state-changing call (deposit / redeem / lp-add / lp-remove / claim), backend data is not immediately consistent — there is a delay before the change reflects in subsequent reads. Follow these rules when the user asks to verify the result:

1. Set expectations on submit. A returned txHash only means the transaction was submitted — it may still be pending in the mempool, and it could still fail on-chain (revert, run out of gas, be dropped). Tell the user something like "submitted; not yet confirmed on-chain. Data may take a moment to update, ask any time to check." Do NOT claim the deposit / redeem / claim is complete, and do NOT call any verification query immediately after — it will just show stale data.

2. First verification = normal query, no --refresh. When the user asks to check, call defi position without --refresh. Most of the time data is already updated.

3. If the data still doesn't look updated after the normal query, you MAY call defi position --refresh once. Do NOT chain multiple --refresh calls back-to-back — --refresh is server-side rate-limited, and refreshes should be spaced at least several minutes apart. This is the only sanctioned exception to the "don't pass --refresh by default" rule.

4. On rate-limit errors from --refresh:

   • Do NOT surface the raw error to the user.
   • Fall back to a regular query (no --refresh) and present whatever data is available.
   • Tell the user data may still be syncing and to retry after a few minutes.

5. Never claim "transaction failed" based on a stale read. A txHash is only proof that the tx was submitted — it does NOT prove it succeeded on-chain. Backend position queries also lag behind the chain, so a stale read is not evidence of failure either. If verification queries still show no change, the answer is "syncing — check the block explorer for the tx's on-chain status", not "it failed".

Display Rules (apply to ALL defi commands)

When summarizing or rendering any field below to the user, format to exactly 2 decimal places (round half-up). Do not drop trailing zeros, do not switch to scientific notation, do not omit the unit.

Notes for the model:

• apyDisplay is pre-formatted by the backend (e.g. "99.63%", "6,800.00%"). Quote it verbatim when showing APY/APR to the user — never re-compute, re-round, reformat, or drop the thousands separator.
• apyBps is the numeric APY in basis points (1 bps = 0.01%): "9963" = 99.63%, "680000" = 6,800.00%. Use apyBps only for sorting, filtering, and comparisons (e.g. "top 3 by APY") — never for display. Do NOT multiply, divide, or convert it.
• The raw decimal apy field is no longer returned. If you need an APY number for reasoning, use apyBps; if you need to show it to the user, use apyDisplay.
• APY/APR is base APY only — it does NOT include earn campaign / promotional APY. Numbers may differ from values shown on the protocol's official website. Mention this if the user asks why the number differs.
• At the protocol level (defi protocol-list), APY is the MAX APY across all the protocol's pools / investments — not every pool yields this rate. When presenting to the user, call it "max APY" or "up to X%" so they don't assume every position under this protocol earns that same rate. To see the per-investment APY, use defi investment-list --defiProtocolId <id>.
• apyType tells you whether the rate is "APY" (compounded) or "APR" (simple). It only labels the rate — the display string is still apyDisplay.
• Token amounts (tokenAmount) keep their original precision (8+ decimals); do not force them to 2 decimals.
• Numeric IDs (nftId, tickLower, tickUpper, unlockTime, chain IDs) are integers; never reformat.

defi protocol-list

List DeFi protocols with TVL and APY metrics.

Syntax

baw defi protocol-list [--binanceChainId <binanceChainId>] [--investType <investType>] [--sortField <sortField>] [--sortDirection <sortDirection>] [--page <page>] [--size <size>] --json

Parameters

Example

baw defi protocol-list --binanceChainId 56 --investType Earn --json

Response

{
  "success": true,
  "data": {
    "total": 2,
    "list": [
      {
        "defiProtocolId": "protocol_abc",
        "protocolName": "Protocol ABC",
        "description": "...",
        "protocolLogo": "https://...",
        "tvl": "1187356864",
        "apyBps": 2900,
        "apyDisplay": "29.00%",
        "investType": ["Earn"],
        "supportedChains": ["56"]
      }
    ]
  }
}

defi protocol-info

Get detailed information about a specific DeFi protocol.

Syntax

baw defi protocol-info --defiProtocolId <defiProtocolId> --json

Parameters

Example

baw defi protocol-info --defiProtocolId protocol_abc --json

Response

{
  "success": true,
  "data": {
    "defiProtocolId": "protocol_abc",
    "protocolName": "Protocol ABC",
    "protocolLogo": "https://...",
    "description": "...",
    "websiteUrl": "https://...",
    "investType": ["Earn"],
    "supportedChains": ["56"],
    "tvl": "1187356864",
    "tags": ["DeFi", "Lending"],
    "founded": "2020",
    "fdv": "83304822.86",
    "totalFunding": null,
    "socialLinks": { "x": "...", "discord": null, "github": null, "linkedin": null },
    "team": [ { "name": "...", "role": "...", "twitter": "...", "linkedin": "...", "bio": "..." } ],
    "fundRaising": [ { "round": "Seed", "amount": "...", "date": "...", "investors": ["..."] } ],
    "securityScore": "85",
    "dimensionScores": { "codeSecurity": "...", "fundamentalHealth": "..." },
    "highlights": ["..."],
    "faq": [ { "title": "...", "answer": "..." } ]
  }
}

defi investment-list

List DeFi investment opportunities. investType is required.

Syntax

baw defi investment-list --investType <investType> [--defiProtocolId <defiProtocolId>] [--contractAddresses <addresses>] [--binanceChainId <binanceChainId>] [--sortField <sortField>] [--sortDirection <sortDirection>] [--page <page>] [--size <size>] --json

Parameters

Example

baw defi investment-list --investType Earn --defiProtocolId protocol_abc --json

Response

{
  "success": true,
  "data": {
    "total": 21,
    "list": [
      {
        "binanceChainId": "56",
        "defiProtocolId": "protocol_abc",
        "protocolName": "Protocol ABC",
        "investmentId": "0e82...",
        "investmentName": "TOKEN_A",
        "investType": "Earn",
        "apyType": "APY",
        "apyBps": 400,
        "apyDisplay": "4.00%",
        "tvl": "2851031.25"
      }
    ]
  }
}

defi investment-info

Get full details for a single investment.

Syntax

baw defi investment-info --investmentId <investmentId> --json

Parameters

Example

baw defi investment-info --investmentId 0e82... --json

Response

{
  "success": true,
  "data": {
    "binanceChainId": "56",
    "defiProtocolId": "protocol_abc",
    "protocolName": "Protocol ABC",
    "protocolLogo": "https://...",
    "investmentId": "...",
    "investmentName": "TOKEN_A",
    "investType": "Earn",
    "investable": true,
    "apyBps": 400,
    "apyDisplay": "4.00%",
    "apyType": "APY",
    "tvl": "2851031.25",
    "poolAddress": null,
    "feeRate": null,
    "assetTokenList": [ { "tokenAddress": "0x4bd1...", "tokenName": "Token A", "tokenSymbol": "TKA" } ],
    "rewardTokenList": [ { "tokenAddress": "0x...", "tokenName": "...", "tokenSymbol": "RWD" } ],
    "lpTokenList": null,
    "borrowTokenList": null
  }
}

Field notes

defi position

Query the user's DeFi positions across all supported protocols. Returns a hierarchical structure: Protocol → Pool → PositionCollection → Position → Token.

Syntax

baw defi position [--address <address>] [--binanceChainId <binanceChainId>] [--defiProtocolId <defiProtocolId>] [--refresh] --json

Parameters

Example

# All positions for the connected wallet
baw defi position --json

# Filter by a specific protocol
baw defi position --defiProtocolId protocol_abc --json

# Force refresh — only when the user explicitly asks to refresh / sync / reload positions
baw defi position --refresh --json

Response Structure (4-Layer Hierarchy)

Response
└── deFiTotalValue  (USD total across all protocols)
└── deFiProtocolVOList[]                       ← Protocol layer
    ├── binanceChainId / protocolId / defiProtocolId / protocolName
    ├── protocolTotalValue
    ├── healthRiskThresholds  (JSON string with health-factor color thresholds for Lending)
    └── poolList[]                              ← Pool layer
        ├── bnPoolId / poolCa / poolType / poolTemplateCode
        ├── poolDetail  (feeTier, spokeName, vaultName, etc — varies by poolType)
        └── positionCollectionList[]            ← PositionCollection layer
            ├── positionCollectionId / positionCollectionTotalValue
            ├── positionCollectionDetail  (healthRate for Lending, collectionDisplayName)
            └── positionList[]                   ← Position layer
                ├── positionId / underlyingAssetName / underlyingAssetId
                ├── assetType  (null / "locked" / "farming")
                ├── investmentIds[]
                ├── positionDetail  (nftId, tickLower, tickUpper, unlockTime, ...)
                └── tokenList                    ← Token layer (grouped by type)
                    ├── supply: TokenVO[]
                    ├── borrow: TokenVO[]
                    └── reward: TokenVO[]

Field Reference Guide

How to Read the Response (AI Guide)

Different user questions need different layers:

Derived insights (compute at render time, not in the response)

Some user-facing concepts are NOT returned directly by defi position — derive them by inspecting the response:

Display Rules (position-specific)

• Always show contract addresses alongside token symbols (token symbols can be spoofed).
• Group by protocolName when summarizing — same defiProtocolId may span multiple protocolIds.
• Highlight risk: if any Lending collection has healthRate < 1.5, surface a warning. Don't auto-act.
• Don't fabricate price-range conversions: tickLower/tickUpper are raw ticks. Only convert to USD price if the user explicitly asks.
• For numeric formatting (USD values, APY/APR, health factor, ratios) follow the global Display Rules at the top of this document.

Example (Abbreviated)

{
  "success": true,
  "data": {
    "deFiTotalValue": "1807.99",
    "deFiProtocolVOList": [
      {
        "binanceChainId": "56",
        "protocolId": "bsc_protocol_abc",
        "defiProtocolId": "protocol_abc",
        "protocolName": "Protocol ABC",
        "protocolTotalValue": "57.40",
        "healthRiskThresholds": "{...}",
        "poolList": [
          {
            "poolType": "Lending",
            "poolTemplateCode": "Lending_Hub_Spoke",
            "poolDetail": { "spokeName": "Main Market" },
            "positionCollectionList": [
              {
                "positionCollectionDetail": { "healthRate": "1.85" },
                "positionList": [
                  {
                    "underlyingAssetName": "USDT",
                    "tokenList": {
                      "supply": [
                        { "tokenSymbol": "USDT", "tokenAddress": "0x55d3...", "tokenAmount": "100", "tokenValue": "100.00" }
                      ]
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

defi deposit

Deposit / stake / supply assets to a DeFi protocol.

Syntax

baw defi deposit --investmentId <investmentId> --tokenAddress <tokenAddress> --amount <amount> [--gasLevel <gasLevel>] --json

Parameters

Example

baw defi deposit --investmentId 0e82... --tokenAddress 0x55d398326f99059fF775485246999027B3197955 --amount 1.5 --json

Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123..."
  }
}

defi redeem

Redeem / unstake / withdraw assets from a DeFi protocol.

Syntax

baw defi redeem --investmentId <investmentId> --tokenAddress <tokenAddress> [--amount <amount>] [--ratio <ratio>] [--gasLevel <gasLevel>] --json

Parameters

*Either --amount or --ratio must be provided.

Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123...",
    "redeemDelayDays": ["7", "15"]
  }
}

Field notes

Two-phase redemption flow

For protocols with non-empty redeemDelayDays (e.g. a staking protocol 7-day unstake):

1. Phase 1 — submit redeem: user calls defi redeem .... Returns a txHash and redeemDelayDays. The position enters a redemption-in-progress state — see Derived insights → redemption in progress in defi position.
2. Phase 2 — claim matured redemption: after the delay elapses, the position becomes claimable. User must explicitly call defi claim --claimType REDEMPTION --redemptionId <id> ... to actually receive the unstaked funds.

For protocols with no delay, redeem is single-step — no Phase 2 needed.

defi lp-add

Add liquidity to an LP position (create new or top up existing).

You name one token; the wallet debits BOTH. An LP position requires both pool tokens, but lp-add only takes one --tokenAddress + --amount. The wallet does not swap the input into the paired token; the user must already hold both tokens in the correct ratio for the chosen price range.

Syntax

baw defi lp-add --investmentId <investmentId> --tokenAddress <tokenAddress> --amount <amount> [--nftId <nftId>] [--priceRange <percent>] [--tickLower <tickLower>] [--tickUpper <tickUpper>] [--slippageBps <slippageBps>] [--gasLevel <gasLevel>] --json

Parameters

*Provide exactly one position source: --nftId, --priceRange, or --tickLower+--tickUpper.

Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123..."
  }
}

defi lp-remove

Remove liquidity from an LP position.

Syntax

baw defi lp-remove --investmentId <investmentId> --nftId <nftId> --ratio <ratio> [--slippageBps <slippageBps>] [--gasLevel <gasLevel>] --json

Parameters

Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123..."
  }
}

defi claim

Claim LP fees, protocol/investment rewards, or matured redemptions.

Syntax

baw defi claim --claimType <claimType> [--investmentId <investmentId>] [--defiProtocolId <defiProtocolId>] [--nftId <nftId>] [--redemptionId <redemptionId>] [--tokenAddress <tokenAddress>] [--gasLevel <gasLevel>] [--binanceChainId <binanceChainId>] --json

Parameters

*Required params depend on --claimType.

Response

{
  "success": true,
  "data": {
    "txHash": "0xabc123..."
  }
}

defi preview

Preview a DeFi transaction without broadcasting. Returns estimated gas, balance changes, and warnings.

Syntax

baw defi preview --action <action> [--investmentId <investmentId>] [--tokenAddress <tokenAddress>] [--amount <amount>] [--ratio <ratio>] [--nftId <nftId>] [--priceRange <percent>] [--tickLower <tickLower>] [--tickUpper <tickUpper>] [--slippageBps <slippageBps>] [--claimType <claimType>] [--defiProtocolId <defiProtocolId>] [--gasLevel <gasLevel>] [--binanceChainId <binanceChainId>] --json

Parameters

Example

baw defi preview --action DEPOSIT --investmentId 0e82... --tokenAddress 0x55d3... --amount 1.5 --json

Response

{
  "success": true,
  "data": {
    "balanceChange": [
      { "tokenSymbol": "USDT",  "tokenAddress": "0x55d398...", "amount": "-1.5", "valueUsd": "1.50" },
      { "tokenSymbol": "vUSDT", "tokenAddress": "0xfd5840...", "amount": "1.5",  "valueUsd": "1.50" }
    ],
    "feeAndContract": {
      "estimatedNetworkFee": { "amount": "0.00012", "tokenSymbol": "BNB", "valueUsd": "0.07" },
      "interactWith":        { "address": "0xfD36..." }
    },
    "warnings": []
  }
}

Field notes