@byreal-io/byreal-cli-realclaw 0.3.1 → 0.3.3

package/README.md

@@ -1,6 +1,6 @@
 # Byreal Agent Skills
 
-> **Note:** This is the **openclaw** internal branch. Write commands output unsigned base64 transactions by default and require `--wallet-address <address>` instead of local keypair setup.
+> **Note:** This is the **RealClaw** internal branch (`openclaw`). Write commands output unsigned base64 transactions by default and require `--wallet-address <address>` instead of local keypair setup. Package name: `@byreal-io/byreal-cli-realclaw`.
 
 Agent skills for [Byreal](https://byreal.io) — a concentrated liquidity (CLMM) DEX on Solana. Every command supports structured JSON output, and the built-in skill system lets AI agents discover and use all capabilities automatically.
 
@@ -15,6 +15,10 @@ npx skills add https://github.com/byreal-git/byreal-agent-skills/tree/openclaw
 Or install the CLI only:
 
 ```bash
+# If @byreal-io/byreal-cli (main branch) is already installed, uninstall first
+# to avoid bin name conflict (both packages use the `byreal-cli` binary name):
+npm uninstall -g @byreal-io/byreal-cli
+
 npm install -g @byreal-io/byreal-cli-realclaw
 ```
 
@@ -62,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      |
@@ -70,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.1" : void 0;
+    INJECTED_VERSION = true ? "0.3.3" : 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"
     };
@@ -82846,6 +82847,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 +82874,8 @@ var api = {
   getUnclaimedData,
   getEpochBonus,
   getProviderOverview,
-  encodeReward
+  encodeReward,
+  submitRewardOrder
 };
 
 // src/cli/commands/pools.ts
@@ -83555,6 +83570,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) {
@@ -84030,6 +84064,9 @@ Byreal DEX (Solana) all-in-one CLI: query pools/tokens/TVL, analyze pool APR & r
 # Check if already installed
 which byreal-cli && byreal-cli --version
 
+# If @byreal-io/byreal-cli (main branch) is installed, uninstall first (bin name conflict):
+npm uninstall -g @byreal-io/byreal-cli
+
 # Install
 npm install -g @byreal-io/byreal-cli-realclaw
 \`\`\`
@@ -84069,7 +84106,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 |
@@ -84351,12 +84388,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
@@ -84365,6 +84403,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).
 
@@ -84499,6 +84549,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.
 
@@ -84514,6 +84567,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.
@@ -84690,6 +84761,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
 
@@ -84942,11 +85050,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" },
@@ -85064,6 +85173,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",
@@ -85617,25 +85738,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,
@@ -87497,6 +87624,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());
@@ -87507,6 +87705,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.1",
+  "version": "0.3.3",
   "description": "AI-native CLI for Byreal CLMM DEX on Solana",
   "type": "module",
   "main": "dist/index.cjs",

package/skills/{byreal-cli → byreal-cli-realclaw}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: byreal-cli
-description: "Byreal DEX (Solana) all-in-one CLI: query pools/tokens/TVL, analyze pool APR & risk, open/close/claim CLMM positions, token swap, wallet & balance management. Use when user mentions Byreal, LP, liquidity, pools, DeFi positions, token swap, or Solana DEX operations."
+name: byreal-cli-realclaw
+description: "RealClaw edition of Byreal DEX CLI (Solana): query pools/tokens/TVL, analyze pool APR & risk, open/close/claim CLMM positions, token swap, wallet balance. Outputs unsigned base64 transactions for hosted wallet signing. Use when user mentions Byreal, LP, liquidity, pools, DeFi positions, token swap, or Solana DEX operations."
 metadata:
   openclaw:
     homepage: https://github.com/byreal-git/byreal-agent-skills
@@ -37,6 +37,10 @@ byreal-cli catalog show <capability-id>
 # Check if already installed
 which byreal-cli && byreal-cli --version
 
+# If @byreal-io/byreal-cli (main branch version) is already installed,
+# uninstall it first to avoid bin name conflict:
+npm uninstall -g @byreal-io/byreal-cli
+
 # Install
 npm install -g @byreal-io/byreal-cli-realclaw
 ```