solana-traderclaw 1.0.82 → 1.0.84

package/README.md

@@ -348,7 +348,6 @@ Pay-as-you-go or Basic tier is required for the read-only social intel tools.
 ### Safety
 | Tool | Description |
 |------|-------------|
-| `solana_killswitch` | Toggle emergency kill switch |
 | `solana_killswitch_status` | Check kill switch state |
 
 ### Wallet

package/config/gateway-v1-upgraded.json5

@@ -29,7 +29,7 @@
         agentId: "main",
         sessionTarget: "isolated",
         delivery: { mode: "none" },
-        message: "CRON_JOB: strategy_evolution\n\nStep 1: Call solana_journal_summary to get aggregate performance stats (win rate, avg PnL, trade count). If fewer than 20 closed trades since the last strategy evolution, skip weight updates but still run pattern detection.\n\nStep 2: Call solana_memory_search for 'strategy_evolution' — find last 3 evolution cycle results. Call solana_memory_search for 'strategy_drift_warning' — find drift warnings since last evolution. Call solana_memory_search for 'pre_trade_rationale' — recent decision patterns.\n\nStep 3: Run Recurring Pattern Detection — search for learning_entry tags, group by area, check linked chains (3+ = confirmed pattern), investigate drift warnings.\n\nStep 4: Call solana_strategy_state to read current feature weights.\n\nStep 5: Call solana_trades to get recent closed trades. Apply ADL checks (direction consistency, weight velocity, reversion check).\n\nStep 6: Compute proposed weight changes. Score each with VFM (Frequency + Failure Reduction + Self-Cost). Only apply changes scoring >= 3/5.\n\nStep 7: Verify guardrails: maxDeltaOk, sumWeightsOk, minTradesOk, floorCapOk. If all pass, call solana_strategy_update with incremented version.\n\nStep 8: Run Named Pattern Recognition — search for winning trade clusters, catalog new patterns, evolve existing ones.\n\nStep 9: Evaluate discovery filter performance. Log all results via solana_memory_write with tags: strategy_evolution, vfm_scorecard, pattern_detection, named_pattern.\n\nFORMATTING RULES:\n- Every token reference MUST use SYMBOL (full_CA) format.\n- Do not execute trades. Do not ask questions.",
+        message: "CRON_JOB: strategy_evolution\n\nStep 1: Call solana_journal_summary to get aggregate performance stats (win rate, avg PnL, trade count). If fewer than 10 closed trades since the last strategy evolution, skip weight updates but still run pattern detection.\n\nStep 2: Call solana_memory_search for 'strategy_evolution' — find last 3 evolution cycle results. Call solana_memory_search for 'strategy_drift_warning' — find drift warnings since last evolution. Call solana_memory_search for 'pre_trade_rationale' — recent decision patterns.\n\nStep 3: Run Recurring Pattern Detection — search for learning_entry tags, group by area, check linked chains (3+ = confirmed pattern), investigate drift warnings.\n\nStep 4: Call solana_strategy_state to read current feature weights.\n\nStep 5: Call solana_trades to get recent closed trades. Apply ADL checks (direction consistency, weight velocity, reversion check).\n\nStep 6: Compute proposed weight changes. Score each with VFM (Frequency + Failure Reduction + Self-Cost). Only apply changes scoring >= 3/5.\n\nStep 7: Verify guardrails: maxDeltaOk, sumWeightsOk, minTradesOk, floorCapOk. If all pass, call solana_strategy_update with incremented version.\n\nStep 8: Run Named Pattern Recognition — search for winning trade clusters, catalog new patterns, evolve existing ones.\n\nStep 9: Evaluate discovery filter performance. Log all results via solana_memory_write with tags: strategy_evolution, vfm_scorecard, pattern_detection, named_pattern.\n\nFORMATTING RULES:\n- Every token reference MUST use SYMBOL (full_CA) format.\n- Do not execute trades. Do not ask questions.",
         enabled: true
       },
       {

package/dist/{chunk-C24QA3MQ.js → chunk-FBS5FGW2.js}

@@ -53,8 +53,14 @@ var IntelligenceLab = class {
     } else {
       candidates.push(full);
     }
-    if (candidates.length > 5e3) {
-      candidates.splice(0, candidates.length - 5e3);
+    const MAX_CANDIDATES = 200;
+    if (candidates.length > MAX_CANDIDATES) {
+      const labeled = candidates.filter((c) => c.outcome);
+      const unlabeled = candidates.filter((c) => !c.outcome);
+      const keepUnlabeled = Math.max(0, MAX_CANDIDATES - labeled.length);
+      const trimmed = [...labeled, ...unlabeled.slice(-keepUnlabeled)];
+      candidates.length = 0;
+      candidates.push(...trimmed);
     }
     writeJsonFile(this.candidatesFile(), candidates);
     return existing >= 0 ? candidates[existing] : full;

package/dist/index.js

@@ -21,7 +21,7 @@ import {
 } from "./chunk-PIZZXNMQ.js";
 import {
   IntelligenceLab
-} from "./chunk-C24QA3MQ.js";
+} from "./chunk-FBS5FGW2.js";
 import {
   scrubUntrustedText
 } from "./chunk-AI6MTHUN.js";
@@ -1142,6 +1142,33 @@ var solanaTraderPlugin = {
       fs.writeFileSync(filePath, entries.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
       return entries.length;
     };
+    const volatileStateKeys = /* @__PURE__ */ new Set(["lastHeartbeat", "lastHeartbeatAt"]);
+    const renderSummaryBullets = (key, val) => {
+      if (key === "lastCycleSummary" && val && typeof val === "object") {
+        const s = val;
+        const bullets = ["## Last Cycle Summary", ""];
+        if (s.capitalSol !== void 0) bullets.push(`- **Capital SOL:** ${s.capitalSol}`);
+        if (s.openPositions !== void 0) bullets.push(`- **Open Positions:** ${s.openPositions}`);
+        if (s.signalsProcessed !== void 0) bullets.push(`- **Signals Processed:** ${s.signalsProcessed}`);
+        if (s.topWatch) bullets.push(`- **Top Watch:** ${s.topWatch}`);
+        if (s.xApiStatus) bullets.push(`- **X API Status:** ${s.xApiStatus}`);
+        if (s.bitqueryStatus) bullets.push(`- **Bitquery Status:** ${s.bitqueryStatus}`);
+        const rendered = Object.keys(s).filter((k) => !["capitalSol", "openPositions", "signalsProcessed", "topWatch", "xApiStatus", "bitqueryStatus"].includes(k));
+        for (const rk of rendered.slice(0, 5)) {
+          const rv = s[rk];
+          const disp = typeof rv === "object" ? JSON.stringify(rv) : String(rv);
+          bullets.push(`- **${rk}:** ${disp.length > 120 ? disp.slice(0, 120) + "\u2026" : disp}`);
+        }
+        bullets.push("");
+        return bullets;
+      }
+      return [];
+    };
+    const formatStateValue = (val) => {
+      if (val === null || val === void 0) return String(val);
+      if (typeof val === "object") return JSON.stringify(val);
+      return String(val);
+    };
     const generateMemoryMd = (aid, stateObj) => {
       const lines = [
         `# ${aid} \u2014 Durable Memory`,
@@ -1160,7 +1187,7 @@ var solanaTraderPlugin = {
       if (state.walletId) identity.push(`- **Wallet:** ${state.walletId}`);
       if (state.mode) identity.push(`- **Mode:** ${state.mode}`);
       if (state.strategyVersion) identity.push(`- **Strategy Version:** ${state.strategyVersion}`);
-      if (state.regime) identity.push(`- **Regime:** ${state.regime}`);
+      if (state.regime) identity.push(`- **Regime:** ${formatStateValue(state.regime)}`);
       if (state.maxPositions) identity.push(`- **Max Positions:** ${state.maxPositions}`);
       if (state.maxPositionSizeSol) identity.push(`- **Max Position Size:** ${state.maxPositionSizeSol} SOL`);
       if (identity.length > 0) {
@@ -1192,13 +1219,24 @@ var solanaTraderPlugin = {
         const rc = state.regimeCanary;
         lines.push("## Regime Canary", "", `- **Regime:** ${rc.regime || "unknown"}`, `- **Detected At:** ${rc.detectedAt || "unknown"}`, "");
       }
-      const excludeKeys = /* @__PURE__ */ new Set(["tier", "walletId", "mode", "strategyVersion", "regime", "maxPositions", "maxPositionSizeSol", "defenseMode", "killSwitchActive", "watchlist", "permanentLearnings", "regimeCanary"]);
-      const otherKeys = Object.keys(state).filter((k) => !excludeKeys.has(k));
-      if (otherKeys.length > 0) {
+      const structuredKeys = /* @__PURE__ */ new Set(["tier", "walletId", "mode", "strategyVersion", "regime", "maxPositions", "maxPositionSizeSol", "defenseMode", "killSwitchActive", "watchlist", "permanentLearnings", "regimeCanary"]);
+      const summaryKeys = /* @__PURE__ */ new Set(["lastCycleSummary"]);
+      const otherKeys = Object.keys(state).filter((k) => !structuredKeys.has(k) && !volatileStateKeys.has(k));
+      const summaryRendered = [];
+      const remainingKeys = [];
+      for (const key of otherKeys) {
+        if (summaryKeys.has(key)) {
+          summaryRendered.push(...renderSummaryBullets(key, state[key]));
+        } else {
+          remainingKeys.push(key);
+        }
+      }
+      if (summaryRendered.length > 0) lines.push(...summaryRendered);
+      if (remainingKeys.length > 0) {
         lines.push("## Other State Keys", "");
-        for (const key of otherKeys.slice(0, 30)) {
+        for (const key of remainingKeys.slice(0, 30)) {
           const val = state[key];
-          const display = typeof val === "object" ? JSON.stringify(val) : String(val);
+          const display = formatStateValue(val);
           lines.push(`- **${key}:** ${display.length > 200 ? display.slice(0, 200) + "\u2026" : display}`);
         }
         lines.push("");
@@ -1721,15 +1759,6 @@ ${notes}
         })
       )
     });
-    api.registerTool({
-      name: "solana_killswitch_status",
-      description: "Check the current kill switch state \u2014 whether it's enabled and in what mode.",
-      parameters: Type.Object({}),
-      execute: wrapExecute(
-        "solana_killswitch_status",
-        async () => get(`/api/killswitch/status?walletId=${walletId}`)
-      )
-    });
     api.registerTool({
       name: "solana_capital_status",
       description: "Get your current capital status \u2014 SOL balance, open position count, unrealized/realized PnL, daily notional used, daily loss, and effective limits. **PnL:** for Solana wallets, `totalUnrealizedPnl` / `totalRealizedPnl` / `totalPnl` are returned in SOL-native units.",
@@ -1954,34 +1983,6 @@ ${notes}
         })
       )
     });
-    api.registerTool({
-      name: "solana_wallet_token_balance",
-      description: "Get the on-chain SPL token balance (uiAmount \u2014 source of truth) for a specific mint in your trading wallet. Returns the token amount, decimals, and USD value estimate. Use to verify actual holdings when position balances seem inconsistent.",
-      parameters: Type.Object({
-        tokenAddress: Type.String({ description: "Solana token mint address to check balance for" })
-      }),
-      execute: wrapExecute(
-        "solana_wallet_token_balance",
-        async (_id, params) => post("/api/wallet/token-balance", { tokenAddress: params.tokenAddress })
-      )
-    });
-    api.registerTool({
-      name: "solana_sweep_dead_tokens",
-      description: "Sell 100% of open positions where unrealizedReturnPct \u2264 -maxLossPct to cut losses and reclaim SOL. NOT a dust/rent sweeper \u2014 this sells actual positions that are down beyond recovery. Use in dead_money_sweep cron or manual loss-cutting.",
-      parameters: Type.Object({
-        maxLossPct: Type.Optional(Type.Number({ description: "Maximum loss percentage threshold \u2014 positions down more than this % are sold (default: 80)" })),
-        slippageBps: Type.Optional(Type.Number({ description: "Slippage in basis points for the sell orders (default: server default)" })),
-        dryRun: Type.Optional(Type.Boolean({ description: "If true, return positions that would be sold without executing. Default: false" }))
-      }),
-      execute: wrapExecute(
-        "solana_sweep_dead_tokens",
-        async (_id, params) => post("/api/wallet/sweep-dead-tokens", {
-          maxLossPct: params.maxLossPct,
-          slippageBps: params.slippageBps,
-          dryRun: params.dryRun
-        })
-      )
-    });
     api.registerTool({
       name: "solana_trades",
       description: "List your trade history with pagination. Returns executed trades with details like token, side, size, PnL, and timestamp.",
@@ -2449,6 +2450,29 @@ ${notes}
         const capitalOnly = failed === 1 && steps.find((s) => !s.ok)?.step === "solana_capital_status";
         startupGateState = { ok: allOk, ts: Date.now(), steps };
         const k = config.apiKey && String(config.apiKey).trim() || null;
+        if (allOk || capitalOnly) {
+          try {
+            const effectiveAgentId = config.agentId || "main";
+            const stateFilePath = path.join(stateDir, `${effectiveAgentId}.json`);
+            const existing = readJsonFile(stateFilePath);
+            const existingState = existing?.state && typeof existing.state === "object" ? existing.state : {};
+            const alphaStep = steps.find((s) => s.step === "solana_alpha_subscribe" && s.ok);
+            const tier = alphaStep?.details?.tier;
+            const seedFields = {};
+            if (!existingState.walletId && walletId) seedFields.walletId = walletId;
+            if (!existingState.tier && tier) seedFields.tier = tier;
+            if (!existingState.mode) seedFields.mode = "HARDENED";
+            if (!existingState.strategyVersion) seedFields.strategyVersion = "1.0.0";
+            if (Object.keys(seedFields).length > 0) {
+              const merged = { ...existingState, ...seedFields };
+              writeJsonFile(stateFilePath, { agentId: effectiveAgentId, state: merged, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
+              writeMemoryMd(effectiveAgentId, merged);
+              api.logger.info(`[solana-trader] Seeded identity fields into state: ${Object.keys(seedFields).join(", ")}`);
+            }
+          } catch (seedErr) {
+            api.logger.warn(`[solana-trader] Failed to seed identity fields: ${seedErr instanceof Error ? seedErr.message : String(seedErr)}`);
+          }
+        }
         return {
           ok: allOk,
           ts: Date.now(),
@@ -2598,6 +2622,49 @@ ${notes}
       parameters: Type.Object({}),
       execute: wrapExecute("solana_system_status", async () => get("/api/system/status"))
     });
+    api.registerTool({
+      name: "solana_storage_status",
+      description: "Check local VPS disk usage and plugin storage health. Reports disk free/total, daily log count + size, candidates count, session directory size. Use in heartbeat Step 0 or risk_audit to detect disk pressure before it causes silent failures.",
+      parameters: Type.Object({}),
+      execute: wrapExecute("solana_storage_status", async () => {
+        const os = await import("os");
+        const result = {};
+        try {
+          const stat = fs.statfsSync(workspaceRoot);
+          const totalGB = Math.round(stat.bsize * stat.blocks / 1024 ** 3 * 100) / 100;
+          const freeGB = Math.round(stat.bsize * stat.bavail / 1024 ** 3 * 100) / 100;
+          const usedPct = Math.round((1 - freeGB / totalGB) * 100);
+          result.disk = { totalGB, freeGB, usedPct, warning: usedPct > 85, critical: usedPct > 95 };
+        } catch {
+          result.disk = { error: "unable to read disk stats" };
+        }
+        try {
+          const logFiles = fs.readdirSync(memoryDir).filter((f) => f.endsWith(".md"));
+          let totalBytes = 0;
+          for (const f of logFiles) {
+            try {
+              totalBytes += fs.statSync(path.join(memoryDir, f)).size;
+            } catch {
+            }
+          }
+          result.dailyLogs = { count: logFiles.length, totalKB: Math.round(totalBytes / 1024) };
+        } catch {
+          result.dailyLogs = { count: 0, totalKB: 0 };
+        }
+        try {
+          const candidatesPath = intelligenceLab.exportDataset("json");
+          const parsed = JSON.parse(candidatesPath);
+          const labeled = Array.isArray(parsed) ? parsed.filter((c) => c.outcome).length : 0;
+          const total = Array.isArray(parsed) ? parsed.length : 0;
+          result.candidates = { total, labeled, unlabeled: total - labeled };
+        } catch {
+          result.candidates = { total: 0, labeled: 0, unlabeled: 0 };
+        }
+        result.memoryRAM = { rssKB: Math.round(process.memoryUsage().rss / 1024), heapUsedKB: Math.round(process.memoryUsage().heapUsed / 1024) };
+        result.uptime = { systemHours: Math.round(os.uptime() / 3600 * 10) / 10, processHours: Math.round(process.uptime() / 3600 * 10) / 10 };
+        return result;
+      })
+    });
     api.registerTool({
       name: "solana_startup_gate",
       description: "Run the mandatory startup sequence and return deterministic pass/fail results per step. Optionally auto-fixes gateway credentials if gatewayBaseUrl and gatewayToken are present in plugin config. On full pass, includes welcomeMessage. If the only failed step is solana_capital_status (e.g. capital API error), still includes welcomeMessage so the user gets onboarding text; check welcomeNote in that case.",

package/dist/src/intelligence-lab.js

@@ -1,6 +1,6 @@
 import {
   IntelligenceLab
-} from "../chunk-C24QA3MQ.js";
+} from "../chunk-FBS5FGW2.js";
 import "../chunk-JO3BXAUQ.js";
 export {
   IntelligenceLab

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.82",
+  "version": "1.0.84",
   "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/HEARTBEAT.md

@@ -215,6 +215,8 @@ HARDENED range: +100–300%. DEGEN range: +200–500%. `percent` = price increas
 
 **Pre-trade journal FIRST** — call `solana_memory_write` with tag `pre_trade_rationale` BEFORE executing. Also call `solana_decision_log` to record the decision with confidence, sizing rationale, and risk factors.
 
+**Source attribution (mandatory):** The `pre_trade_rationale` memory entry MUST include `source: "<how you found this token>"` — one of: `alpha_signal:<source_name>`, `scan_launches`, `scan_hot_pairs`, `bitquery_subscription`, `manual`, `watchlist`. This is required for source trust scoring and strategy evolution to correlate wins/losses with discovery channels.
+
 **Prior history check (mandatory):**
 ```
 solana_memory_by_token({ tokenAddress: "CA" })
@@ -308,22 +310,31 @@ Execute exits via `solana_trade_execute` with `side: "sell"`.
 
 Partial exits → "🔴 PARTIAL EXIT (50%): SYMBOL (CA)"
 
-**Post-exit mandatory actions:**
+**Post-exit mandatory actions (ALL required — skipping any is a critical violation):**
 
 1. Call `solana_trade_review` for each closed position.
 
-2. Label the outcome for intelligence lab learning:
+2. **LABEL THE OUTCOME — CRITICAL, DO NOT SKIP:**
 ```
 solana_candidate_label_outcome({ id: "CA", outcome: "win|loss|skip|dead_money", pnlPct: X.XX, holdingHours: H })
 ```
-This is how the intelligence lab learns. Every exit MUST be labeled.
+The intelligence lab CANNOT learn without labeled outcomes. An unlabeled exit is wasted data. If you skip this call, the entire learning pipeline is broken — strategy evolution, model evaluation, and replay all depend on labeled candidates.
+
+3. **LEARNING ENTRY — REQUIRED after every loss or dead_money exit:**
+```
+solana_memory_write({
+  content: "LEARNING ENTRY: LRN-YYYYMMDD-NNN\nPriority: P2\nArea: <area_tag>\nWHAT HAPPENED: <1 sentence>\nWHY IT WENT WRONG: <root cause>\nEVIDENCE: token CA, entry price, exit price, hold time\nSUGGESTED ADJUSTMENT: <what to change>",
+  tags: ["learning_entry", "learning_entry_<area>"]
+})
+```
+Losses without learning entries are the #1 reason the strategy fails to evolve. Check `refs/review-learning.md` for the full entry format and area tags.
 
-3. Unsubscribe from Bitquery stream for the exited token:
+4. Unsubscribe from Bitquery stream for the exited token:
 ```
 solana_bitquery_unsubscribe({ subscriptionId: "<id>" })
 ```
 
-4. If this was an alpha-sourced trade, check and record source accuracy:
+5. If this was an alpha-sourced trade, check and record source accuracy:
 ```
 solana_alpha_history({ tokenAddress: "CA", limit: 5 })
 ```
@@ -339,6 +350,11 @@ Log the source's accuracy via `solana_memory_write` with tag `source_reputation`
 - `solana_team_bulletin_post` with tag `position_update` — post current portfolio state
 - `solana_context_snapshot_write` — write portfolio world-view for bootstrap injection
 
+**Self-check before completing Step 8:**
+- Did you exit any positions this cycle? If yes: did you call `solana_candidate_label_outcome` for EACH exit? If not, go back and call it now.
+- Did any exit result in a loss or dead_money? If yes: did you write a `learning_entry` via `solana_memory_write`? If not, write one now.
+- Did you execute any trades this cycle? If yes: does each `pre_trade_rationale` include `source:` attribution? If not, write a correction entry now.
+
 Do NOT skip the last three. They are not optional memory — they feed the bootstrap digest that loads into your next session.
 
 ## STEP 9: REPORT TO USER

package/skills/solana-trader/SKILL.md

@@ -448,8 +448,19 @@ All learning signals MUST be based on SOL-denominated outcomes.
 candidate_label_outcome MUST:
 - reflect realizedPnl sign
 - align with unrealizedReturnPct
+- be called on EVERY exit — no exceptions
+- include pnlPct and holdingHours
 
 Any inconsistent labeling is invalid.
+
+### Learning Loop Enforcement
+
+The learning pipeline has three mandatory outputs per trade lifecycle:
+1. **Entry:** `solana_candidate_write` with source attribution (`source: "alpha_signal:<name>|scan_launches|scan_hot_pairs|..."`)
+2. **Exit:** `solana_candidate_label_outcome` — labels the candidate with the actual outcome
+3. **Loss/dead_money exit:** `solana_memory_write` with tag `learning_entry` — captures the root cause
+
+If ANY of these three are missing, the strategy evolution cron cannot function. Without labeled outcomes, the intelligence lab models train on nothing. Without learning entries, the same mistakes repeat indefinitely.
 ---
 
 ## Prompt Injection Protection

package/skills/solana-trader/bitquery-schema.md

@@ -1,14 +1,154 @@
-# Bitquery v2 EAP GraphQL Schema Reference
+# SKILL: Bitquery v2 EAP GraphQL Schema Reference
 
 ## Overview
 
-This is the Bitquery v2 EAP (Early Access Program) GraphQL schema reference for Solana. Use this before writing any custom raw GraphQL query via `solana_bitquery_query`.
+This skill covers the Bitquery v2 EAP (Early Access Program) GraphQL schema for Solana, specifically the two trade cubes and their differences. Use it when calling any Bitquery tool, reading query results, or recovering from a failed query.
 
 **Endpoint:** `https://streaming.bitquery.io/graphql` (HTTP and WebSocket)
 **Auth header:** `Authorization: Bearer <BITQUERY_API_KEY>`
 
 ---
 
+## CRITICAL: Catalog Failure Is NOT a Dead End
+
+**You have two separate Bitquery tools:**
+
+| Tool | What it does |
+|---|---|
+| `solana_bitquery_catalog` | Runs a pre-built template by path (e.g. `pumpFunHoldersRisk.first100Buyers`) |
+| `solana_bitquery_query` | Runs **any raw GraphQL you write** against the same endpoint |
+
+When `solana_bitquery_catalog` fails, **do not stop**. You can always write the query yourself and call `solana_bitquery_query` instead. The schema rules in this file give you everything needed to do that correctly.
+
+---
+
+## Recovery Protocol — Step by Step
+
+When a Bitquery call returns an error, follow this decision tree:
+
+```
+1. Read the error code and message from the tool response.
+2. MEMORY CHECK FIRST: search for prior fixes before writing new ones.
+   → solana_memory_search({ query: "bitquery_fix_applied <template_path_or_error_snippet>", limit: 3 })
+   → If a matching fix exists, apply it directly — skip to step 6.
+3. Classify the error (see table below).
+4. If SCHEMA error → apply the fix from "Common Schema Errors → Fix Map" below
+                   → call solana_bitquery_query with corrected GraphQL.
+5. If OPERATIONAL error → retry with backoff (max 2 retries) or skip this data.
+6. If AUTH error → report to user; do not retry.
+7. MEMORY WRITE: after any recovery attempt, record the result:
+   → Success: solana_memory_write with tag "bitquery_fix_applied"
+   → Failure: solana_memory_write with tag "bitquery_recovery_failed"
+   → Repeated failure on same template: solana_memory_write with tag "bitquery_template_broken"
+```
+
+### Memory Integration for Recovery
+
+**Search before recovering** — always check if you've fixed this error before:
+```
+solana_memory_search({ query: "bitquery_fix_applied", limit: 5 })
+```
+Prior fixes contain the exact corrected query and variables that worked. Reusing them is faster and more reliable than re-deriving the fix.
+
+**Write after recovering** — record every fix attempt:
+```
+// Successful fix:
+solana_memory_write({
+  content: "Bitquery fix: <template_path> failed with '<error_message>'. Fixed by switching cube from DEXTrades to DEXTradeByTokens. Working query: <corrected_query>. Variables: <variables>.",
+  tags: ["bitquery_fix_applied"]
+})
+
+// Failed recovery:
+solana_memory_write({
+  content: "Bitquery recovery failed: <template_path> error '<error_message>'. Tried: <what_was_attempted>. Result: still failing.",
+  tags: ["bitquery_recovery_failed"]
+})
+
+// Template consistently broken (2+ failures):
+solana_memory_write({
+  content: "Bitquery template broken: <template_path> consistently fails with '<error_pattern>'. Recommend using solana_bitquery_query with custom GraphQL instead.",
+  tags: ["bitquery_template_broken"]
+})
+```
+
+This memory loop prevents the agent from re-deriving the same fix every session and creates a growing knowledge base of working query patterns.
+
+### Error Classification
+
+| Response indicator | Class | Action |
+|---|---|---|
+| `code: "BITQUERY_QUERY_FAILED"` + message contains `Cannot query field` | SCHEMA | Fix the field/cube in your query (see Fix Map) |
+| `code: "BITQUERY_QUERY_FAILED"` + message contains `Unknown argument` | SCHEMA | Remove unsupported argument (e.g. `groupBy`) |
+| `code: "BITQUERY_QUERY_FAILED"` + message contains `Variable ... is never used` | SCHEMA | Remove the undeclared variable from the query signature |
+| `code: "BITQUERY_QUERY_FAILED"` + message contains `Argument ... has invalid value` | SCHEMA | Fix the WHERE filter shape (wrong cube or wrong field path) |
+| `code: "BITQUERY_QUERY_FAILED"` + message contains `context deadline exceeded` or `aborted` | OPERATIONAL — TIMEOUT | Add `Block: { Time: { since: $since } }` to WHERE; retry once |
+| `code: "BITQUERY_QUERY_FAILED"` + HTTP 429 | OPERATIONAL — RATE LIMIT | Wait 5s and retry once; if still failing, skip and note |
+| `code: "BITQUERY_QUERY_FAILED"` + HTTP 500 | OPERATIONAL — SERVER | Retry once after 3s; if still failing, skip this data point |
+| `code: "BITQUERY_API_KEY_MISSING"` | AUTH | Report to user — no retry possible |
+| Response `ok: false` + no `errors[]` and no HTTP status | NETWORK | Retry once; if failing, skip |
+| Response `ok: true`, `data` present but all arrays are empty | NOT AN ERROR | The query is valid — the token/time window has no data |
+
+### Writing a Custom Query to Replace a Failed Catalog Call
+
+1. Call `solana_bitquery_templates` to find the closest existing template and read its operation text as a starting point.
+2. Read the error message. Match it to the Fix Map table below.
+3. Apply the fix (change cube, fix field path, remove bad argument, etc.).
+4. Call `solana_bitquery_query` with:
+   - `query`: your corrected GraphQL string
+   - `variables`: the same variables you were going to pass
+
+**Example — catalog call fails with "Cannot query field `Currency` on DEXTrades":**
+```
+// Original catalog call (fails):
+solana_bitquery_catalog({ templatePath: "pumpFunTradesLiquidity.latestTradesByToken", variables: { token: "...", limit: 10 } })
+
+// Error: Cannot query field "Currency" on type "Solana_DEXTrade_Fields_Trade"
+// Fix: switch cube from DEXTrades → DEXTradeByTokens (Trade.Currency is valid there)
+
+// Recovery call:
+solana_bitquery_query({
+  query: `query LatestTradesByToken($token: String!, $limit: Int!) {
+    Solana {
+      DEXTradeByTokens(
+        where: { Trade: { Currency: { MintAddress: { is: $token } } } }
+        orderBy: { descending: Block_Time }
+        limit: { count: $limit }
+      ) {
+        Block { Time }
+        Trade { PriceInUSD Amount AmountInUSD Side { Type } }
+      }
+    }
+  }`,
+  variables: { token: "...", limit: 10 }
+})
+```
+
+### When to Give Up vs When to Recover
+
+**Always attempt recovery (1 retry with a corrected query):**
+- Any SCHEMA error — you have the knowledge to fix it from this file.
+- TIMEOUT — add a `since` filter and retry.
+
+**Skip and continue without this data point:**
+- Two consecutive failures on the same query path.
+- AUTH errors.
+- The data is supplementary (not required for the trade decision).
+
+**Block the trade:**
+- FRESH token analysis fails for `first100Buyers` AND `devHoldings` after recovery attempts — risk is unquantifiable.
+
+---
+
+## Catalog vs Live Schema — Why 400s Happen
+
+A query path being registered in `OPENCLAW_QUERY_TEMPLATES` (e.g. `pumpFunHoldersRisk.first100Buyers`) only means the **path string** resolves to a GraphQL operation. It does **not** guarantee the operation is schema-valid.
+
+When `runCatalogQuery` returns `ok: false` with HTTP 400 (or HTTP 200 with `errors[]`), the stored GraphQL text has a schema violation. Fix it in `SpyFly/Contexts/openClawAPI/bitQuery.js`.
+
+The most common root causes are using `DEXTrades`-only fields (`Trade.Currency`, `Trade.Buyer`, `Trade.PriceInUSD`, `Trade.Side`, `Trade.AmountInUSD`) on the wrong cube, or using `groupBy` on `DEXTradeByTokens`.
+
+---
+
 ## The Two Trade Cubes
 
 Bitquery v2 has two Solana trade cubes with **fundamentally different `Trade` shapes**. Mixing them up causes `Cannot query field "X" on type "Solana_DEXTrade_Fields_Trade"` errors.
@@ -43,11 +183,11 @@ DEXTrades(...) {
 ```
 
 **WHERE filters in DEXTrades:**
-- Filter by Dex: `Trade: { Dex: { ProtocolName: { includes: "pump" } } }`
-- Filter by token (buy side): `Trade: { Buy: { Currency: { MintAddress: { is: $token } } } }`
-- Filter by signer: `Transaction: { Signer: { is: $wallet } }`
-- `Trade: { Currency: { MintAddress: ... } }` — **INVALID on DEXTrades**
-- `Trade: { Buyer: { is: $wallet } }` — **INVALID on DEXTrades**
+- Filter by Dex: `Trade: { Dex: { ProtocolName: { includes: "pump" } } }` ✓
+- Filter by token (buy side): `Trade: { Buy: { Currency: { MintAddress: { is: $token } } } }` ✓
+- Filter by signer: `Transaction: { Signer: { is: $wallet } }` ✓
+- `Trade: { Currency: { MintAddress: ... } }` ✗ — **invalid on DEXTrades**
+- `Trade: { Buyer: { is: $wallet } }` ✗ — **invalid on DEXTrades** — use `Transaction: { Signer: { is: $wallet } }`
 
 **Aggregate keys for DEXTrades:**
 - `sum(of: Trade_Buy_AmountInUSD)` — buy-side USD volume
@@ -79,17 +219,29 @@ DEXTradeByTokens(...) {
 ```
 
 **WHERE filters in DEXTradeByTokens:**
-- Filter by token: `Trade: { Currency: { MintAddress: { is: $token } } }`
-- Filter by side: `Trade: { Side: { Type: { is: buy } } }`
-- Filter by Dex: `Trade: { Dex: { ProtocolName: { includes: "pump" } } }`
+- Filter by token: `Trade: { Currency: { MintAddress: { is: $token } } }` ✓
+- Filter by side: `Trade: { Side: { Type: { is: buy } } }` ✓
+- Filter by Dex: `Trade: { Dex: { ProtocolName: { includes: "pump" } } }` ✓
 
 **Aggregate keys for DEXTradeByTokens:**
-- `sum(of: Trade_Side_AmountInUSD)` — total USD volume (NOT `Trade_AmountInUSD`)
+- `sum(of: Trade_Side_AmountInUSD)` — total USD volume (use this, NOT `Trade_AmountInUSD`)
 - `sum(of: Trade_Amount)` — native token amount
-- `count(distinct: Transaction_Signer)` — unique traders (NOT `Trade_Buyer`)
+- `count(distinct: Transaction_Signer)` — unique traders (use this, NOT `Trade_Buyer`)
 - `count(distinct: Transaction_Signer, if: {Trade: {Side: {Type: {is: buy}}}})` — unique buyers
-- `groupBy` is NOT supported; use time-bounded aggregate windows instead
-- If `groupBy` is removed, also remove unused variables (e.g. `$intervalSeconds`) from the operation signature
+- `groupBy` is **not supported** on this cube in our current v2 endpoint profile
+- If `groupBy` is removed from a query, remove now-unused variables (e.g. `$intervalSeconds`) from the operation signature and `variableShape` too.
+
+**OHLC without groupBy:** return raw time-series rows (limit 500) and compute candles client-side:
+```graphql
+DEXTradeByTokens(
+  where: {Block: {Time: {since: $since}}, Trade: {Currency: {MintAddress: {is: $token}}}}
+  orderBy: {ascending: Block_Time}
+  limit: {count: 500}
+) {
+  Block { Time }
+  Trade { PriceInUSD Amount AmountInUSD }
+}
+```
 
 ---
 
@@ -150,6 +302,8 @@ BalanceUpdates(
 - `PostBalance` requires aggregation modifier: `PostBalance(maximum: Block_Slot)` to get the latest balance
 - `limitBy` key: use `BalanceUpdate_Account_Token_Owner` (not `BalanceUpdate_Address`)
 - WHERE path: `BalanceUpdate: { Account: { Token: { Owner: { is: $wallet } } } }`
+- For lists of wallets: `Account: { Token: { Owner: { in: $holders } } }`
+- `orderBy` on balance alias: use `BalanceUpdate_balance_maximum` (not `"balance"`)
 
 ---
 
@@ -157,6 +311,8 @@ BalanceUpdates(
 
 In `TokenSupplyUpdates`, the currency metadata field is `Uri` (camel-case), not `URI`.
 
+Use:
+
 ```graphql
 TokenSupplyUpdates(
   where: {
@@ -172,9 +328,12 @@ TokenSupplyUpdates(
 }
 ```
 
+Avoid:
+- `Currency { ... URI }` ✗ (unknown field)
+
 ---
 
-## Common Schema Errors and Fix Map
+## Common Schema Errors → Fix Map
 
 | Error message | Root cause | Fix |
 |---|---|---|
@@ -183,16 +342,19 @@ TokenSupplyUpdates(
 | `Cannot query field "PriceInUSD" on type "Solana_DEXTrade_Fields_Trade"` | Using `Trade.PriceInUSD` on `DEXTrades` | Use `Trade.Buy.PriceInUSD` or `Trade.Sell.PriceInUSD` |
 | `Cannot query field "AmountInUSD" on type "Solana_DEXTrade_Fields_Trade"` | Using `Trade.AmountInUSD` on `DEXTrades` | Use `Trade.Buy.Amount` or switch to `DEXTradeByTokens` |
 | `Cannot query field "Buyer" on type "Solana_DEXTrade_Fields_Trade"` | Using `Trade.Buyer` on `DEXTrades` | Use `Trade.Buy.Account.Address` for output; `Transaction.Signer` for WHERE |
+| `In field "Trade": In field "Buyer": Unknown field` | `Trade: { Buyer: { is: $wallet } }` in WHERE on DEXTrades | Use `Transaction: { Signer: { is: $wallet } }` |
 | `Cannot query field "Address" on type "Solana_BalanceUpdate"` | Using `BalanceUpdate.Address` | Use `BalanceUpdate.Account.Token.Owner` (SPL) or `BalanceUpdate.Account.Owner` (SOL) |
-| `Cannot query field "URI"` | Using uppercase `URI` in `TokenSupplyUpdate.Currency` | Use `Uri` |
-| `Unknown field` in `Instruction.Accounts.Address` | Using direct `Accounts.Address` in `Instructions.where` | Use `Accounts: { includes: { Address: { is: $token } } }` |
-| `Unknown argument "groupBy"` on `DEXTradeByTokens` | Attempting interval grouping | Remove `groupBy`; use aggregate windows over `Block.Time` ranges |
-| `Variable "$intervalSeconds" is never used` | Leftover variable after removing groupBy | Remove from query args and `variableShape` |
-| `Unexpected metric name or alias to order balance` | Ordering by non-existent alias | Order by concrete metric name (e.g. `BalanceUpdate_balance_maximum`) |
-| `Variable "$minCap" of type "Float!"` type mismatch | Comparator input type mismatch | Use `String` vars for `PostBalanceInUSD` filters |
-| `This operation was aborted` | Query exceeded timeout | Increase `options.timeoutMs` (e.g. 120000) and/or reduce scan window/limit |
+| `Cannot query field "URI" on type "Solana_TokenSupplyUpdate_Fields_TokenSupplyUpdate_Currency"` | Using uppercase `URI` in `TokenSupplyUpdate.Currency` | Use `Uri` |
+| `In field "Instruction" -> "Accounts" -> "Address": Unknown field` | Using direct `Accounts.Address` in `Instructions.where` | Use `Accounts: { includes: { Address: { is: $token } } }` |
+| `Unknown argument "groupBy" on field "DEXTradeByTokens" of type "Solana"` | Attempting interval grouping on `DEXTradeByTokens` | Remove `groupBy`; return raw rows and build candles client-side |
+| `Variable "$intervalSeconds" is never used in operation ...` | Query signature still includes interval variable after removing groupBy | Remove `$intervalSeconds` from query args and `variableShape` |
+| `Variable "$wallet" is never used in operation ...` | Variable declared in operation but no field references it | Remove `$wallet` from query args and `variableShape` |
+| `Unexpected metric name or alias to order balance ...` | Ordering by non-existent alias like `"balance"` | Order by concrete metric name returned by engine (e.g. `BalanceUpdate_balance_maximum`) |
+| `Variable "$minCap" of type "Float!" used ... expecting type "String"` | Comparator input type mismatch in token supply filters | Use `String` vars for `PostBalanceInUSD` bound filters in this endpoint profile |
+| `This operation was aborted` / `context deadline exceeded` | Query exceeded request timeout budget — often an unbounded Instructions scan | Add `Block: { Time: { since: $since } }` to the WHERE clause; increase `options.timeoutMs` if needed |
 | `Field "Trade_Buyer" not found` | Aggregate `count(distinct: Trade_Buyer)` | Use `count(distinct: Transaction_Signer)` |
-| `Field "Trade_AmountInUSD" not found` (DEXTradeByTokens) | Wrong aggregate key | Use `Trade_Side_AmountInUSD` |
+| `Field "Trade_AmountInUSD" not found` (in DEXTradeByTokens) | Wrong aggregate key | Use `Trade_Side_AmountInUSD` |
+| `calculate(expression: ...)` not recognized | Unsupported computed field expression | Remove `calculate`; compute derived values client-side instead |
 
 ---
 
@@ -225,15 +387,19 @@ DEXPools(
 
 ---
 
-## Instructions Cube — Account Filters
+## Instructions Cube — Account Filters (Important)
 
-For `Solana.Instructions`, account matching in `where.Instruction.Accounts` must use `includes`, not direct `Address` equality.
+For `Solana.Instructions`, account matching in `where.Instruction.Accounts` must use
+`includes`, not direct `Address` equality.
+
+Use:
 
 ```graphql
 Instructions(
   where: {
+    Block: { Time: { since: $since } }
     Instruction: {
-      Program: { Name: { includes: "pump" } }
+      Program: { Name: { includes: "pump" }, Method: { includes: "create" } }
       Accounts: { includes: { Address: { is: $token } } }
     }
     Transaction: { Result: { Success: true } }
@@ -246,8 +412,13 @@ Instructions(
 ```
 
 Avoid:
-- `Accounts: { Address: { is: $token } }` (invalid shape)
-- Duplicate keys in one input object — combine into one: `Program: { Name: ..., Method: ... }`
+- `Accounts: { Address: { is: $token } }` ✗ (invalid shape)
+
+Also avoid duplicate keys in one input object:
+- `Program: { Name: ... }` and a second `Program: { Method: ... }` in the same object is **invalid** — GraphQL only keeps the last key.
+- Combine into one: `Program: { Name: ..., Method: ... }` ✓
+
+**Always add a `Block.Time.since` filter to Instructions queries** — unbounded Instructions scans (especially with ascending orderBy to find creation events) time out consistently.
 
 ---
 
@@ -257,7 +428,38 @@ Avoid:
 - **DEX filter:** `Trade: { Dex: { ProtocolName: { includes: "pump" } } }`
 - **PumpSwap filter:** `Trade: { Dex: { ProtocolName: { includes: "pumpswap" } } }`
 - **Migration detection:** `Instructions` cube with `Program: { Method: { includes: "migrate" } }`
-- **Bonding curve progress:** Requires `DEXPools` with `Base.PostAmountInUSD`
+- **Bonding curve progress:** Requires `DEXPools` with `Base.PostAmountInUSD` — exact threshold formula requires live testing
+- **First buyers:** Use `DEXTrades` with `Trade: { Buy: { Currency: { MintAddress: { is: $token } } } }` and `orderBy: { ascending: Block_Time }` — output buyer address as `Trade.Buy.Account.Address`
+
+### Token Creation — Correct Method Filter
+
+Filtering Instructions by `Name: {includes: "pump"}` alone returns **all** pump.fun interactions (buys, sells, fees). To target **only new token launches**, filter by the exact program address **and** method:
+
+```graphql
+Instruction: {
+  Program: {
+    Address: {is: "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"}
+    Method: {is: "create_v2"}
+  }
+}
+```
+
+In the result, `Accounts[0].Address` is the **token mint** and `Transaction.Signer` is the **dev wallet**. Not all pump.fun mints use the `pump` vanity suffix — do not filter by address suffix.
+
+Known pump.fun method values (live-verified, 30-day sample of 2000 instructions):
+| Method | Meaning |
+|---|---|
+| `create_v2` | New token launch — **use this for new token detection** |
+| `CreateEvent` | CPI event emitted alongside `create_v2` (single account, less data) |
+| `buy` / `buy_exact_sol_in` / `buy_exact_quote_in` | Buy trades |
+| `sell` | Sell trade |
+| `BuyEvent` / `SellEvent` / `TradeEvent` | CPI event logs for trades |
+| `collect_creator_fee` / `CollectCreatorFeeEvent` | Creator fee collection |
+| `extend_account` / `ExtendAccountEvent` | Account reallocation |
+| `close_user_volume_accumulator` | Volume accumulator housekeeping |
+| `sync_user_volume_accumulator` / `init_user_volume_accumulator` | Volume accumulator lifecycle |
+
+**"Mayhem Mode" does not exist on-chain.** No instruction with `mayhem` in the method name has ever appeared in the pump.fun program. The three catalog templates for it (`trackMayhemModeRealtime`, `currentMayhemModeStatus`, `historicalMayhemModeStatus`) have been removed.
 
 ---
 
@@ -279,8 +481,8 @@ subscription PumpFunTrades($token: String) {
       Block { Time }
       Transaction { Signature }
       Trade {
-        Buy { Currency { MintAddress Symbol } PriceInUSD }
-        Sell { Currency { MintAddress Symbol } PriceInUSD }
+        Buy { Currency { MintAddress Symbol } PriceInUSD Amount }
+        Sell { Currency { MintAddress Symbol } }
       }
     }
   }

package/skills/solana-trader/refs/memory-tags.md

@@ -69,6 +69,16 @@ Used by Steps 0, 5.5, 8.5, 9.
 | `strategy_evolution` | Strategy evolution reasoning log (Step 9) |
 | `discovery_filter_evolution` | Discovery filter parameter updates (Step 9) |
 
+## Bitquery Recovery Tags
+
+Used when Bitquery API calls fail and the agent applies recovery procedures.
+
+| Tag | Purpose |
+|---|---|
+| `bitquery_fix_applied` | Successful Bitquery recovery — records error class, fix applied, and working query/variables |
+| `bitquery_recovery_failed` | Recovery attempt failed — records error class, what was tried, and why it didn't work |
+| `bitquery_template_broken` | Template identified as consistently broken — records template path, error pattern, suggested replacement |
+
 ## System Tags
 
 | Tag | Purpose |
@@ -88,3 +98,4 @@ Used by Steps 0, 5.5, 8.5, 9.
 | `coordinated_shill_detected` | Coordinated shill campaign detected |
 | `website_analyzed` | Website legitimacy analysis result |
 | `alpha_source_model` | Personal alpha source trust model |
+| `memory_trim` | Memory trim cron results |

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

@@ -37,7 +37,6 @@ Every tool has a mandatory trigger — when the trigger condition is met, you MU
 | `solana_wallet_token_balance` | On-chain SPL balance (POST) | Step 0 when position balance seems off; Step 6 for on-chain verification |
 | `solana_sweep_dead_tokens` | Batch-exit losing positions | `dead_money_sweep` cron; Step 0 when multiple dead positions found |
 | `solana_killswitch_status` | Check kill switch state | Step 0 every heartbeat |
-| `solana_killswitch` | Toggle kill switch (enabled + mode) | When consecutive loss limit hit; when user requests |
 | `risk_management_get_default` | Read per-wallet default TP/SL/trailing used when buys omit risk | Before relying on implicit defaults; after user asks about protection |
 | `risk_management_set_default` | Save per-wallet default exit plan for future buys | When user or policy wants custom defaults instead of platform system default |
 | `trade_size_limit_get` | Read max **buy** size (SOL) from wallet `limits` (default 1.5) | Before every buy or when user asks about size limits |