@byreal-io/byreal-cli-realclaw 0.3.2 → 0.3.4

package/README.md

@@ -24,7 +24,7 @@ npm install -g @byreal-io/byreal-cli-realclaw
 
 ## Features
 
-- **Pools** — List, search, and inspect CLMM pools. View K-line charts, APR, TVL, volume, and run comprehensive pool analysis (risk, volatility, range recommendations).
+- **Pools** — List, search, and inspect CLMM pools. View K-line charts, Est. APR (fee + reward incentive breakdown), TVL, volume, and run comprehensive pool analysis (risk, volatility, range recommendations).
 - **Tokens** — List tokens, search by symbol/name, get real-time prices.
 - **Swap** — Preview and execute token swaps with slippage control and price impact estimation.
 - **Positions** — Open, close, and manage CLMM positions. Claim fees and rewards. Analyze position performance. Copy top farmers' positions with one command.
@@ -66,7 +66,7 @@ All commands support `-o json` for structured output.
 | `pools analyze`           | Comprehensive pool analysis (APR, risk, range) |
 | `tokens list`             | List available tokens                          |
 | `swap execute`            | Preview or execute a token swap                |
-| `positions list`          | List your CLMM positions                       |
+| `positions list`          | List positions (own wallet or any via --user)   |
 | `positions open`          | Open a new CLMM position                       |
 | `positions increase`      | Add liquidity to an existing position           |
 | `positions decrease`      | Partially remove liquidity from a position      |
@@ -74,6 +74,7 @@ All commands support `-o json` for structured output.
 | `positions claim`           | Claim trading fees                              |
 | `positions claim-rewards`   | Claim incentive rewards from positions           |
 | `positions claim-bonus`     | Claim CopyFarmer bonus rewards                  |
+| `positions submit-rewards`  | Submit signed reward/bonus transactions to backend |
 | `positions analyze`       | Analyze an existing position                   |
 | `positions top-positions` | View top positions in a pool                   |
 | `positions copy`          | Copy a farmer's position                       |

package/dist/index.cjs

@@ -3033,7 +3033,7 @@ var INJECTED_VERSION, VERSION, CLI_NAME, NPM_PACKAGE, API_BASE_URL, API_ENDPOINT
 var init_constants = __esm({
   "src/core/constants.ts"() {
     "use strict";
-    INJECTED_VERSION = true ? "0.3.2" : void 0;
+    INJECTED_VERSION = true ? "0.3.4" : void 0;
     VERSION = INJECTED_VERSION ?? process.env.npm_package_version ?? "0.0.0";
     CLI_NAME = "byreal-cli";
     NPM_PACKAGE = "@byreal-io/byreal-cli-realclaw";
@@ -3061,6 +3061,7 @@ var init_constants = __esm({
       // Reward / Bonus claim endpoints
       UNCLAIMED_DATA: "/byreal/api/dex/v2/position/unclaimed-data",
       REWARD_ENCODE: "/byreal/api/dex/v2/incentive/encode-v2",
+      REWARD_ORDER: "/byreal/api/dex/v2/incentive/order-v2",
       // Fee endpoints
       AUTO_FEE: "/byreal/api/dex/v2/main/auto-fee"
     };
@@ -82379,12 +82380,48 @@ var apiClient = {
 // src/api/endpoints.ts
 init_constants();
 init_errors();
+function transformReward(r) {
+  const isNewFormat = r.token !== void 0;
+  const mintInfo = isNewFormat ? r.token?.mintInfo : r.mint;
+  const mint = mintInfo?.address || "";
+  const symbol = mintInfo?.symbol || "";
+  const priceUsd = isNewFormat ? parseFloat(r.token?.price || "0") : 0;
+  const apr = parseFloat(r.apr || "0") * 100;
+  const rawEndTime = isNewFormat ? r.endTimestamp || 0 : r.rewardEndTime || 0;
+  const endTime = rawEndTime > 1e12 ? Math.floor(rawEndTime / 1e3) : rawEndTime;
+  const rawOpenTime = r.rewardOpenTime || 0;
+  const openTime = rawOpenTime > 1e12 ? Math.floor(rawOpenTime / 1e3) : rawOpenTime;
+  let dailyAmount = r.dailyAmountDisplay || r.dailyMaxAmount || "";
+  if (!dailyAmount && r.rewardPerSecond) {
+    const rps = parseFloat(r.rewardPerSecond);
+    if (rps > 0) {
+      dailyAmount = (rps * 86400).toString();
+    }
+  }
+  const dailyAmountNum = parseFloat(dailyAmount || "0");
+  const dailyAmountUsd = dailyAmountNum * priceUsd;
+  return {
+    mint,
+    symbol,
+    rewardPerSecond: r.rewardPerSecond || "0",
+    openTime,
+    endTime,
+    apr,
+    daily_amount: dailyAmount,
+    daily_amount_usd: dailyAmountUsd,
+    price_usd: priceUsd
+  };
+}
 function transformPool(apiPool) {
   const mintA = apiPool.mintA?.mintInfo || {};
   const mintB = apiPool.mintB?.mintInfo || {};
   const baseMintPrice = parseFloat(apiPool.baseMint?.price || apiPool.mintA?.price || "0");
   const quoteMintPrice = parseFloat(apiPool.quoteMint?.price || apiPool.mintB?.price || "0");
   const poolPrice = quoteMintPrice > 0 ? baseMintPrice / quoteMintPrice : 0;
+  const now = Math.floor(Date.now() / 1e3);
+  const activeRewards = (apiPool.rewards || []).map(transformReward).filter((r) => r.endTime > now || r.endTime === 0);
+  const feeApr = parseFloat(apiPool.feeApr24h || "0") * 100;
+  const rewardApr = activeRewards.reduce((sum3, r) => sum3 + r.apr, 0);
   return {
     id: apiPool.poolAddress,
     pair: `${mintA.symbol || "Unknown"}/${mintB.symbol || "Unknown"}`,
@@ -82410,13 +82447,15 @@ function transformPool(apiPool) {
     fee_rate_bps: parseInt(apiPool.feeRate?.fixFeeRate || "0", 10) / 100,
     // fixFeeRate is in 1/100 bps
     fee_24h_usd: parseFloat(apiPool.feeUsd1d || apiPool.feeUsd24h || "0"),
-    apr: parseFloat(apiPool.feeApr24h || "0") * 100,
-    // 转换为百分比
+    apr: feeApr,
+    reward_apr: rewardApr,
+    total_apr: feeApr + rewardApr,
     current_price: poolPrice,
     created_at: apiPool.openTime ? new Date(apiPool.openTime).toISOString() : "",
     price_change_1h: apiPool.priceChange1h ? parseFloat(apiPool.priceChange1h) * 100 : void 0,
     price_change_24h: apiPool.priceChange1d ? parseFloat(apiPool.priceChange1d) * 100 : void 0,
-    price_change_7d: apiPool.priceChange7d ? parseFloat(apiPool.priceChange7d) * 100 : void 0
+    price_change_7d: apiPool.priceChange7d ? parseFloat(apiPool.priceChange7d) * 100 : void 0,
+    rewards: activeRewards.length > 0 ? activeRewards : void 0
   };
 }
 function transformToken(apiToken) {
@@ -82504,13 +82543,6 @@ async function getPoolInfo(poolId) {
     };
   }
   const pool = transformPool(poolData);
-  const rewards = (poolData.rewards || []).map((r) => ({
-    mint: r.mint?.address || "",
-    symbol: r.mint?.symbol || "",
-    rewardPerSecond: r.rewardPerSecond || "0",
-    openTime: r.rewardOpenTime || 0,
-    endTime: r.rewardEndTime || 0
-  }));
   return {
     ok: true,
     value: {
@@ -82523,8 +82555,7 @@ async function getPoolInfo(poolId) {
       price_change_24h: parseFloat(poolData.priceChange1d || "0") * 100,
       price_change_7d: parseFloat(poolData.priceChange7d || "0") * 100,
       fee_7d_usd: parseFloat(poolData.feeUsd7d || "0"),
-      category: poolData.category,
-      rewards: rewards.length > 0 ? rewards : void 0
+      category: poolData.category
     }
   };
 }
@@ -82846,6 +82877,19 @@ async function encodeReward(params) {
   }
   return { ok: true, value: data };
 }
+async function submitRewardOrder(params) {
+  const result = await apiClient.post(API_ENDPOINTS.REWARD_ORDER, {
+    orderCode: params.orderCode,
+    walletAddress: params.walletAddress,
+    signedTxPayload: params.signedTxPayload
+  });
+  if (!result.ok) return result;
+  const data = result.value.result?.data;
+  if (!data) {
+    return { ok: true, value: { orderCode: "", txList: [], claimTokenList: [] } };
+  }
+  return { ok: true, value: data };
+}
 var api = {
   listPools,
   getPoolInfo,
@@ -82860,7 +82904,8 @@ var api = {
   getUnclaimedData,
   getEpochBonus,
   getProviderOverview,
-  encodeReward
+  encodeReward,
+  submitRewardOrder
 };
 
 // src/cli/commands/pools.ts
@@ -82953,20 +82998,26 @@ function formatApr(value) {
   return color(`${value.toFixed(2)}%`);
 }
 function outputPoolsTable(pools, total) {
-  const table = createTable(["Pair", "Pool ID", "TVL", "Volume 24h", "APR", "Fee Rate"]);
+  const table = createTable(["Pair", "Pool ID", "TVL", "Volume 24h", "Est. APR", "Fee Rate"]);
   for (const pool of pools) {
+    const hasRewards = pool.reward_apr > 0;
+    const aprDisplay = formatApr(pool.total_apr) + (hasRewards ? source_default.magenta(" (+R)") : "");
     table.push([
       source_default.white.bold(pool.pair),
       source_default.gray(pool.id),
       formatUsd(pool.tvl_usd),
       formatUsd(pool.volume_24h_usd),
-      formatApr(pool.apr),
+      aprDisplay,
       `${(pool.fee_rate_bps / 100).toFixed(2)}%`
     ]);
   }
   console.log(table.toString());
   console.log(source_default.gray(`
 Showing ${pools.length} of ${total} pools`));
+  const hasAnyRewards = pools.some((p) => p.reward_apr > 0);
+  if (hasAnyRewards) {
+    console.log(source_default.magenta("(+R)") + source_default.gray(" = includes reward incentives"));
+  }
 }
 function outputPoolDetail(pool) {
   console.log(source_default.cyan.bold(`
@@ -82980,9 +83031,26 @@ ${pool.pair}`));
     ["Volume (7d)", formatUsd(pool.volume_7d_usd)],
     ["Fees (24h)", formatUsd(pool.fee_24h_usd)],
     ["Fee Rate", `${(pool.fee_rate_bps / 100).toFixed(2)}%`],
-    ["APR", formatApr(pool.apr)]
+    ["Fee APR", formatApr(pool.apr)],
+    ["Reward APR", pool.reward_apr > 0 ? formatApr(pool.reward_apr) : source_default.gray("None")],
+    ["Total APR", source_default.bold(formatApr(pool.total_apr))]
   );
   console.log(table.toString());
+  if (pool.rewards && pool.rewards.length > 0) {
+    console.log(source_default.cyan("\nActive Rewards:"));
+    const rewardsTable = createTable(["Token", "APR", "Daily Amount", "Daily USD", "Ends"]);
+    for (const r of pool.rewards) {
+      const endDate = r.endTime > 0 ? new Date(r.endTime * 1e3).toISOString().slice(0, 10) : "Ongoing";
+      rewardsTable.push([
+        source_default.white.bold(r.symbol || r.mint),
+        formatApr(r.apr),
+        r.daily_amount ? parseFloat(r.daily_amount).toLocaleString() : "-",
+        r.daily_amount_usd > 0 ? formatUsd(r.daily_amount_usd) : "-",
+        source_default.gray(endDate)
+      ]);
+    }
+    console.log(rewardsTable.toString());
+  }
   console.log(source_default.cyan("\nPrices:"));
   const priceTable = createTable(["Token", "Price (USD)", "Mint"]);
   priceTable.push(
@@ -83412,6 +83480,8 @@ Pool Analysis: ${data.pool.pair}`));
     ["Fees (24h)", `$${data.metrics.fee24h}`],
     ["Fees (7d)", `$${data.metrics.fee7d}`],
     ["Fee APR (24h)", data.metrics.feeApr24h],
+    ["Reward APR", data.metrics.rewardApr || source_default.gray("None")],
+    ["Total APR", source_default.bold(data.metrics.totalApr)],
     ["Volume/TVL", data.metrics.volumeToTvl]
   );
   console.log(metricsTable.toString());
@@ -83424,9 +83494,15 @@ Pool Analysis: ${data.pool.pair}`));
   console.log(volTable.toString());
   if (data.rewards && data.rewards.length > 0) {
     console.log(source_default.cyan.bold("\nRewards"));
-    const rewardsTable = createTable(["Token", "End Date"]);
+    const rewardsTable = createTable(["Token", "APR", "Daily Amount", "Daily USD", "End Date"]);
     for (const r of data.rewards) {
-      rewardsTable.push([r.token, r.endTime]);
+      rewardsTable.push([
+        r.token,
+        r.apr || "-",
+        r.dailyAmount || "-",
+        r.dailyAmountUsd || "-",
+        r.endTime
+      ]);
     }
     console.log(rewardsTable.toString());
   }
@@ -83555,6 +83631,25 @@ function outputError(error, format) {
     outputErrorTable(error);
   }
 }
+function outputRewardOrderResult(result) {
+  console.log(source_default.green.bold("\nRewards Claimed\n"));
+  if (result.claimTokenList.length > 0) {
+    console.log(source_default.white.bold("  Claimed Tokens:"));
+    for (const token of result.claimTokenList) {
+      console.log(source_default.gray(`    ${token.tokenAmount} ${token.tokenSymbol} (${token.tokenAddress})`));
+    }
+    console.log();
+  }
+  if (result.txList.length > 0) {
+    console.log(source_default.white.bold("  Transactions:"));
+    for (const tx of result.txList) {
+      const statusLabel = tx.status === 1 ? source_default.green("Success") : tx.status === 2 ? source_default.red("Failed") : source_default.yellow("Sent");
+      console.log(source_default.gray(`    ${tx.txSignature} ${statusLabel}`));
+      console.log(source_default.blue(`    https://solscan.io/tx/${tx.txSignature}`));
+    }
+    console.log();
+  }
+}
 
 // src/cli/commands/pools.ts
 async function listPools2(options, globalOptions) {
@@ -83759,14 +83854,15 @@ function createPoolsAnalyzeCommand() {
       const dayPriceLow = pool.price_range_24h.low;
       const dayPriceHigh = pool.price_range_24h.high;
       const dayPriceRangePercent = currentPrice > 0 ? (dayPriceHigh - dayPriceLow) / currentPrice * 100 : 0;
-      const now = Math.floor(Date.now() / 1e3);
-      const rewardsOutput = (pool.rewards || []).filter((r) => r.endTime > now).map((r) => {
-        return {
-          token: r.symbol || r.mint,
-          rewardPerSecond: r.rewardPerSecond,
-          endTime: new Date(r.endTime * 1e3).toISOString().slice(0, 10)
-        };
-      });
+      const activeRewards = pool.rewards || [];
+      const totalRewardApr = pool.reward_apr;
+      const rewardsOutput = activeRewards.map((r) => ({
+        token: r.symbol || r.mint,
+        apr: `${r.apr.toFixed(2)}%`,
+        dailyAmount: r.daily_amount ? parseFloat(r.daily_amount).toLocaleString() : "-",
+        dailyAmountUsd: r.daily_amount_usd > 0 ? `$${r.daily_amount_usd.toFixed(2)}` : "-",
+        endTime: r.endTime > 0 ? new Date(r.endTime * 1e3).toISOString().slice(0, 10) : "Ongoing"
+      }));
       const rangeAprs = calculateRangeAprs2({
         percentRanges: rangePercents,
         volume24h: pool.volume_24h_usd,
@@ -83816,8 +83912,7 @@ function createPoolsAnalyzeCommand() {
           priceLower: alignedPriceLower.toFixed(8).replace(/0+$/, "").replace(/\.$/, ""),
           priceUpper: alignedPriceUpper.toFixed(8).replace(/0+$/, "").replace(/\.$/, ""),
           estimatedFeeApr: `${feeApr.toFixed(1)}%`,
-          estimatedTotalApr: `${feeApr.toFixed(1)}%`,
-          // same as feeApr if no rewards calculated
+          estimatedTotalApr: `${(feeApr + totalRewardApr).toFixed(1)}%`,
           inRangeLikelihood,
           rebalanceFrequency
         };
@@ -83826,7 +83921,7 @@ function createPoolsAnalyzeCommand() {
       const volatilityRisk = assessVolatilityRisk(dayPriceRangePercent);
       const riskSummary = buildRiskSummary(pool, dayPriceRangePercent);
       const projectionRange = rangePercents.includes(10) ? 10 : rangePercents[Math.floor(rangePercents.length / 2)];
-      const projectionApr = rangeAprs[projectionRange] || 0;
+      const projectionApr = (rangeAprs[projectionRange] || 0) + totalRewardApr;
       const dailyFee = projectionApr / 100 / 365 * investAmount;
       const weeklyFee = dailyFee * 7;
       const monthlyFee = dailyFee * 30;
@@ -83847,6 +83942,8 @@ function createPoolsAnalyzeCommand() {
           fee24h: fee24h.toFixed(2),
           fee7d: fee7d.toFixed(2),
           feeApr24h: `${feeApr24h.toFixed(2)}%`,
+          rewardApr: totalRewardApr > 0 ? `${totalRewardApr.toFixed(2)}%` : void 0,
+          totalApr: `${(feeApr24h + totalRewardApr).toFixed(2)}%`,
           volumeToTvl: volumeToTvl.toFixed(2)
         },
         volatility: {
@@ -84072,7 +84169,7 @@ byreal-cli catalog show dex.pool.list
 | dex.token.list | Query tokens with search |
 | dex.overview.global | Global statistics |
 | dex.swap.execute | Preview or execute a token swap |
-| dex.position.list | List user's CLMM positions |
+| dex.position.list | List positions for your wallet or any wallet via --user |
 | dex.position.analyze | Analyze existing position |
 | dex.position.open | Open a new CLMM position |
 | dex.position.increase | Add liquidity to an existing position |
@@ -84187,7 +84284,7 @@ Byreal CLI provides on-chain data only. For complete analysis, **you (the AI age
 ## Commands
 
 ### pools list
-Query available liquidity pools with sorting and filtering.
+Query available liquidity pools with Est. APR (fee + reward incentive breakdown), sorting and filtering.
 
 \`\`\`bash
 byreal-cli pools list [options]
@@ -84214,7 +84311,7 @@ byreal-cli pools list --category 1 -o json
 \`\`\`
 
 ### pools info
-Get detailed information about a specific pool.
+Get detailed information about a specific pool, including Fee APR, Reward APR, Total APR breakdown and active reward incentives (token, APR, daily amount, daily USD, end date).
 
 \`\`\`bash
 byreal-cli pools info <pool-id> -o json
@@ -84354,12 +84451,13 @@ byreal-cli swap execute --input-mint So11111111111111111111111111111111111111112
 \`\`\`
 
 ### positions list
-List user's CLMM positions.
+List CLMM positions for your wallet or any wallet address. Use \`--user\` to query another wallet's positions (read-only, no \`--wallet-address\` needed).
 
 \`\`\`bash
 byreal-cli positions list [options]
 
 Options:
+  --user <address>       Query positions for a specific wallet address (read-only)
   --page <n>             Page number (default: 1)
   --page-size <n>        Page size (default: 20)
   --sort-field <field>   Sort field
@@ -84368,6 +84466,18 @@ Options:
   --status <status>      Filter by status: 0=closed, 1=active
 \`\`\`
 
+Examples:
+\`\`\`bash
+# List your own positions
+byreal-cli positions list --wallet-address <your-addr> -o json
+
+# Query another user's positions (for LP copy trading research)
+byreal-cli positions list --user <target-wallet> -o json
+
+# Query another user's positions in a specific pool
+byreal-cli positions list --user <target-wallet> --pool <pool-address> -o json
+\`\`\`
+
 ### positions open
 Open a new CLMM position. Supports two modes: specify token amount (--amount) or USD investment (--amount-usd).
 
@@ -84502,6 +84612,9 @@ Options:
 - **Incentive rewards** \u2192 \`positions claim-rewards\` (this command)
 - **Copy bonus** \u2192 \`positions claim-bonus\` (see below)
 
+**IMPORTANT \u2014 claim-rewards is a multi-step flow:**
+The output includes \`orderCode\` and per-transaction \`txCode\`. After the wallet signs each transaction, you MUST call \`positions submit-rewards\` to send the signed transactions back to the backend for broadcasting. See "Workflow: Claim Rewards / Bonus" below.
+
 ### positions claim-bonus
 Claim CopyFarmer bonus rewards earned from copying other users' positions. Bonuses accrue in epochs and become claimable in time windows.
 
@@ -84517,6 +84630,24 @@ Options:
 - **Pending**: Settlement period, not yet claimable
 - **Claimable**: Ready to claim within the time window
 
+**IMPORTANT \u2014 claim-bonus is a multi-step flow** (same as claim-rewards): After signing, call \`positions submit-rewards\` to complete the claim.
+
+### positions submit-rewards
+Submit signed reward/bonus claim transactions to the backend for on-chain broadcasting. This is the final step after \`claim-rewards\` or \`claim-bonus\` generates unsigned transactions and the wallet signs them.
+
+\`\`\`bash
+byreal-cli positions submit-rewards [options]
+
+Options:
+  --order-code <code>         Order code from claim-rewards or claim-bonus output (required)
+  --signed-payloads <json>    JSON array of signed transactions (required)
+\`\`\`
+
+The \`--signed-payloads\` format:
+\`\`\`json
+[{"txCode":"<from output>","poolAddress":"<from output>","signedTx":"<base64 signed tx>"}]
+\`\`\`
+
 ### positions top-positions
 Query top positions in a pool. Use this to discover high-performing positions that can be copied.
 Each position includes an \`inRange\` field (true/false) indicating whether the pool's current tick is within the position's tick range. Out-of-range positions earn zero trading fees.
@@ -84561,7 +84692,7 @@ Response includes:
 - **pool**: Basic info (address, pair, category, currentPrice, feeRate, tickSpacing)
 - **metrics**: TVL, volume (24h/7d), fees (24h/7d), feeApr24h, volumeToTvl ratio
 - **volatility**: 24h price range (low/high) and dayPriceRangePercent
-- **rewards**: Active reward programs (token, endTime)
+- **rewards**: Active reward programs (token, APR, daily amount, daily USD value, end date)
 - **rangeAnalysis**: For each range %, shows priceLower/Upper, estimated fee APR, in-range likelihood, rebalance frequency
 - **riskFactors**: TVL risk, volatility risk, and human-readable summary
 - **wallet**: Wallet address, balanceUsd, and optional low-balance warning (included when --wallet-address is provided)
@@ -84693,6 +84824,43 @@ When user asks vague questions like "\u6709\u4EC0\u4E48\u4ED3\u4F4D\u53EF\u4EE5
 - Always explain WHY you recommend a position (e.g., "\u9AD8\u624B\u7EED\u8D39\u6536\u76CA + \u4F4E\u65E0\u5E38\u635F\u5931 + \u5728\u533A\u95F4\u5185")
 - If user's balance is low (<$20), suggest starting with a single position to minimize gas cost
 - If all positions in a pool are out-of-range, skip that pool and explain why
+- To inspect a specific LP's full portfolio: \`byreal-cli positions list --user <wallet-address> -o json\`
+
+## Workflow: Claim Rewards / Bonus (Multi-Step)
+
+Claiming incentive rewards (\`claim-rewards\`) and CopyFarmer bonus (\`claim-bonus\`) requires a **3-step flow** because the backend co-signs and broadcasts these transactions:
+
+**Step 1 \u2014 Preview** (optional but recommended):
+\`\`\`bash
+byreal-cli positions claim-rewards --dry-run --wallet-address <addr> -o json
+\`\`\`
+
+**Step 2 \u2014 Generate unsigned transactions**:
+\`\`\`bash
+byreal-cli positions claim-rewards --wallet-address <addr> -o json
+\`\`\`
+Output:
+\`\`\`json
+{
+  "orderCode": "ORD_xxx",
+  "unsignedTransactions": [
+    { "poolAddress": "...", "txPayload": "<base64>", "txCode": "TX_xxx", "tokens": [...] }
+  ]
+}
+\`\`\`
+
+**Step 3 \u2014 Sign each \`txPayload\` with the user's wallet**, then submit:
+\`\`\`bash
+byreal-cli positions submit-rewards \\
+  --order-code "ORD_xxx" \\
+  --signed-payloads '[{"txCode":"TX_xxx","poolAddress":"...","signedTx":"<base64 signed>"}]' \\
+  --wallet-address <addr> -o json
+\`\`\`
+The backend broadcasts the signed transactions on-chain and returns tx signatures + status.
+
+**For claim-bonus**: Same flow \u2014 replace \`claim-rewards\` with \`claim-bonus\` in Step 1-2; Step 3 is identical (\`submit-rewards\`).
+
+**Critical**: Do NOT skip Step 3. Without \`submit-rewards\`, the signed transactions are never sent to the blockchain. The \`orderCode\` ties the encode and submit steps together \u2014 always pass the same \`orderCode\` from Step 2 into Step 3.
 
 ## Output Format
 
@@ -84809,7 +84977,7 @@ var CAPABILITIES = [
   {
     id: "dex.pool.list",
     name: "List Pools",
-    description: "Query available liquidity pools with sorting and filtering",
+    description: "Query available liquidity pools with Est. APR (fee + reward incentive), sorting and filtering",
     category: "query",
     auth_required: false,
     command: "byreal-cli pools list",
@@ -84850,7 +85018,7 @@ var CAPABILITIES = [
   {
     id: "dex.pool.analyze",
     name: "Pool Analysis",
-    description: "Comprehensive pool analysis: metrics, volatility, multi-range APR comparison, risk assessment, and investment projection",
+    description: "Comprehensive pool analysis: metrics (fee APR, reward APR, total APR), volatility, multi-range APR comparison, risk assessment, and investment projection",
     category: "analyze",
     auth_required: false,
     command: "byreal-cli pools analyze <pool-id>",
@@ -84945,11 +85113,12 @@ var CAPABILITIES = [
   {
     id: "dex.position.list",
     name: "List Positions",
-    description: "List user CLMM positions with filtering and sorting. Requires --wallet-address global option.",
+    description: "List CLMM positions for your wallet or any wallet address. Use --user to query another wallet (read-only, no --wallet-address needed).",
     category: "query",
-    auth_required: true,
-    command: "byreal-cli positions list --wallet-address <address>",
+    auth_required: false,
+    command: "byreal-cli positions list",
     params: [
+      { name: "user", type: "string", required: false, description: "Query positions for a specific wallet address (read-only)" },
       { name: "page", type: "integer", required: false, description: "Page number", default: "1" },
       { name: "page-size", type: "integer", required: false, description: "Page size", default: "20" },
       { name: "sort-field", type: "string", required: false, description: "Sort field" },
@@ -85067,6 +85236,18 @@ var CAPABILITIES = [
       { name: "dry-run", type: "boolean", required: false, description: "Preview claimable bonus without claiming" }
     ]
   },
+  {
+    id: "dex.position.submitRewards",
+    name: "Submit Signed Rewards",
+    description: "Submit signed reward/bonus claim transactions to backend for broadcasting. Used after claim-rewards or claim-bonus generates unsigned transactions and the external wallet signs them. Requires --wallet-address global option.",
+    category: "execute",
+    auth_required: true,
+    command: "byreal-cli positions submit-rewards --wallet-address <address>",
+    params: [
+      { name: "order-code", type: "string", required: true, description: "Order code from claim-rewards or claim-bonus output" },
+      { name: "signed-payloads", type: "string", required: true, description: 'JSON array of signed transactions: [{"txCode":"...","poolAddress":"...","signedTx":"<base64>"}]' }
+    ]
+  },
   {
     id: "dex.position.topPositions",
     name: "Top Positions",
@@ -85620,25 +85801,31 @@ function serializeTransaction(tx) {
 // src/cli/commands/positions.ts
 init_errors();
 function createPositionsListCommand() {
-  return new Command("list").description("List your positions").option("--page <n>", "Page number", "1").option("--page-size <n>", "Page size", "20").option("--sort-field <field>", "Sort field").option("--sort-type <type>", "Sort direction: asc or desc").option("--pool <address>", "Filter by pool address").option(
+  return new Command("list").description("List positions for your wallet or any wallet address").option("--user <address>", "Query positions for a specific wallet address (read-only, no --wallet-address needed)").option("--page <n>", "Page number", "1").option("--page-size <n>", "Page size", "20").option("--sort-field <field>", "Sort field").option("--sort-type <type>", "Sort direction: asc or desc").option("--pool <address>", "Filter by pool address").option(
     "--status <status>",
     "Filter by status: 0=active, 1=closed (default: 0)"
   ).action(async (options, cmdObj) => {
     const globalOptions = cmdObj.optsWithGlobals();
     const format = globalOptions.output;
     const startTime = Date.now();
-    const walletAddress = globalOptions.walletAddress;
-    if (!walletAddress) {
-      const err2 = missingWalletAddressError();
+    const userAddress = options.user || globalOptions.walletAddress;
+    if (!userAddress) {
+      const errMsg = "Provide --user <address> or global --wallet-address to specify which wallet to query.";
       if (format === "json") {
-        outputErrorJson(err2.toJSON());
+        outputErrorJson({ code: "MISSING_ADDRESS", type: "VALIDATION", message: errMsg, retryable: false });
       } else {
-        outputErrorTable(err2.toJSON());
+        console.error(source_default.red(`
+Error: ${errMsg}`));
       }
       process.exit(1);
     }
+    if (options.user && format !== "json") {
+      console.log(source_default.gray(`
+  Positions for: ${options.user}
+`));
+    }
     const result = await api.listPositions({
-      userAddress: walletAddress,
+      userAddress,
       page: parseInt(options.page, 10),
       pageSize: parseInt(options.pageSize, 10),
       sortField: options.sortField,
@@ -87500,6 +87687,77 @@ SDK Error: ${message}`));
     }
   });
 }
+function createSubmitRewardsCommand() {
+  return new Command("submit-rewards").description(
+    "Submit signed reward/bonus transactions to backend for broadcasting"
+  ).requiredOption(
+    "--order-code <code>",
+    "Order code from claim-rewards or claim-bonus output"
+  ).requiredOption(
+    "--signed-payloads <json>",
+    'JSON array: [{"txCode":"...","poolAddress":"...","signedTx":"<base64>"}]'
+  ).action(async (options, cmdObj) => {
+    const globalOptions = cmdObj.optsWithGlobals();
+    const format = globalOptions.output;
+    const startTime = Date.now();
+    const walletAddress = globalOptions.walletAddress;
+    if (!walletAddress) {
+      const err2 = missingWalletAddressError();
+      if (format === "json") {
+        outputErrorJson(err2.toJSON());
+      } else {
+        outputErrorTable(err2.toJSON());
+      }
+      process.exit(1);
+    }
+    let signedPayloads;
+    try {
+      signedPayloads = JSON.parse(options.signedPayloads);
+      if (!Array.isArray(signedPayloads) || signedPayloads.length === 0) {
+        throw new Error("must be a non-empty array");
+      }
+      for (const p of signedPayloads) {
+        if (!p.txCode || !p.poolAddress || !p.signedTx) {
+          throw new Error(
+            "each entry must have txCode, poolAddress, signedTx"
+          );
+        }
+      }
+    } catch (e) {
+      const errMsg = `Invalid --signed-payloads: ${e.message}`;
+      if (format === "json") {
+        outputErrorJson({
+          code: "INVALID_PARAMETER",
+          type: "VALIDATION",
+          message: errMsg,
+          retryable: false
+        });
+      } else {
+        console.error(source_default.red(`
+Error: ${errMsg}`));
+      }
+      process.exit(1);
+    }
+    const orderResult = await api.submitRewardOrder({
+      orderCode: options.orderCode,
+      walletAddress,
+      signedTxPayload: signedPayloads
+    });
+    if (!orderResult.ok) {
+      if (format === "json") {
+        outputErrorJson(orderResult.error);
+      } else {
+        outputErrorTable(orderResult.error);
+      }
+      process.exit(1);
+    }
+    if (format === "json") {
+      outputJson(orderResult.value, startTime);
+    } else {
+      outputRewardOrderResult(orderResult.value);
+    }
+  });
+}
 function createPositionsCommand() {
   const cmd = new Command("positions").description("Manage CLMM positions");
   cmd.addCommand(createPositionsListCommand());
@@ -87510,6 +87768,7 @@ function createPositionsCommand() {
   cmd.addCommand(createPositionsClaimCommand());
   cmd.addCommand(createPositionsClaimRewardsCommand());
   cmd.addCommand(createPositionsClaimBonusCommand());
+  cmd.addCommand(createSubmitRewardsCommand());
   cmd.addCommand(createPositionsAnalyzeCommand());
   cmd.addCommand(createTopPositionsCommand());
   cmd.addCommand(createCopyPositionCommand());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byreal-io/byreal-cli-realclaw",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "AI-native CLI for Byreal CLMM DEX on Solana",
   "type": "module",
   "main": "dist/index.cjs",