solana-traderclaw (Public V1)

Public release of TraderClaw’s Solana trading skill — built on the OpenClaw framework.

This is the open execution layer of an autonomous trading system: a composable, agent-driven architecture wired directly into server-side tooling for market data, execution, risk enforcement, deterministic compute, memory, episodic logging, and intelligence workflows.

At its core, this repository exposes a fully operational trading framework with 97 integrated tools spanning the entire lifecycle of Solana memecoin trading — from discovery to execution to risk management and post-trade evaluation.

TraderClaw is evolving toward a multi-agent trading desk architecture, where specialized agents operate across strategy, execution, token discovery, social intelligence, smart money tracking, and adaptive learning.

This release gives builders direct access to the underlying system primitives — and the ability to build, extend, and deploy their own agentic trading logic on top of the OpenClaw stack.

Architecture

OpenClaw Agent (brain: reasoning, decisions, strategy evolution)
       │
       │ calls 97 typed tools (94 trading + 3 X read-only)
       ▼
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/   (or explicit plugins.entries.solana-trader.config.dataDir)
  │
  └── 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 (OpenClaw)

openclaw plugins install solana-traderclaw

The solana-traderclaw tarball is the plugin only (no global traderclaw binary), so OpenClaw’s install scanner stays clean.

2. Install the global CLI (optional)

For traderclaw --version, traderclaw install --wizard, traderclaw setup, etc., install the companion package (it depends on solana-traderclaw and wires paths correctly):

npm install -g traderclaw-cli

That publishes the command name traderclaw on your PATH. From a git checkout you can also run node bin/traderclaw.cjs … at the repo root.

Install name and config id are intentionally different:

• npm plugin package: solana-traderclaw
• global CLI package: traderclaw-cli (command: traderclaw)
• OpenClaw plugin id in openclaw.json: solana-trader
• OpenClaw allowlist entry: plugins.allow: ["solana-trader"]

3. 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.

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.

4. 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

If alpha signals stop but the gateway looks healthy, call solana_alpha_subscribe({ force: true }) or inspect solana_runtime_status (alpha stats.lastEventTs, subscribed). The plugin also runs a background watchdog for stale ingestion and gateway forward probes.

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, recoverySecret, walletPublicKey, walletPrivateKey, gatewayBaseUrl, gatewayToken, agentId

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: {
    allow: ["solana-trader"],
    entries: {
      "solana-trader": {
        enabled: true,
        config: {
          orchestratorUrl: "https://api.traderclaw.ai",
          walletId: 1,
          apiKey: "sk_live_your_key_here",
          apiTimeout: 30000,  // optional, default 30s
          dataDir: "/path/to/data"  // optional, default: ~/.traderclaw-v1-data; VPS: set explicit absolute path
        }
      }
    }
  }
}

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:

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

Local Data Directory

Default location is ~/.traderclaw-v1-data when dataDir is not set in openclaw.json (older releases used <cwd>/.traderclaw-v1-data). For production/VPS hosts, set plugins.entries.solana-trader.config.dataDir to an absolute path so the CLI and OpenClaw gateway always share the same session sidecar.

~/.traderclaw-v1-data/   (or your explicit dataDir)
├── 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

X/Twitter Setup (Read-Only Social Intel)

The public edition includes 3 read-only X/Twitter tools for social intelligence gathering (search tweets, read mentions, get threads). X posting is not included in the public edition.

Configure via Environment Variables

export X_CONSUMER_KEY="your-app-consumer-key"
export X_CONSUMER_SECRET="your-app-consumer-secret"
export X_ACCESS_TOKEN_MAIN="your-access-token"
export X_ACCESS_TOKEN_MAIN_SECRET="your-access-token-secret"

Or Configure via Plugin Config

Add to ~/.openclaw/openclaw.json under the plugin entry:

{
  "x": {
    "consumerKey": "your-app-consumer-key",
    "consumerSecret": "your-app-consumer-secret",
    "profiles": {
      "main": {
        "accessToken": "your-access-token",
        "accessTokenSecret": "your-access-token-secret"
      }
    }
  }
}

X API Tiers

Pay-as-you-go or Basic tier is required for the read-only social intel tools.

Available Tools (97 — 94 trading + 3 X read-only)

Scanning

Token Analysis

Intelligence

Trading

Reflection & Server-Side Memory

Strategy

Safety

Wallet

Entitlements

Trade History & Risk

Alpha Signal Processing

Firehose

Bitquery Deep Scans

Gateway & System

Local Durable State

Episodic Decision Log

Team Bulletin

Context Snapshot

Deterministic Compute (Anti-Hallucination)

Intelligence Lab (New in V1-Upgraded)

Deep Analysis

OpenClaw Native Memory

X/Twitter (Read-Only Social Intel)

Hooks (2)

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 6 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

Tools returning errors:

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

Session / wallet-proof loop (CLI login succeeds but OpenClaw gateway tools keep failing):

This usually means a stale session-tokens.json sidecar is overriding the refresh token in openclaw.json, and/or the CLI and gateway resolved a different dataDir when one process used a different working directory.

1. Stop the gateway (systemctl --user stop openclaw-gateway.service or equivalent).
2. Back up then remove session-tokens.json under your session data directory (see dataDir in openclaw.json; default is ~/.traderclaw-v1-data for new installs — older installs may still use a legacy <cwd>/.traderclaw-v1-data folder).
3. In ~/.openclaw/openclaw.json, set plugins.entries.solana-trader.config.dataDir to a single absolute path (for example /root/.traderclaw-v1-data when running as root) so the CLI and gateway always agree.
4. Run traderclaw login (use --wallet-private-key or env if the server requires wallet proof).
5. Start the gateway again, then run traderclaw test-session and a quick tool smoke test.

New traderclaw setup runs persist explicit dataDir, and traderclaw login writes the session sidecar so it matches openclaw.json after login.

Memory/state not persisting:

• Check that the dataDir config points to a writable location
• Default is ~/.traderclaw-v1-data (older releases used <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