solana-traderclaw 1.0.88 → 1.0.89

package/dist/{chunk-Q5AWKXY3.js → chunk-4G64IVJO.js}

@@ -13,7 +13,13 @@ var ERROR_CLASSIFICATION = {
   "404": { retryable: false, code: "NOT_FOUND" },
   "500": { retryable: true, code: "SERVER_ERROR" },
   "502": { retryable: true, code: "SERVER_ERROR" },
-  "503": { retryable: true, code: "SERVER_ERROR" }
+  "503": { retryable: true, code: "SERVER_ERROR" },
+  // Referral-specific codes (sent as "CODE: message" by http-client after extraction)
+  "REFERRAL_CODE_TAKEN": { retryable: false, code: "REFERRAL_CODE_TAKEN" },
+  "referral code already taken": { retryable: false, code: "REFERRAL_CODE_TAKEN" },
+  "REFERRAL_CODE_INVALID": { retryable: false, code: "REFERRAL_CODE_INVALID" },
+  "REFERRAL_CODE_ERROR": { retryable: false, code: "REFERRAL_CODE_ERROR" },
+  "alphanumeric": { retryable: false, code: "VALIDATION_ERROR" }
 };
 function generateTraceId() {
   const ts = Date.now().toString(36);

package/dist/{chunk-PIZZXNMQ.js → chunk-NDPVVAV7.js}

@@ -49,7 +49,10 @@ async function doRequest(opts, isRetry = false) {
       return doRequest({ ...opts, accessToken: newToken }, true);
     }
     if (!res.ok) {
-      const errMsg = data && typeof data === "object" && "error" in data ? data.error : `HTTP ${res.status}: ${text.slice(0, 200)}`;
+      const errBody = data && typeof data === "object" && !Array.isArray(data) ? data : null;
+      const errCode = typeof errBody?.code === "string" ? errBody.code : null;
+      const errText = typeof errBody?.message === "string" ? errBody.message : typeof errBody?.error === "string" ? errBody.error : `HTTP ${res.status}: ${text.slice(0, 200)}`;
+      const errMsg = errCode ? `${errCode}: ${errText}` : errText;
       throw new Error(errMsg);
     }
     return data;

package/dist/index.js

@@ -9,7 +9,7 @@ import {
   normalizeToolError,
   normalizeToolSuccess,
   renderToolEnvelope
-} from "./chunk-Q5AWKXY3.js";
+} from "./chunk-4G64IVJO.js";
 import {
   AlphaBuffer
 } from "./chunk-3UQIQJPQ.js";
@@ -18,7 +18,7 @@ import {
 } from "./chunk-3YPZOXWE.js";
 import {
   orchestratorRequest
-} from "./chunk-PIZZXNMQ.js";
+} from "./chunk-NDPVVAV7.js";
 import {
   IntelligenceLab
 } from "./chunk-FBS5FGW2.js";
@@ -2073,6 +2073,27 @@ ${notes}
         })
       )
     });
+    api.registerTool({
+      name: "solana_referral_profile",
+      description: "Read your TraderClaw referral profile: your current referral code (null if not set), access window, tier, and earnings metadata. Call this when the user asks about their referral code, when ACCESS_LIMIT_REACHED is received, or to check whether a code has already been created. This endpoint remains accessible even after the runtime access window has expired \u2014 use it to help the user set up a referral code so they can regain access by referring others. If referralCode is null, prompt the user to choose a custom 4\u201316 alphanumeric code and call solana_referral_set_code with their input.",
+      parameters: Type.Object({}),
+      execute: wrapExecute("solana_referral_profile", async () => get("/api/referral/me"))
+    });
+    api.registerTool({
+      name: "solana_referral_set_code",
+      description: "Set or update your custom TraderClaw referral code. The code must be 4\u201316 alphanumeric characters; it is stored normalized to UPPERCASE. IMPORTANT: You must ask the user to provide the code \u2014 never invent or guess one. Suggest that the code be memorable (e.g. their username, brand, or handle). Once set, anyone who signs up using this code grants you +8 hours of access per active referral. This endpoint remains accessible even after the runtime access window has expired, so the user can always create or update their referral code. After setting the code, confirm the saved value from the response and share it with the user so they can start referring others. Expected errors (check ok=false + errorCode): REFERRAL_CODE_TAKEN \u2014 that exact code is already used by another account; ask the user to choose a different one. VALIDATION_ERROR \u2014 code does not meet the 4\u201316 alphanumeric rule; tell the user which constraint was violated. AUTH_ERROR \u2014 session expired; user must re-authenticate before setting the code.",
+      parameters: Type.Object({
+        referralCode: Type.String({
+          description: "Custom referral code chosen by the user. Must be 4\u201316 alphanumeric characters (letters and digits only). Will be stored as UPPERCASE.",
+          minLength: 4,
+          maxLength: 16
+        })
+      }),
+      execute: wrapExecute(
+        "solana_referral_set_code",
+        async (_id, params) => put("/api/referral/code", { referralCode: String(params.referralCode).trim().toUpperCase() })
+      )
+    });
     api.registerTool({
       name: "solana_bitquery_templates",
       description: "List all available pre-built Bitquery query templates with descriptions and required variables. Call this first to discover what templates are available before using solana_bitquery_catalog. Returns 50+ templates organized by category covering Pump.fun, PumpSwap, Raydium, Jupiter, BonkSwap, and generic DEX analytics.",

package/dist/src/http-client.js

@@ -1,6 +1,6 @@
 import {
   orchestratorRequest
-} from "../chunk-PIZZXNMQ.js";
+} from "../chunk-NDPVVAV7.js";
 export {
   orchestratorRequest
 };

package/dist/src/tool-envelope.js

@@ -3,7 +3,7 @@ import {
   normalizeToolError,
   normalizeToolSuccess,
   renderToolEnvelope
-} from "../chunk-Q5AWKXY3.js";
+} from "../chunk-4G64IVJO.js";
 export {
   envelopedExecute,
   normalizeToolError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.88",
+  "version": "1.0.89",
   "description": "TraderClaw V1-Upgraded — Solana trading for OpenClaw with intelligence lab, tool envelopes, prompt scrubbing, read-only X social intel, and split skill docs",
   "type": "module",
   "main": "./dist/index.js",

package/skills/solana-trader/SKILL.md

@@ -19,7 +19,7 @@ You interact with the orchestrator **exclusively through plugin tools** (e.g. `s
 **Critical rules:**
 - **You do NOT have direct HTTP/API access.** Never attempt to call REST endpoints, use curl/fetch, or construct API URLs.
 - **You do NOT manage authentication.** Bearer tokens, access tokens, API keys, and session credentials are handled automatically by the plugin runtime.
-- **You never sign up, register, or change API keys or wallet keys.** Account creation and credential updates happen only when the **human** runs `traderclaw signup` or `traderclaw setup` / `traderclaw setup --signup` on their machine.
+- **You never sign up, register, or change API keys or wallet keys.** Account creation and credential updates happen only when the **human** runs `traderclaw signup` or `traderclaw setup` / `traderclaw setup --signup` on their machine. The only exception is `solana_referral_set_code`, which lets the user choose a custom referral code — you must always ask the user for the code, never generate one yourself.
 - **Never try to independently verify endpoints.** If you want to check system health, call `solana_system_status`.
 - **Tool errors ARE your diagnostics.** If a tool call returns an error, that error message is the definitive answer. Report the tool error and suggest the user run `traderclaw status` from their terminal.
 - **The CLI handles raw API access.** Users can run `traderclaw status`, `traderclaw config show`, and `traderclaw login` from their terminal.
@@ -121,6 +121,24 @@ Alpha signals are **curated trading calls from real humans** in Telegram and Dis
 
 ---
 
+## Access Limit and Referral Codes
+
+When any tool returns an `ACCESS_LIMIT_REACHED` error, the user's runtime access window has expired. They can restore access by staking $TCLAW or by referring other users. Each active referral (someone who completes at least one trade) adds +8 hours.
+
+**Your protocol when ACCESS_LIMIT_REACHED appears:**
+
+1. Call `solana_referral_profile` to read the user's current referral code.
+2. If `referralCode` is non-null, share it with the user as their active code they can give to others.
+3. If `referralCode` is null, explain that they have not set a referral code yet and ask them to choose one:
+   - It must be 4–16 alphanumeric characters (letters and digits only).
+   - Suggest something memorable — their username, brand name, or a short phrase.
+   - **Never invent or guess a code** — always wait for the user's input.
+   - Once the user provides a code, call `solana_referral_set_code({ referralCode: "THEIRCODE" })`.
+4. Both `solana_referral_profile` and `solana_referral_set_code` remain accessible even when the runtime window has expired, so the user can always manage their code regardless of access status.
+5. Never show a placeholder like `(yourcode)` in user-facing text — always use the real code from `solana_referral_profile`, or explicitly guide the user to create one.
+
+---
+
 ## ⚠️ MANDATORY STARTUP SEQUENCE — Run This EVERY Session
 
 **Exception:** If the incoming message starts with `CRON_JOB:`, skip startup and go directly to cron job handling.

package/skills/solana-trader/refs/api-reference.md

@@ -73,6 +73,8 @@ All authenticated endpoints use `Authorization: Bearer <accessToken>`.
 | `POST` | `/api/wallet/token-balance` | `walletId`, `tokenAddress` | On-chain SPL `uiAmount` (source of truth) for a specific mint in wallet. Use to verify actual holdings. |
 | `POST` | `/api/wallet/sweep-dead-tokens` | `walletId` | Sells **100%** of each **open** position with `unrealizedReturnPct ≤ -maxLossPct`. Optional: `maxLossPct` (default **80**), `slippageBps`, `dryRun`. **`trade:execute` scope.** |
 | `GET` | `/api/system/status` | — | System health and connectivity |
+| `GET` | `/api/referral/me` | — | Read referral profile: `referralCode`, `accessUntil`, tier, earnings. **Runtime-gate exempt** — accessible even after access window expires. |
+| `PUT` | `/api/referral/code` | `referralCode` (body) | Set or update custom referral code. Must be 4–16 alphanumeric characters; stored as UPPERCASE. **Runtime-gate exempt** — accessible even after access window expires. |
 
 ## Key Contract Notes
 

package/skills/solana-trader/workspace/TOOLS.md

@@ -13,7 +13,7 @@ Things like:
 - Rate limit observations
 - Anything environment-specific
 
-## Tool Inventory (101 tools — 98 Solana + 3 X read-only)
+## Tool Inventory (103 tools — 100 Solana + 3 X read-only)
 
 Every tool has a mandatory trigger — when the trigger condition is met, you MUST call the tool. "Cron-only" tools are called during cron jobs, not the heartbeat fast loop.
 
@@ -92,6 +92,12 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 | `solana_entitlement_purchase` | Buy a plan | When user explicitly requests purchase |
 | `solana_entitlement_upgrade` | Upgrade account tier | When user explicitly requests upgrade |
 
+### Referral (2)
+| Tool | Purpose | When to Call |
+|---|---|---|
+| `solana_referral_profile` | Read referral code and access window | On ACCESS_LIMIT_REACHED; when user asks about their referral code or access status |
+| `solana_referral_set_code` | Set or update custom referral code (user must supply the code) | When referral code is null and user wants to start referring others; when user asks to create or change their code |
+
 ### Alpha Signals (5)
 | Tool | Purpose | When to Call |
 |---|---|---|