solana-traderclaw 1.0.36 → 1.0.37

package/bin/installer-step-engine.mjs

@@ -619,7 +619,7 @@ function traderCronPrescriptiveJobs(agentId) {
       schedule: "0 * * * *",
       agentId,
       message:
-        "CRON_JOB: alpha_scan — Call solana_scan_launches to find new token launches from the last hour. For each candidate, call solana_token_snapshot to check price, volume, and age. Filter for: 24h volume above 50000 USD, market cap above 10000 USD. For tokens that pass, call solana_token_holders to check holder distribution (skip if top holder owns more than 30 percent), then solana_token_risk to check for mint/freeze authority (hard skip if present). If a token passes all checks, call solana_alpha_submit to add it to the alpha buffer for the CTO's next heartbeat evaluation. Log all scanned tokens and results using solana_memory_write. Do not execute trades directly — only submit to alpha buffer. Do not ask questions.",
+        "CRON_JOB: alpha_scan — Call solana_scan_launches to find new token launches from the last hour. For each candidate, call solana_token_snapshot to check price, volume, and age. Filter for: 24h volume above 50000 USD, market cap above 10000 USD. For tokens that pass, call solana_token_holders to check holder distribution (skip if top holder owns more than 30 percent), then solana_token_risk to check for mint/freeze authority (hard skip if present). If a token passes all checks, use solana_trade_precheck and consider trade execution using solana_trade_execute. Log all scanned tokens and results using solana_memory_write. Do not ask questions.",
       enabled: true,
     },
     {

package/dist/index.js

@@ -1254,14 +1254,31 @@ var solanaTraderPlugin = {
     });
     api.registerTool({
       name: "solana_trade_precheck",
-      description: "Pre-trade risk check \u2014 validates a proposed trade against risk rules, kill switch, entitlement limits, and on-chain conditions. Returns approved/denied with reasons and capped size. Always call this before executing a trade. Buy: sizeSol required; do not send sizeTokens or sellPct. Sell: send exactly one of sizeTokens or sellPct (not sizeSol). If both sellPct and sizeTokens are sent, sellPct is preferred and sizeTokens is ignored.",
+      description: "Pre-trade risk check \u2014 validates a proposed trade against risk rules, kill switch, entitlement limits, and on-chain conditions. Returns approved/denied with reasons and capped size. Always call this before executing a trade. Buy: sizeSol required; do not send sizeTokens or sellPct. Sell: send exactly one of sizeTokens or sellPct (not sizeSol). If both sellPct and sizeTokens are sent, sellPct is preferred and sizeTokens is ignored. Optional exit fields (trailingStopPct, trailingStop) are accepted to mirror execute payloads; sizing logic ignores them.",
       parameters: Type.Object({
         tokenAddress: Type.String({ description: "Solana token mint address" }),
         side: Type.Union([Type.Literal("buy"), Type.Literal("sell")], { description: "Trade direction" }),
         sizeSol: Type.Optional(Type.Number({ description: "Position size in SOL \u2014 required for buy, omit for sell" })),
         sellPct: Type.Optional(Type.Number({ description: "Sell percentage 1\u2013100 (100 = full exit) \u2014 sell only; preferred over sizeTokens if both sent" })),
         sizeTokens: Type.Optional(Type.Number({ description: "Token amount to sell \u2014 sell only; ignored if sellPct is also provided" })),
-        slippageBps: Type.Optional(Type.Number({ description: "Slippage tolerance in basis points (e.g., 300 = 3%)" }))
+        slippageBps: Type.Optional(Type.Number({ description: "Slippage tolerance in basis points (e.g., 300 = 3%)" })),
+        trailingStopPct: Type.Optional(Type.Number({ description: "Optional \u2014 same as execute; ignored for policy sizing" })),
+        trailingStop: Type.Optional(
+          Type.Object({
+            levels: Type.Array(
+              Type.Object({
+                percentage: Type.Number({ description: "Trailing drawdown % from the armed high once the level is active" }),
+                amount: Type.Optional(Type.Number({ description: "% of position to sell at this level (1\u2013100). Server default 100." })),
+                triggerAboveATH: Type.Optional(
+                  Type.Number({
+                    description: "Optional. % above session ATH before this level arms. If omitted, API defaults to 100 (2\xD7 ATH)."
+                  })
+                )
+              }),
+              { minItems: 1, maxItems: 5, description: "Multi-level trailing (optional on precheck)" }
+            )
+          })
+        )
       }),
       execute: wrapExecute(async (_id, params) => {
         const body = {
@@ -1269,6 +1286,13 @@ var solanaTraderPlugin = {
           side: params.side,
           slippageBps: params.slippageBps
         };
+        if (params.trailingStopPct !== void 0) {
+          body.trailingStopPct = params.trailingStopPct;
+        }
+        const ts = params.trailingStop;
+        if (ts?.levels && Array.isArray(ts.levels) && ts.levels.length > 0) {
+          body.trailingStop = ts;
+        }
         if (params.side === "buy") {
           body.sizeSol = params.sizeSol;
         } else {
@@ -1283,7 +1307,7 @@ var solanaTraderPlugin = {
     });
     api.registerTool({
       name: "solana_trade_execute",
-      description: "Execute a trade on Solana via the SpyFly bot. Enforces risk rules before proxying to on-chain execution. Returns trade ID, position ID, and transaction signature. IMPORTANT: tpLevels alone (e.g. [10, 15]) means EACH level sells 100% of the position at that gain \u2014 use tpExits for partials (e.g. +10% sell 50%, +15% sell 100%). Buy: sizeSol required; do not send sizeTokens or sellPct. Sell: send exactly one of sizeTokens or sellPct (not sizeSol). If both sellPct and sizeTokens are sent, sellPct is preferred and sizeTokens is ignored.",
+      description: "Execute a trade on Solana via the SpyFly bot. Enforces risk rules before proxying to on-chain execution. Returns trade ID, position ID, and transaction signature. IMPORTANT: tpLevels alone (e.g. [10, 15]) means EACH level sells 100% of the position at that gain \u2014 use tpExits for partials (e.g. +10% sell 50%, +15% sell 100%). Trailing: use `trailingStopPct` for a single simple trailing %, or `trailingStop.levels` (1\u20135) for multi-level trailing with optional `triggerAboveATH` per level (% above session ATH before that level arms; if omitted, server defaults to 100 i.e. 2\xD7 ATH). When both are sent, `trailingStop` wins. Buy: sizeSol required; do not send sizeTokens or sellPct. Sell: send exactly one of sizeTokens or sellPct (not sizeSol). If both sellPct and sizeTokens are sent, sellPct is preferred and sizeTokens is ignored.",
       parameters: Type.Object({
         tokenAddress: Type.String({ description: "Solana token mint address" }),
         side: Type.Union([Type.Literal("buy"), Type.Literal("sell")], { description: "Trade direction" }),
@@ -1318,7 +1342,37 @@ var solanaTraderPlugin = {
             { description: "Multi-level stop-loss with partial exits (optional). Otherwise use slPct for a single full exit." }
           )
         ),
-        trailingStopPct: Type.Optional(Type.Number({ description: "Trailing stop percentage" })),
+        trailingStopPct: Type.Optional(
+          Type.Number({
+            description: "Single trailing-stop % (legacy). Ignored if `trailingStop` is provided."
+          })
+        ),
+        trailingStop: Type.Optional(
+          Type.Object({
+            levels: Type.Array(
+              Type.Object({
+                percentage: Type.Number({
+                  description: "Once armed, sell when price drops this % from the high (trailing drawdown)."
+                }),
+                amount: Type.Optional(
+                  Type.Number({
+                    description: "% of position to sell when this level fires (1\u2013100). Server default 100."
+                  })
+                ),
+                triggerAboveATH: Type.Optional(
+                  Type.Number({
+                    description: "Optional. Session price must reach this % above session ATH before this level arms (e.g. 50 \u2192 1.5\xD7 ATH). If omitted, API defaults to 100 (2\xD7 ATH)."
+                  })
+                )
+              }),
+              {
+                minItems: 1,
+                maxItems: 5,
+                description: "Ordered trailing-stop levels (up to 5)."
+              }
+            )
+          })
+        ),
         managementMode: Type.Optional(
           Type.Union([Type.Literal("LOCAL_MANAGED"), Type.Literal("SERVER_MANAGED")], {
             description: "Advisory only \u2014 server decides position mode internally. Sent for future compatibility."
@@ -1337,9 +1391,14 @@ var solanaTraderPlugin = {
           symbol: params.symbol,
           slippageBps: params.slippageBps,
           slPct: params.slPct,
-          trailingStopPct: params.trailingStopPct,
           managementMode: params.managementMode
         };
+        const tsExecute = params.trailingStop;
+        if (tsExecute?.levels && Array.isArray(tsExecute.levels) && tsExecute.levels.length > 0) {
+          body.trailingStop = tsExecute;
+        } else if (params.trailingStopPct !== void 0) {
+          body.trailingStopPct = params.trailingStopPct;
+        }
         if (params.side === "buy") {
           body.sizeSol = params.sizeSol;
         } else {
@@ -1507,7 +1566,7 @@ var solanaTraderPlugin = {
     });
     api.registerTool({
       name: "solana_capital_status",
-      description: "Get your current capital status \u2014 SOL balance, open position count, unrealized PnL, daily notional used, daily loss, and effective limits (adjusted by entitlements).",
+      description: "Get your current capital status \u2014 SOL balance, open position count, unrealized/realized PnL, daily notional used, daily loss, and effective limits. **PnL:** `totalUnrealizedPnl` / `totalRealizedPnl` are USD (DB); use `totalUnrealizedPnlSol` / `totalRealizedPnlSol` / `totalPnlSol` for SOL (derived via `solPriceUsd`, same as positions API).",
       parameters: Type.Object({}),
       execute: wrapExecute(
         async () => get(`/api/capital/status?walletId=${walletId}`)
@@ -1515,7 +1574,7 @@ var solanaTraderPlugin = {
     });
     api.registerTool({
       name: "solana_positions",
-      description: "List your current trading positions with unrealized PnL, entry price, current price, stop-loss/take-profit settings, and management mode. Call at the START of every trading cycle for interrupt check. Also use to detect dead money (flat positions).",
+      description: "List trading positions with mark-to-market. **PnL:** `realizedPnl` / `unrealizedPnl` are USD as stored; prefer `realizedPnlSol` / `unrealizedPnlSol` when reasoning in SOL. `unrealizedReturnPct` is ROI on cost basis (for sweep-dead-tokens logic). See response `pnlNote`.",
       parameters: Type.Object({
         status: Type.Optional(Type.String({ description: "Filter by status: 'open', 'closed', or omit for all" }))
       }),
@@ -1525,6 +1584,38 @@ var solanaTraderPlugin = {
         return get(path2);
       })
     });
+    api.registerTool({
+      name: "solana_wallet_token_balance",
+      description: "Read on-chain SPL token balance (UI amount) for your trading wallet and a token mint. Same balance path as server exit monitoring (`balanceOf`).",
+      parameters: Type.Object({
+        tokenAddress: Type.String({ description: "SPL token mint address" })
+      }),
+      execute: wrapExecute(
+        async (_id, params) => post("/api/wallet/token-balance", {
+          walletId,
+          tokenAddress: params.tokenAddress
+        })
+      )
+    });
+    api.registerTool({
+      name: "solana_sweep_dead_tokens",
+      description: "Sell 100% of each OPEN position whose unrealizedReturnPct is \u2264 -maxLossPct (default 80), using the same mark-to-market as positions. Use dryRun:true first to list candidates. Executes sequential full exits (sellPct 100). Requires trade:execute scope.",
+      parameters: Type.Object({
+        maxLossPct: Type.Optional(
+          Type.Number({ description: "Threshold: sweep when unrealizedReturnPct <= -maxLossPct (default 80)" })
+        ),
+        slippageBps: Type.Optional(Type.Number({ description: "Per-exit slippage in bps (default 300)" })),
+        dryRun: Type.Optional(Type.Boolean({ description: "If true, only return candidate tokens without selling" }))
+      }),
+      execute: wrapExecute(
+        async (_id, params) => post("/api/wallet/sweep-dead-tokens", {
+          walletId,
+          maxLossPct: params.maxLossPct,
+          slippageBps: params.slippageBps,
+          dryRun: params.dryRun
+        })
+      )
+    });
     api.registerTool({
       name: "solana_funding_instructions",
       description: "Get deposit instructions for funding your trading wallet with SOL.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solana-traderclaw",
-  "version": "1.0.36",
+  "version": "1.0.37",
   "description": "TraderClaw V1 — autonomous Solana memecoin trading for OpenClaw (team edition: X/Twitter journal and engagement tools)",
   "type": "module",
   "main": "./dist/index.js",

package/skills/solana-trader/SKILL.md

@@ -14,7 +14,7 @@ The orchestrator gathers data, enforces execution policy, applies entitlement li
 
 ## How You Access the Orchestrator
 
-You interact with the orchestrator **exclusively through plugin tools** (e.g. `solana_system_status`, `solana_scan`, `solana_alpha_signals`, `solana_trade`, etc.). You have no other access method.
+You interact with the orchestrator **exclusively through plugin tools** (e.g. `solana_system_status`, `solana_scan_hot_pairs`,`solana_scan_launches` , `solana_alpha_signals`, `solana_trade_precheck`, `solana_trade_execute`, etc.). You have no other access method.
 
 **Critical rules:**
 - **You do NOT have direct HTTP/API access.** Never attempt to call REST endpoints, use curl/fetch, or construct API URLs. You cannot reach the orchestrator that way.
@@ -234,8 +234,14 @@ All values are internal targets that must still comply with server policy caps.
 | Position size (exploratory) | 3–8% of capital | 5–10% of capital |
 | Max correlated cluster exposure | 40% of capital | 40% of capital |
 | Consecutive losses → kill switch | 5 | 7 |
-| Rapid drawdown defense trigger | -20% on any position | -15% on any position |
-| Partial profit trigger | +40–60% (optional) | +25–50% (take partial quickly) |
+| Stop loss (slExits) | -20% on every position | -40% on every position |
+| Trailing Stop loss ("trailingStop": {
+      "levels": [
+        { "percentage": 25, "amount": 50 },
+        { "percentage": 35, "amount": 100, "triggerAboveATH": 100 }
+      ]
+    }) where percent is the price decrease from entry price and amount is the size of position in percentage and in token holding  | -20% on every position and optional triggerAboveATH | -40% on every position |
+| Multiple Take Profit exits (tpExits) (e.g [{"percent": 100, "amountPct": 30},{ "percent": 200, "amountPct": 100" }], where percent is the price increase from entry price and amountPct is the size of position in percentage and in token holding) | +100–300% (multiple) | +200–500% (multiple) |
 | Exploration ratio | 20% experimental / 80% proven | 50% experimental / 50% proven |
 | Weight evolution (minimum trades) | ≥20 closed trades | ≥20 closed trades |
 | Max weight delta per update | ±0.10 | ±0.15 |
@@ -330,7 +336,7 @@ There is no context loss from this separation. Cron outputs flow into the persis
        ↓
 2. Step 0: INTERRUPT CHECK — identify wake-up trigger, check kill switch, check dead money, STRATEGY INTEGRITY CHECK
        ↓
-3. Step 1: SCAN — call solana_scan for broad discovery, process Bitquery subscriptions
+3. Step 1: SCAN — call solana_scan_launches and solana_scan_hot_pairs for broad discovery, process Bitquery subscriptions
        ↓
 4. Step 1.5b: ALPHA SIGNALS — poll solana_alpha_signals, score, classify priority
        ↓
@@ -902,10 +908,6 @@ Discovery subscriptions complement — not replace — scan endpoints and alpha
 
 When multiple paths independently surface the same token = convergence = highest conviction. Log convergence events via `solana_memory_write` with tag `signal_convergence`.
 
-**Future enhancement (not yet available):**
-
-When `solana_firehose_config` and `solana_firehose_status` tools become available, you will be able to configure advanced filter parameters (volume thresholds, buyer counts, whale detection) directly on the orchestrator or local worker, and check health/stats. For now, use the existing `solana_bitquery_subscribe` with the available template keys and evolve your subscription strategy based on outcomes.
-
 ---
 
 ### Step 2: ANALYZE — Deep Dive
@@ -1128,9 +1130,11 @@ If BUY, you must define before executing:
 - `tpLevels` — staged take-profit levels as percentages
   - HARDENED: `[50, 100, 200]` (patient, ride trends)
   - DEGEN: `[25, 50, 100]` (lock gains faster)
-- `trailingStopPct` — trailing stop activation
-  - HARDENED: 12–18%
-  - DEGEN: 8–15%
+- `trailingStopPct` — single trailing stop (% drawdown from session high once active). Legacy/simple path on the server.
+- **`trailingStop`** (preferred for staging) — `{ levels: [ ... ] }` with **1–5** levels. Each level:
+  - `percentage` — trailing drawdown % from the armed high once that level is active (required).
+  - `amount` — % of position to sell at this level (1–100; server default **100**).
+  - `triggerAboveATH` — **optional.** Price must reach this **% above the session ATH** before this level arms (e.g. `50` → 1.5× ATH). **If omitted, the API defaults to `100` (2× ATH).** Use a smaller value (e.g. `25`) to arm earlier; use `trailingStopPct` instead if you want the simpler single-level trailing that keys off ATH without this gate.
 - `managementMode` — LOCAL_MANAGED or SERVER_MANAGED
 - `slippageBps` — must scale with liquidity:
   - Pool depth > $500K: 100–200 bps
@@ -1227,7 +1231,7 @@ Call `solana_trade_execute` with:
 - **For buy:** `sizeSol` (amount in SOL to spend) — required
 - **For sell:** `sellPct` (percentage of position to sell, 1–100 where 100 = full exit) **or** `sizeTokens` (exact token count) — one is required. If both sent, `sellPct` wins. Do NOT send `sizeSol` for sells.
 - `slippageBps` (scaled to liquidity as defined in your exit plan — hard cap 800bps)
-- `slPct`, `tpLevels`, `trailingStopPct`
+- `slPct`, `tpLevels`, **`trailingStopPct` and/or `trailingStop`** (see **Define Exit Plan** above — if both are sent, `trailingStop` wins)
 - `managementMode`
 
 Record the returned `tradeId` and `positionId`. You will need these for monitoring and review.
@@ -1669,7 +1673,6 @@ Your discovery subscriptions (Step 1.75) should evolve alongside your strategy w
    - **Adjusting discovery subscriptions** (broad, for token detection):
      Discovery subscriptions like `pumpFunTokenCreation` and `raydiumNewPools` are fire-and-forget — you set them up once and they run until you unsubscribe. Evolution here means deciding which broad subscriptions to keep vs remove, not changing their parameters.
    
-   When `solana_firehose_config` becomes available, you will be able to configure advanced filter parameters (volume thresholds, buyer counts, whale detection) on the orchestrator or local worker side without the unsub/resub cycle.
 
 5. Mode switches should trigger subscription review:
    - Switching to DEGEN → add more discovery subscriptions, broaden parameters
@@ -2064,8 +2067,10 @@ All authenticated endpoints use `Authorization: Bearer <accessToken>`.
 | `POST` | `/api/session/logout` | `refreshToken` | No auth needed. Revokes session |
 | `GET` | `/api/wallets` | — | List all wallets. Optional `?refresh=true` |
 | `POST` | `/api/wallet/create` | — | Create wallet. Optional: `label`, `publicKey`, `chain` (solana/bsc), `ownerRef`, `includePrivateKey`. Status `201` |
-| `GET` | `/api/capital/status` | `?walletId=<uuid>` | Wallet capital and daily limits |
-| `GET` | `/api/wallet/positions` | `?walletId=<uuid>` | Open positions. Optional `?status=` |
+| `GET` | `/api/capital/status` | `?walletId=<uuid>` | Wallet capital and daily limits. **PnL:** `totalUnrealizedPnl` / `totalRealizedPnl` are **USD** (stored); `totalUnrealizedPnlSol` / `totalRealizedPnlSol` / `totalPnlSol` are **SOL** derived with `solPriceUsd` (agent-safe). |
+| `GET` | `/api/wallet/positions` | `?walletId=<uuid>` | Positions. **`realizedPnl` / `unrealizedPnl` = USD** in DB; use **`realizedPnlSol` / `unrealizedPnlSol`** for SOL. `unrealizedReturnPct` = ROI vs cost (for sweep). |
+| `POST` | `/api/wallet/token-balance` | `walletId`, `tokenAddress` | On-chain SPL **uiAmount** for the wallet (same as server `balanceOf`) |
+| `POST` | `/api/wallet/sweep-dead-tokens` | `walletId` | Optional: `maxLossPct` (default **80**), `slippageBps`, `dryRun`. Sells **100%** of each **open** position with `unrealizedReturnPct` ≤ **-maxLossPct**. **trade:execute** scope. |
 | `GET` | `/api/funding/instructions` | `?walletId=<uuid>` | Deposit instructions |
 | `GET` | `/api/killswitch/status` | `?walletId=<uuid>` | Kill switch state |
 | `POST` | `/api/killswitch` | `walletId`, `enabled` | Toggle kill switch. Optional: `mode` (TRADES_ONLY / TRADES_AND_STREAMS). **Pro tier required** |
@@ -2073,7 +2078,7 @@ All authenticated endpoints use `Authorization: Bearer <accessToken>`.
 | `POST` | `/api/strategy/update` | `walletId`, `featureWeights` | Update weights. Optional: `strategyVersion`, `mode` (HARDENED/DEGEN) |
 | `POST` | `/api/thesis/build` | `walletId`, `tokenAddress` | Build full thesis package |
 | `POST` | `/api/trade/precheck` | `walletId`, `tokenAddress`, `side` (buy/sell), `slippageBps`. Buy: `sizeSol`. Sell: `sellPct` or `sizeTokens` | Risk/policy check, no execution |
-| `POST` | `/api/trade/execute` | `walletId`, `tokenAddress`, `side`, `slippageBps`. Buy: `sizeSol`. Sell: `sellPct` or `sizeTokens` | Execute trade. Optional: `symbol`, `tpLevels[]`, `slPct`, `trailingStopPct`. Header: `x-idempotency-key` |
+| `POST` | `/api/trade/execute` | `walletId`, `tokenAddress`, `side`, `slippageBps`. Buy: `sizeSol`. Sell: `sellPct` or `sizeTokens` | Execute trade. Optional: `symbol`, `tpLevels[]`, `slPct`, `trailingStopPct`, `trailingStop: { levels: [{ percentage, amount?, triggerAboveATH? }] }` (1–5 levels; **omitted `triggerAboveATH` defaults to 100** = 2× ATH). Header: `x-idempotency-key` |
 | `POST` | `/api/trade/review` | `walletId`, `outcome` (win/loss/neutral), `notes` | Post-trade review. Optional: `tradeId`, `tokenAddress`, `pnlSol`, `tags[]`, `strategyVersion` (strict semver). Status `201` |
 | `POST` | `/api/memory/write` | `walletId`, `notes` | Journal entry. Optional: `tokenAddress`, `outcome` (win/loss/neutral), `tags[]`, `strategyVersion` (strict semver). Status `201` |
 | `POST` | `/api/memory/search` | `walletId`, `query` | Search memory entries |
@@ -2701,8 +2706,10 @@ Each user configures their own X/Twitter API developer account tokens in the plu
 | Thesis | `solana_build_thesis` | Full context package |
 | Trade | `solana_trade_precheck` | Pre-trade risk validation |
 | Trade | `solana_trade_execute` | Execute trade |
-| Monitor | `solana_positions` | Position tracking |
-| Monitor | `solana_capital_status` | Portfolio status |
+| Monitor | `solana_positions` | Position tracking (USD PnL in DB; use `*PnlSol` fields for SOL) |
+| Monitor | `solana_capital_status` | Portfolio status (same USD vs SOL split as API) |
+| Risk | `solana_sweep_dead_tokens` | Full-exit open positions below **-maxLossPct** ROI (default 80%); use `dryRun` first |
+| Wallet | `solana_wallet_token_balance` | On-chain SPL balance for a mint |
 | Review | `solana_trade_review` | Post-trade review |
 | Memory | `solana_memory_write` | Write journal entry (deployer profiles, filter evolution, convergence) |
 | Memory | `solana_memory_search` | Search memories (check deployer history before profiling) |