solana-trader (TraderClaw V1)

TraderClaw V1 plugin for autonomous Solana memecoin trading. Connects OpenClaw to a trading orchestrator that handles market data, risk enforcement, and trade execution. Includes a full memory layer with local persistence, episodic logging, deterministic compute tools, and OpenClaw-native memory integration.

Architecture

OpenClaw Agent (brain: reasoning, decisions, strategy evolution)
       │
       │ calls 66 typed tools
       ▼
Plugin (this package)
  ├── HTTP ──→ Orchestrator (data + risk + execution)
  │                  │              │
  │              Bitquery        SpyFly Bot
  │              (market data)   (on-chain execution)
  │
  ├── Local persistence (state, decisions, bulletin, patterns)
  │     └── .traderclaw-v1-data/
  │
  └── OpenClaw native memory (auto-loaded every session)
        ├── MEMORY.md (durable facts — always in context)
        └── memory/YYYY-MM-DD.md (daily logs — today + yesterday)

The plugin gives OpenClaw tools to interact with the Solana trading orchestrator. The orchestrator gathers market data, enforces risk rules, and proxies trades. OpenClaw does all reasoning, decision-making, and strategy evolution. The plugin also manages a 3-layer memory system that eliminates amnesia between sessions.

Prerequisites

• OpenClaw v2026.1+ with Node >= 22
• An API key from traderclaw.ai/register

Quick Start

1. Install the plugin

The npm package name and OpenClaw plugin id are both solana-trader (so OpenClaw does not warn about id vs package mismatch). The global CLI binary is traderclaw.

npm install -g [email protected]

Or install directly into OpenClaw:

openclaw plugins install [email protected]

The previous npm name solana-traderclaw-v1 is retired; use solana-trader for new installs. Existing installs can npm install -g solana-trader@latest after you publish.

2. Run setup

traderclaw setup

The setup wizard will:

• Ask for your API key (from traderclaw.ai/register)
• Connect to the orchestrator and validate your key
• Create or select a trading wallet
• Write the plugin configuration automatically

That's it. Restart the gateway and start trading:

openclaw gateway restart

Optional: Simple localhost installer wizard (Linux-first)

traderclaw install --wizard

This opens a localhost UI that runs prechecks, lane-aware setup, gateway validation, optional Telegram setup, and final verification. It also installs HEARTBEAT.md into your OpenClaw agent workspace root (default ~/.openclaw/workspace/HEARTBEAT.md) from the packaged skill so heartbeats load the TraderClaw checklist without manual cp. traderclaw setup does the same.

Optional: Run CLI prechecks directly

traderclaw precheck --dry-run --output linux-qa-dryrun.log
traderclaw precheck --allow-install --output linux-qa-install.log

Use --dry-run for non-mutating validation and --allow-install for guided dependency installs.

3. Run the mandatory startup sequence

Send this prompt to your bot after startup:

Run mandatory startup sequence and report pass/fail for each:
1) solana_system_status
2) solana_gateway_credentials_get (set if missing)
3) solana_alpha_subscribe(agentId: "main")
4) solana_capital_status
5) solana_positions
6) solana_killswitch_status

Non-interactive setup

traderclaw setup --api-key sk_live_abc123 --url https://api.traderclaw.ai

CLI Commands

traderclaw setup

Interactive setup wizard. Validates API key, connects to orchestrator, sets up wallet, writes config.

Options:

• --api-key, -k — API key (skip prompt)
• --url, -u — Orchestrator URL (skip prompt, default: https://api.traderclaw.ai)

traderclaw status

Check connection health and wallet status at a glance:

OpenClaw Solana Trader - Status
=============================================
  Orchestrator:     CONNECTED
  Execution mode:   live
  Upstream:         configured
  System status:    OK
  WS connections:   1

  Wallet:           ACTIVE
  Wallet ID:        1
  Balance:          5.0 SOL
  Open positions:   3
  Unrealized PnL:   0.062 SOL
  Kill switch:      disabled
  Strategy version: v1.2.3
  Mode:             HARDENED
=============================================

traderclaw config

View and manage configuration:

traderclaw config show          # View current config (API key masked)
traderclaw config set <key> <v> # Update a value
traderclaw config reset         # Remove all plugin config

Available config keys: orchestratorUrl, walletId, apiKey, apiTimeout, refreshToken, walletPublicKey, gatewayBaseUrl, gatewayToken, agentId

Wallet proof note: if login/session challenge requires wallet ownership proof, provide the key at runtime with --wallet-private-key or TRADERCLAW_WALLET_PRIVATE_KEY. It is used for local signing only and is not stored in ~/.openclaw/openclaw.json.

Gateway process: Telegram and other channels talk to the OpenClaw gateway process. That process must be able to read TRADERCLAW_WALLET_PRIVATE_KEY when the session refresh fails and a new challenge runs. Exporting the variable only in your SSH session does not set it for systemd (or Docker, etc.). Configure it in the gateway unit’s environment per the troubleshooting guide below.

traderclaw login: Uses the saved refresh token when valid (no wallet key needed). Use traderclaw login --force-reauth when you intentionally want a full API challenge (e.g. after traderclaw logout).

Session / auth / startup issues: follow the official guide — Installation → Troubleshooting (session expired, auth, logged out).

traderclaw --help

Print all available commands and options.

traderclaw --version

Print plugin version.

Advanced: Manual Configuration

If you prefer to configure manually instead of using the CLI, add to ~/.openclaw/openclaw.json:

{
  plugins: {
    entries: {
      "solana-trader": {
        enabled: true,
        config: {
          orchestratorUrl: "https://api.traderclaw.ai",
          walletId: 1,
          apiKey: "sk_live_your_key_here",
          apiTimeout: 80000,  // optional, default 80s
          dataDir: "/path/to/data"  // optional, default: <cwd>/.traderclaw-v1-data
        }
      }
    }
  }
}

Restart the gateway after configuration:

openclaw gateway restart

Memory & Context System

The plugin implements a 3-layer memory architecture that uses OpenClaw's native infrastructure plus custom tools to eliminate amnesia between sessions.

Layer 1: Durable Facts (MEMORY.md)

OpenClaw automatically loads MEMORY.md into agent context at every session start — zero tool calls needed. When solana_state_save is called, it writes both a JSON state file AND updates MEMORY.md with curated durable facts: tier, wallet, mode, strategy version, watchlist, permanent learnings, and regime canary.

Layer 2: Episodic Memory (Daily Logs + Bootstrap Injection)

Two auto-loaded sources:

• Daily logs (memory/YYYY-MM-DD.md) — OpenClaw auto-loads today + yesterday's files. Written via solana_daily_log.
• Bootstrap injection — The agent:bootstrap hook auto-injects durable state, last 50 decisions, team bulletin (last 6h), context snapshot, and entitlements into agent context at session start.

Layer 3: Deep Knowledge (Server-Side Memory)

Unlimited retention via the orchestrator API. solana_memory_write / solana_memory_search / solana_memory_by_token for storing and retrieving historical trades, lessons, and patterns.

Memory Flush Hook

The memory:flush hook fires automatically when OpenClaw is about to trim context. It syncs MEMORY.md from the last persisted state and writes a compaction marker to the daily log. This is an automatic safety net — no agent action needed.

Bootstrap Hook (agent:bootstrap)

Fires at every agent session start before the first prompt. Injects via context.bootstrapFiles:

| File Injected | Source | Content | |---|---|---| | <agentId>-durable-state.json | state/<agentId>.json | Full durable state from last session | | <agentId>-decision-log.jsonl | logs/<agentId>/decisions.jsonl | Last 50 decision log entries | | team-bulletin.jsonl | logs/shared/team-bulletin.jsonl | Bulletin entries from last 6 hours | | context-snapshot.json | state/context-snapshot.json | Latest portfolio world-view snapshot | | active-entitlements.json | 4-step fallback chain | Entitlement tier, limits, expiration |

Entitlement fallback chain: live API fetch → cached file → durable state → conservative defaults (starter tier).

Local Data Directory

.traderclaw-v1-data/
├── state/                  # Durable agent state, snapshot, entitlement cache, patterns
├── logs/
│   ├── <agentId>/          # Per-agent decision logs (JSONL)
│   └── shared/             # Team bulletin (JSONL)

Plus OpenClaw-native paths at project root:

MEMORY.md                   # Curated durable facts (auto-loaded by OpenClaw)
memory/
├── 2026-03-19.md           # Today's daily log (auto-loaded by OpenClaw)
├── 2026-03-18.md           # Yesterday's daily log (auto-loaded by OpenClaw)
└── ...                     # Auto-pruned after 7 days

Available Tools (66)

Scanning

| Tool | Description | |------|-------------| | solana_scan_launches | Find new Solana token launches | | solana_scan_hot_pairs | Find high-volume trading pairs | | solana_market_regime | Get macro market state (bullish/bearish/neutral) |

Token Analysis

| Tool | Description | |------|-------------| | solana_token_snapshot | Price, volume, OHLC data | | solana_token_holders | Holder concentration and distribution | | solana_token_flows | Buy/sell pressure and flow data | | solana_token_liquidity | Pool depth and liquidity profile | | solana_token_risk | Composite risk assessment |

Intelligence

| Tool | Description | |------|-------------| | solana_build_thesis | Full context package: market data + strategy weights + memory + risk pre-screen |

Trading

| Tool | Description | |------|-------------| | solana_trade_precheck | Pre-trade risk validation | | solana_trade_execute | Execute trade via SpyFly bot |

Reflection & Server-Side Memory

| Tool | Description | |------|-------------| | solana_trade_review | Post-trade outcome review | | solana_memory_write | Write journal entry to server | | solana_memory_search | Search trading memories on server | | solana_memory_by_token | Token-specific trade history from server | | solana_journal_summary | Performance stats summary |

Strategy

| Tool | Description | |------|-------------| | solana_strategy_state | Read current strategy weights | | solana_strategy_update | Update weights after learning |

Safety

| Tool | Description | |------|-------------| | solana_killswitch | Toggle emergency kill switch | | solana_killswitch_status | Check kill switch state |

Wallet

| Tool | Description | |------|-------------| | solana_capital_status | Balance, positions, PnL, limits | | solana_positions | Current positions with PnL | | solana_funding_instructions | Deposit instructions | | solana_wallets | List all wallets | | solana_wallet_create | Create a new wallet |

Entitlements

| Tool | Description | |------|-------------| | solana_entitlement_plans | Available limit upgrades | | solana_entitlement_purchase | Purchase upgrade plan | | solana_entitlement_current | Current tier, limits, and expiration (also caches for bootstrap) | | solana_entitlement_upgrade | Upgrade entitlement tier | | solana_entitlement_costs | View upgrade cost breakdown |

Trade History & Risk

| Tool | Description | |------|-------------| | solana_trades | Query trade history with filters | | solana_risk_denials | View recent risk denial log |

Alpha Signal Processing

| Tool | Description | |------|-------------| | solana_alpha_subscribe | Subscribe to alpha signal WebSocket feed | | solana_alpha_unsubscribe | Unsubscribe from alpha feed | | solana_alpha_signals | Retrieve buffered alpha signals | | solana_alpha_history | Query historical alpha signals | | solana_alpha_sources | Get source reputation statistics |

Bitquery Deep Scans

| Tool | Description | |------|-------------| | solana_bitquery_query | Execute custom Bitquery GraphQL query | | solana_bitquery_catalog | List available Bitquery datasets | | solana_bitquery_templates | Pre-built query templates | | solana_bitquery_subscribe | Create Bitquery streaming subscription | | solana_bitquery_unsubscribe | Remove streaming subscription | | solana_bitquery_subscriptions | List active subscriptions | | solana_bitquery_subscription_reopen | Reopen a closed subscription |

Gateway & System

| Tool | Description | |------|-------------| | solana_system_status | Orchestrator health check | | solana_gateway_credentials_get | Get gateway API credentials | | solana_gateway_credentials_set | Set gateway API credentials | | solana_gateway_credentials_delete | Delete gateway credentials | | solana_gateway_forward_probe | Probe gateway forwarding connectivity | | solana_agent_sessions | View agent session diagnostics | | solana_startup_gate | Run startup gate sequence (includes welcomeMessage on full pass; may include it if only capital step fails — see tool output) | | solana_traderclaw_welcome | Post-startup welcome for the user (includes API key when in config) | | solana_runtime_status | Get runtime status diagnostics |

Local Durable State

| Tool | Description | |------|-------------| | solana_state_save | Save agent state to local JSON (also writes MEMORY.md) | | solana_state_read | Read agent state from local JSON |

Episodic Decision Log

| Tool | Description | |------|-------------| | solana_decision_log | Log structured decision entry (FIFO capped at 50) |

Team Bulletin

| Tool | Description | |------|-------------| | solana_team_bulletin_post | Post discovery, alert, or status to shared bulletin | | solana_team_bulletin_read | Read bulletin entries with time/type filters |

Context Snapshot

| Tool | Description | |------|-------------| | solana_context_snapshot_write | Write portfolio world-view snapshot | | solana_context_snapshot_read | Read latest portfolio snapshot |

Deterministic Compute (Anti-Hallucination)

| Tool | Description | |------|-------------| | solana_compute_confidence | Weighted confidence score (on-chain, signal, social, smart money, risk penalty) | | solana_compute_freshness_decay | Freshness decay factor by signal age | | solana_compute_position_limits | Full position sizing ladder with reduction breakdown | | solana_classify_deployer_risk | Deployer wallet risk classification (LOW/MODERATE/HIGH/CRITICAL) |

Deep Analysis

| Tool | Description | |------|-------------| | solana_history_export | Export decision logs + optionally server-side data (trades, memory, strategy) | | solana_pattern_store | Read/write/list named trading patterns |

OpenClaw Native Memory

| Tool | Description | |------|-------------| | solana_daily_log | Append to today's daily log (auto-loaded by OpenClaw next session, 7-day prune) |

Hooks (2)

| Hook | Trigger | What It Does | |------|---------|--------------| | agent:bootstrap | Every session start | Injects durable state, decisions, bulletin, snapshot, and entitlements into context | | memory:flush | Before OpenClaw context compaction | Syncs MEMORY.md from persisted state, writes compaction marker to daily log |

Skills

solana-trader (Trading Skill v5)

The primary skill that teaches OpenClaw the complete trading lifecycle:

1. SCAN — Find opportunities with launch/hot-pair scanners
2. ANALYZE — Deep dive with 5 token analysis tools
3. THESIS — Assemble full context with build_thesis
4. DECIDE — Agent reasons over data using confidence scoring
5. PRECHECK — Validate against risk rules
6. EXECUTE — Place trade via SpyFly
7. MONITOR — Watch positions and capital
8. REVIEW — Journal outcomes honestly
9. EVOLVE — Update strategy weights based on performance

Includes: token lifecycle framework, anti-rug heuristics, volume pattern reading, FOMO detection, liquidity-relative sizing, house money exits, dead money rule, narrative awareness, 3-layer memory architecture, deterministic compute tools.

social-intel (Alpha Feed & Social Intelligence)

Standalone skill for SpyFly alpha feed integration and social intelligence:

• SpyFly Alpha Feed — Query recent alpha calls, historical accuracy, price milestone pings
• Token Social Metadata — Resolve on-chain metadata to find Twitter/Telegram/Discord links
• Twitter Community Stats — Follower count, engagement, growth trajectory, MC-relative benchmarking
• Twitter Trending — Narrative/meta detection from viral crypto topics

This skill is designed to merge into the trading skill when both are ready.

Example Conversation

User: Start scanning for opportunities

Agent: Let me check the current market conditions and scan for new tokens.

[calls solana_market_regime]
Market is in a bullish regime with high DEX volume.

[calls solana_scan_launches]
Found 5 new launches in the last hour. POPCAT at 0x7a... looks interesting — high initial volume.

[calls solana_build_thesis with POPCAT address]
Thesis package shows:
- Strong buy pressure (68% buy ratio)
- Adequate liquidity ($180k)
- Holder concentration at 35% (acceptable)
- My strategy weights favor volume_momentum (0.28) — this token scores well there
- No prior trades on this token in my memory
- Risk pre-screen: approved, capped at 0.5 SOL

Based on the thesis data and my learned weights, I'll enter a small position.

[calls solana_trade_precheck]
Approved. Capped size: 0.5 SOL.

[calls solana_trade_execute]
Trade executed. TradeId: 15, PositionId: 4, TX: 5xK...

I'll monitor this position and review after exit.

Troubleshooting

Plugin won't load:

• Run traderclaw status to check connectivity
• Check openclaw plugins list for errors
• Verify openclaw.plugin.json exists in the plugin directory

"apiKey is required" error:

• Run traderclaw setup to configure your API key
• Or manually add apiKey to your config: traderclaw config set apiKey sk_live_...

"Could not reach orchestrator" warning:

• Run traderclaw status to diagnose
• Check your internet connection
• Verify the orchestrator URL: traderclaw config show

"Wallet not found" errors:

• Run traderclaw setup to create or select a wallet
• Verify the wallet ID: traderclaw config show

Heartbeat not sending messages to Telegram:

• Fresh traderclaw setup: the installer runs configureGatewayScheduling, which sets a custom heartbeat.prompt on the main agent (no HEARTBEAT_OK escape). You only need the manual openclaw config set command below if you are on an older install or overwrote agents.list.
• HEARTBEAT.md must live in the agent workspace root (default ~/.openclaw/workspace/HEARTBEAT.md, next to AGENTS.md). A copy under workspace/.openclaw/ or only inside the plugin package is not loaded as the heartbeat checklist. Copy from skills/solana-trader/HEARTBEAT.md in the installed package if needed. See OpenClaw agent workspace.
• OpenClaw's default heartbeat prompt tells the model "If nothing needs attention, reply HEARTBEAT_OK" — which is stripped and never delivered. Run traderclaw setup again (v1.0.16+) to set a custom prompt, or apply manually:

openclaw config set agents.list '[{"id":"main","default":true,"heartbeat":{"every":"30m","target":"last","prompt":"Read HEARTBEAT.md (workspace context). Follow it strictly — execute the full trading cycle and report results to the user. Do NOT reply HEARTBEAT_OK. Always produce a visible summary of what you checked and did."}}]'
openclaw gateway restart

• Verify with openclaw config get agents — the main agent should have a heartbeat.prompt field.
• Confirm Telegram is healthy: openclaw channels status --probe
• You must have messaged the bot at least once for target: "last" to have a delivery route.

Scheduled cron jobs run but you never see Telegram/WhatsApp output:

• TraderClaw templates merged into ~/.openclaw/cron/jobs.json use delivery.mode: "announce" with channel: "last" so each completed isolated job posts a summary to the same channel you last used (see OpenClaw cron delivery).
• If you installed before this behavior: run traderclaw setup again so the installer re-merges cron jobs, or stop the gateway and edit managed job entries in ~/.openclaw/cron/jobs.json — set delivery to { "mode": "announce", "channel": "last", "bestEffort": true } for each TraderClaw job (or remove delivery entirely; isolated jobs default to announce when omitted).
• The same last requirement as heartbeat applies: message the bot at least once so the gateway knows where to deliver.

Tools returning errors:

• Run traderclaw status to check system health
• Check if kill switch is enabled
• Verify your wallet has sufficient SOL balance

Memory/state not persisting:

• Check that the dataDir config points to a writable location
• Default is <cwd>/.traderclaw-v1-data — verify permissions
• Check MEMORY.md exists at project root after first solana_state_save call
• Check memory/ directory for daily log files