traderclaw-cli 1.0.61 → 1.0.63

package/bin/installer-step-engine.mjs

@@ -941,6 +941,11 @@ function configureGatewayScheduling(modeConfig, configPath = CONFIG_FILE) {
     config.channels.defaults.heartbeat.showOk = true;
   }
 
+  if (!config.agents.defaults || typeof config.agents.defaults !== "object") {
+    config.agents.defaults = {};
+  }
+  config.agents.defaults.heartbeat = { ...defaultHeartbeat };
+
   ensureAgentsDefaultsSchemaCompat(config);
   mkdirSync(CONFIG_DIR, { recursive: true });
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
@@ -1498,6 +1503,7 @@ export class InstallerStepEngine {
       xAccessTokenCtoSecret: typeof options.xAccessTokenCtoSecret === "string" ? options.xAccessTokenCtoSecret : "",
       xAccessTokenIntern: typeof options.xAccessTokenIntern === "string" ? options.xAccessTokenIntern : "",
       xAccessTokenInternSecret: typeof options.xAccessTokenInternSecret === "string" ? options.xAccessTokenInternSecret : "",
+      referralCode: typeof options.referralCode === "string" ? options.referralCode.trim() : "",
     };
     this.hooks = {
       onStepEvent: typeof hooks.onStepEvent === "function" ? hooks.onStepEvent : () => {},
@@ -1783,6 +1789,11 @@ export class InstallerStepEngine {
       args.push("--gateway-base-url", gatewayBaseUrl);
     }
 
+    const ref = String(this.options.referralCode || "").trim();
+    if (ref) {
+      args.push("--referral-code", ref);
+    }
+
     const command = [this.modeConfig.cliName, ...args].join(" ");
     const docs =
       "https://docs.traderclaw.ai/docs/installation#troubleshooting-session-expired-auth-errors-or-the-agent-logged-out";

package/bin/openclaw-trader.mjs

@@ -520,15 +520,22 @@ function signChallengeLocally(challengeText, privateKeyBase58) {
   return b58Encode(new Uint8Array(sig));
 }
 
-async function doSignup(orchestratorUrl, externalUserId) {
+async function doSignup(orchestratorUrl, externalUserId, referralCode = "") {
   printInfo(`  Signing up as: ${externalUserId}`);
+  const body = { externalUserId };
+  const ref = String(referralCode || "").trim();
+  if (ref) body.referralCode = ref;
   const res = await httpRequest(`${orchestratorUrl}/api/auth/signup`, {
     method: "POST",
-    body: { externalUserId },
+    body,
   });
 
   if (!res.ok) {
-    throw new Error(`Signup failed (HTTP ${res.status}): ${JSON.stringify(res.data)}`);
+    const payload = res.data && typeof res.data === "object" ? res.data : {};
+    const apiMsg = typeof payload.message === "string" ? payload.message : JSON.stringify(res.data);
+    const err = new Error(`Signup failed (HTTP ${res.status}): ${apiMsg}`);
+    if (typeof payload.code === "string") err.code = payload.code;
+    throw err;
   }
 
   return res.data;
@@ -700,6 +707,8 @@ async function cmdSetup(args) {
   let noEnsureGatewayPersistent = false;
   let signupRecoverySecret = undefined;
   let forwardTelegramRecipientArg = "";
+  let referralCodeArg = "";
+  let referralInvalidRetries = 0;
 
   for (let i = 0; i < args.length; i++) {
     if ((args[i] === "--api-key" || args[i] === "-k") && args[i + 1]) {
@@ -746,6 +755,9 @@ async function cmdSetup(args) {
     ) {
       forwardTelegramRecipientArg = args[++i];
     }
+    if ((args[i] === "--referral-code" || args[i] === "-r") && args[i + 1]) {
+      referralCodeArg = args[++i];
+    }
   }
   const runtimeWalletPrivateKey = getRuntimeWalletPrivateKey(walletPrivateKey);
 
@@ -763,6 +775,16 @@ async function cmdSetup(args) {
     }
   }
 
+  if (doSignupFlow && !referralCodeArg) {
+    printInfo(
+      "\n  Optional: enter a referral code for bonus access time (24h extra when valid). Press Enter to skip.\n",
+    );
+    printInfo(
+      "  Benefits: extra trial time now; referring others later earns +8h per user who completes at least one trade with the agent.\n",
+    );
+    referralCodeArg = await prompt("Referral code (optional)", "");
+  }
+
   if (doSignupFlow) {
     print("\n  Signing up for a new account...\n");
     if (!externalUserId) {
@@ -771,7 +793,7 @@ async function cmdSetup(args) {
 
     for (let signupAttempt = 0; ; signupAttempt++) {
       try {
-        const signupResult = await doSignup(orchestratorUrl, externalUserId);
+        const signupResult = await doSignup(orchestratorUrl, externalUserId, referralCodeArg);
         apiKey = signupResult.apiKey;
         if (signupResult.recoverySecret) {
           signupRecoverySecret = signupResult.recoverySecret;
@@ -783,6 +805,22 @@ async function cmdSetup(args) {
         break;
       } catch (err) {
         const msg = err.message || String(err);
+        const apiCode = err.code;
+        const referralRejected =
+          apiCode === "REFERRAL_CODE_INVALID" ||
+          msg.includes("REFERRAL_CODE_INVALID") ||
+          msg.includes("Unknown referral code");
+        if (referralRejected) {
+          referralInvalidRetries += 1;
+          if (referralInvalidRetries > 30) {
+            printError("Too many invalid referral attempts. Aborting.");
+            process.exit(1);
+          }
+          printWarn("  That referral code was not accepted (unknown or invalid).");
+          printInfo("  Leave it blank or enter a different code, then try again.");
+          referralCodeArg = await prompt("Referral code (optional, leave empty to skip)", "");
+          continue;
+        }
         if (msg.includes("SIGNUP_ALREADY_COMPLETED") || msg.includes("409")) {
           printWarn(`  User "${externalUserId}" is already registered.`);
           if (signupAttempt >= 2) {
@@ -2176,6 +2214,7 @@ function wizardHtml(defaults) {
       .spinner { width:14px; height:14px; border:2px solid #334a87; border-top-color:#8daeff; border-radius:50%; animation:spin 0.8s linear infinite; flex:0 0 auto; }
       .muted a { color:#9fd3ff; }
       .muted a:hover { color:#c5e5ff; }
+      .info-dot { display:inline-flex; align-items:center; justify-content:center; width:18px; height:18px; border-radius:50%; background:#22315a; color:#9cb0de; font-size:11px; font-weight:700; cursor:help; flex-shrink:0; }
       @keyframes spin { to { transform:rotate(360deg); } }
     </style>
   </head>
@@ -2253,6 +2292,13 @@ function wizardHtml(defaults) {
             <p class="muted">Already have a TraderClaw account? Paste your API key here. New users: leave empty.</p>
           </div>
         </div>
+        <div style="margin-top:12px;">
+          <label style="display:flex;align-items:center;gap:8px;">Referral code (optional)
+            <span class="info-dot" title="Included access: 24 hours for every new account. Add a valid referral code for an extra 24 hours. Refer others: when they complete at least one trade with the agent, you earn +8 hours per active referral. When your access window ends, you will need to stake or keep referring to continue.">i</span>
+          </label>
+          <input id="referralCode" type="text" maxlength="16" autocomplete="off" placeholder="e.g. ABCD1234" />
+          <p class="muted">If you have a friend’s code, enter it here. The setup command below will include it for <code>traderclaw setup</code>. If the server rejects the code, clear this field or fix it and copy the updated command — or run <code>traderclaw setup</code> again and enter a valid code or leave referral blank when prompted.</p>
+        </div>
         <button id="start" disabled>Start Installation</button>
       </div>
       <div class="card" id="statusCard">
@@ -2361,6 +2407,7 @@ function wizardHtml(defaults) {
       let llmLoadStartedAt = 0;
       let announcedTailscaleUrl = "";
       let announcedFunnelAdminUrl = "";
+      let lastReferralFailFingerprint = "";
       let pollTimer = null;
       let pollIntervalMs = 1200;
       let installLocked = false;
@@ -2555,6 +2602,7 @@ function wizardHtml(defaults) {
           llmCredential: llmCredentialEl.value.trim(),
           apiKey: document.getElementById("apiKey").value.trim(),
           telegramToken: document.getElementById("telegramToken").value.trim(),
+          referralCode: document.getElementById("referralCode").value.trim(),
           xConsumerKey: xConsumerKeyEl.value.trim(),
           xConsumerSecret: xConsumerSecretEl.value.trim(),
           xAccessTokenMain: xAccessTokenMainEl.value.trim(),
@@ -2716,9 +2764,30 @@ function wizardHtml(defaults) {
         }
 
         const errors = data.errors || [];
-        manualEl.textContent = errors.length > 0
+        let manualText = errors.length > 0
           ? errors.map((e) => "Step " + (e.stepId || "unknown") + ":\\n" + (e.error || "")).join("\\n\\n")
           : "";
+        const combinedErr = errors.map((e) => e.error || "").join("\\n");
+        if (
+          data.status === "failed"
+          && /REFERRAL_CODE_INVALID|Unknown referral code/i.test(combinedErr)
+        ) {
+          manualText +=
+            (manualText ? "\\n\\n" : "") +
+            "Referral code was rejected. Clear or fix the referral field above, then click Start Installation again.";
+          const fp = combinedErr.slice(0, 240);
+          if (fp && fp !== lastReferralFailFingerprint) {
+            lastReferralFailFingerprint = fp;
+            try {
+              window.alert(
+                "Referral code was not accepted. Update or clear the referral field, then click Start Installation again.",
+              );
+            } catch {
+              /* ignore */
+            }
+          }
+        }
+        manualEl.textContent = manualText;
         stepsEl.innerHTML = "";
         steps.forEach((row) => {
           const tr = document.createElement("tr");
@@ -2938,6 +3007,7 @@ async function cmdInstall(args) {
         enableTelegram: true,
         telegramToken: body.telegramToken || defaults.telegramToken,
         autoInstallDeps: true,
+        referralCode: typeof body.referralCode === "string" ? body.referralCode.trim() : "",
         xConsumerKey: body.xConsumerKey ?? defaults.xConsumerKey,
         xConsumerSecret: body.xConsumerSecret ?? defaults.xConsumerSecret,
         xAccessTokenMain: body.xAccessTokenMain ?? defaults.xAccessTokenMain,
@@ -2973,6 +3043,7 @@ async function cmdInstall(args) {
           enableTelegram: true,
           telegramToken: body.telegramToken || defaults.telegramToken,
           autoInstallDeps: true,
+          referralCode: wizardOpts.referralCode,
           xConsumerKey: wizardOpts.xConsumerKey,
           xConsumerSecret: wizardOpts.xConsumerSecret,
           xAccessTokenMain: wizardOpts.xAccessTokenMain,
@@ -3227,7 +3298,14 @@ async function cmdTestSession(args) {
   try {
     if (currentRefreshToken && currentAccessToken) {
       mkdirSync(dataDir, { recursive: true });
+      let existingSidecar = {};
+      try {
+        if (existsSync(sessionTokensPath)) {
+          existingSidecar = JSON.parse(readFileSync(sessionTokensPath, "utf-8")) || {};
+        }
+      } catch { /* ignore */ }
       const payload = {
+        ...existingSidecar,
         refreshToken: currentRefreshToken,
         accessToken: currentAccessToken,
         accessTokenExpiresAt: Date.now() + 900_000,
@@ -3304,6 +3382,7 @@ Setup options:
   --gateway-base-url, -g  Gateway public HTTPS URL for orchestrator callbacks
   --gateway-token, -t     Gateway bearer token (defaults to API key)
   --telegram-recipient    Telegram @username or chat id (aliases: --forward-telegram-chat-id, --telegram-chat-id)
+  --referral-code, -r   Optional referral code for new signups (extra trial time when valid)
   --skip-gateway-registration  Skip gateway URL registration with orchestrator
   --show-api-key     Extra hint after signup (full key is always shown once; confirm with API_KEY_STORED)
   --show-wallet-private-key  Reveal full wallet private key in setup output
@@ -3333,7 +3412,7 @@ Examples:
   traderclaw install --wizard
   traderclaw install --wizard --lane quick-local
   traderclaw gateway ensure-persistent
-  traderclaw setup --signup --user-id my_agent_001
+  traderclaw setup --signup --user-id my_agent_001 --referral-code ABCD1234
   traderclaw setup --api-key oc_xxx --url https://api.traderclaw.ai
   traderclaw setup --gateway-base-url https://gateway.myhost.ts.net
   traderclaw setup --telegram-recipient @myusername

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "traderclaw-cli",
-  "version": "1.0.61",
+  "version": "1.0.63",
   "description": "Global TraderClaw CLI (install --wizard, setup, precheck). Installs solana-traderclaw as a dependency for OpenClaw plugin files.",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "solana-traderclaw": "^1.0.61"
+    "solana-traderclaw": "^1.0.63"
   },
   "keywords": [
     "traderclaw",