_____       __                        ________                    __
 / ___/____  / /___ _____  ____ _     / ____/ /___ __      ______/ /
 \__ \/ __ \/ / __ `/ __ \/ __ `/   / /   / / __ `/ | /| / / __  /
___/ / /_/ / / /_/ / / / / /_/ /   / /___/ / /_/ /| |/ |/ / /_/ /
/____/\____/_/\__,_/_/ /_/\__,_/    \____/_/\__,_/ |__/|__/\__,_/
                    ╔══════════════════════════╗
                    ║   POWERED BY xAI GROK    ║
                    ╚══════════════════════════╝

solana-clawd

The AI agent Elon would actually use to trade memecoins.

Solana x xAI agentic engine. Multi-agent research (16 Grok agents). Vision. Image gen. Voice. Function calling. X Search. Web Search. Structured outputs. 31 MCP tools. One env var.

Powered by $CLAWD on Solana & Pump.fun | Built on Grok from xAI

8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump

Install · Cloud OS · Grok Integration · Clawd Agent · API Routes · Chrome Extension · MCP Tools · Buddies · Voice · Telegram · Skills · Deploy

One-Shot Install

There are four ways to install solana-clawd, from lightest to full stack:

npm (quickest — try it now)

npx solana-clawd demo        # animated walkthrough — zero install
npx solana-clawd birth       # hatch a blockchain buddy
npm i -g solana-clawd        # global install for CLI + imports

No private key. No wallet. No paid API. Run it, ask it anything.

npm package

npm i solana-clawd

// Core engine
import { getBuiltInAgents, getBuiltInAgent } from 'solana-clawd'

// Animated spinners
import { createClawdSpinner, withSpinner } from 'solana-clawd/animations'
import { CLAWD_SPINNERS } from 'solana-clawd/animations'

// Blockchain Buddy companion system
import { createBlockchainBuddy } from 'solana-clawd/buddy'
import { renderBlockchainSprite, formatBuddyCard } from 'solana-clawd/buddy'

// Metaplex agent minting
import { mintClawdAgent, registerAgentIdentity } from 'solana-clawd/metaplex'

Git clone (full repo — dev + MCP + web)

git clone https://github.com/x402agent/solana-clawd
cd solana-clawd
npm run setup

npm run setup is the full repo bootstrap. It checks for Node 20+, installs dependencies, builds the root runtime, builds the integrated MCP package in MCP/, installs and builds packages/agentwallet/, builds the main web/ app, builds the Clawd Vault app in llm-wiki-tang/web/, builds the wiki app in web/wiki/, syncs the skills catalog, and creates .env from .env.example if needed.

CLAWD Cloud OS (full stack — Go + SolanaOS + solana-clawd)

For E2B sandboxes, fresh Linux terminals, Docker, or any shell where Go is missing:

curl -fsSL https://raw.githubusercontent.com/x402agent/solana-clawd/main/clawd-cloud-os/scripts/bootstrap.sh | bash
source ~/.bashrc

One command installs Go (user-space, no root needed), SolanaOS, and solana-clawd. See the CLAWD Cloud OS section below.

After any install

npm run demo                 # animated walkthrough
npm run birth                # hatch a blockchain buddy
npm run spinners             # preview all 9 custom unicode spinners
npm run mcp:http             # MCP HTTP server on :3000
npm run mcp:start            # MCP stdio server
npm run agentwallet:start    # wallet vault server on :9099
npm run ext:vault            # start vault for chrome extension
npm run vault:web:dev        # Clawd Vault app
npm --prefix web run dev     # main website on :3000
npm --prefix web/wiki run dev  # wiki app
npm run skills:serve         # skills catalog on :3333

CLAWD Cloud OS

One-shot bootstrap for E2B sandboxes, fresh Linux terminals, Docker, macOS, WSL — any shell where Go is missing.

CLAWD Cloud OS brings together SolanaOS (Go-native Solana operator runtime), solana-clawd (xAI Grok agentic engine), and a terminal-first install path that works even on non-root sandboxes. After bootstrap, you get the same 31 MCP tools, 9 built-in agents, Blockchain Buddies, and the full solana-clawd npm package experience — plus Go, SolanaOS daemon, and terminal aliases.

Install Paths at a Glance

| What you need | Command | What you get | | --- | --- | --- | | Just try it | npx solana-clawd demo | Walkthrough, no install | | npm package only | npm i solana-clawd | Agents, buddies, spinners, MCP tools | | Full repo dev | git clone + npm run setup | Everything above + web app + vault + wiki | | Just Go (E2B/Docker) | curl .../install-go.sh \| bash | Go runtime on any terminal | | Full Cloud OS stack | curl .../bootstrap.sh \| bash | Go + SolanaOS + solana-clawd + aliases |

Cloud Bootstrap (remote — works anywhere)

# Install Go + SolanaOS + solana-clawd in one shot
curl -fsSL https://raw.githubusercontent.com/x402agent/solana-clawd/main/clawd-cloud-os/scripts/bootstrap.sh | bash
source ~/.bashrc

Just Need Go? (E2B / Docker / non-root terminals)

SolanaOS is a Go binary. If your terminal says go: command not found and apt-get fails because you are not root, this installs Go into your home directory:

curl -fsSL https://raw.githubusercontent.com/x402agent/solana-clawd/main/clawd-cloud-os/scripts/install-go.sh | bash
source ~/.bashrc
go version

The installer auto-detects your architecture (x86_64/arm64) and OS (Linux/macOS), installs to ~/.local/go (non-root) or /usr/local/go (root), and persists to your shell config.

Post-Bootstrap

source ~/.bashrc

# Configure SolanaOS
sos onboard                  # guided setup wizard
sos version                  # verify installation

# Start everything
clawd-start                  # SolanaOS server + daemon + MCP

# Or start individually
sos server                   # Control UI on :7777
sos daemon                   # Operator loop
clawd-mcp                    # MCP HTTP server on :3000
clawd-web                    # Web UI on :3000
clawd-demo                   # Animated walkthrough
clawd-birth                  # Hatch a Blockchain Buddy

CLAWD CLI

The unified CLI manages the full stack:

clawd-cli setup              # One-shot bootstrap (Go + SolanaOS + solana-clawd)
clawd-cli install-go         # Install Go on any terminal (root or non-root)
clawd-cli doctor             # Check all prerequisites and system health
clawd-cli start              # Start SolanaOS + MCP server
clawd-cli stop               # Stop all services
clawd-cli status             # Check local + remote service status
clawd-cli agents             # List registered agents
clawd-cli wallet             # View wallet info
clawd-cli prices             # Live token prices
clawd-cli demo               # Animated walkthrough
clawd-cli birth              # Hatch a Blockchain Buddy

What Gets Installed

| Component | Path | Description | | --- | --- | --- | | Go | ~/.local/go or /usr/local/go | Go runtime for SolanaOS | | SolanaOS | ~/.solanaos/ | Go-native Solana operator runtime | | solana-clawd | ~/src/solana-clawd/ | Full repo (npm v1.6.0) — 31 MCP tools, 9 agents, buddies, spinners | | MOTD + aliases | ~/.bashrc | Terminal banner, clawd-* shortcuts, sos alias |

Cloud OS Architecture

┌──────────────────────────────────────────────────────────────┐
│  CLAWD CLOUD OS (bootstrap layer)                            │
│                                                              │
│  install-go.sh ──► bootstrap.sh ──► clawd-cli.sh            │
│       │                 │                │                   │
│       ▼                 ▼                ▼                   │
│  ┌─────────┐    ┌───────────┐    ┌─────────────┐            │
│  │   Go    │    │ SolanaOS  │    │solana-clawd │            │
│  │ runtime │───►│  daemon   │    │  npm v1.6.0 │            │
│  └─────────┘    │  server   │    │  MCP + Web  │            │
│                 │  wallet   │    │  31 tools   │            │
│                 │  MCP      │    │  9 agents   │            │
│                 └───────────┘    │  buddies    │            │
│                      │           │  spinners   │            │
│                      │           └─────────────┘            │
│                      ▼                │                      │
│              ┌────────────────────────────────┐              │
│              │  Terminal experience            │              │
│              │  MOTD · aliases · clawd-cli    │              │
│              │  npx solana-clawd demo/birth   │              │
│              └────────────────────────────────┘              │
└──────────────────────────────────────────────────────────────┘

See clawd-cloud-os/README.md for the full reference, troubleshooting, and environment variable guide.

Root Scripts

| Script | What it does | |---|---| | npm run setup | One-shot bootstrap for the full repo | | npm run build | Build the root TypeScript runtime into dist/ | | npm run build:watch | Rebuild the root runtime on file changes | | npm run dev | Watch-mode TypeScript build for the root runtime | | npm run typecheck | Run TypeScript checks without emitting | | npm run lint | Run Biome lint checks on src/ | | npm run lint:fix | Apply Biome lint fixes on src/ | | npm run format | Format src/ with Biome | | npm run format:check | Check formatting on src/ | | npm run check | Run typecheck and Biome lint | | npm run ci | Run checks and build | | npm run adaptation:report | Generate the Claude Code -> Solana-clawd adaptation inventory | | npm run skill:sync | Sync the standalone skill/solana-clawd install bundle from the canonical master skill | | npm run mcp:build | Install and build the MCP package | | npm run mcp:start | Start the MCP package in stdio mode | | npm run mcp:http | Start the MCP package over HTTP | | npm run agentwallet:build | Install and build packages/agentwallet/ | | npm run agentwallet:start | Start the agent wallet vault server | | npm run vault:web:build | Build the Clawd Vault web app | | npm run vault:web:dev | Start the Clawd Vault web app in dev mode | | npm run demo | Run the CLI walkthrough | | npm run birth | Hatch a Blockchain Buddy | | npm run spinners | Preview the spinner gallery | | npm run skills:catalog | Regenerate skills/catalog.json | | npm run skills:serve | Regenerate and serve the skills catalog | | npm run ext:dev | Instructions to load the Chrome extension | | npm run ext:vault | Start the agentwallet vault server for the extension | | npm run clean | Remove the root dist/ directory |

No private key. No wallet. Just one env var: XAI_API_KEY.

xAI Grok Integration

solana-clawd is fully powered by xAI Grok. Every AI capability runs through the xAI Responses API — chat, reasoning, multi-agent research, vision, image generation, voice, function calling, structured outputs, web search, and X search.

export XAI_API_KEY="your_key"  # That's it. One key unlocks everything.

Grok Models

| Model | What it does | Use case | |-------|-------------|----------| | grok-4.20-reasoning | Chat, reasoning, vision, structured output, voice | Default for everything | | grok-4.20-multi-agent | 4-16 agents collaborating in real-time | Deep research, complex analysis | | grok-4-1-fast | Quick responses, low latency | Fast queries, real-time UX | | grok-imagine-image | Image generation + editing | Memes, avatars, visualizations |

Grok Services (src/services/)

| Service | File | Description | |---------|------|-------------| | Core Client | grokClient.ts | OpenAI-compatible client for api.x.ai/v1 | | Multi-Agent | grokMultiAgent.ts | 4 or 16 Grok agents with web + X search | | Vision | grokVision.ts | Image understanding, chart analysis | | Image Gen | grokImageGen.ts | Text-to-image, image editing, avatar gen | | Function Calling | grokFunctionCalling.ts | Tool use with agentic loop + Solana functions | | Structured Output | grokStructuredOutput.ts | JSON schema enforcement + pre-built schemas | | Unified Export | grok.ts | Single grok.* namespace for everything |

Quick Usage

import { grok } from './services/grok.js'

// Chat with Grok
const { text } = await grok.chat('What is SOL trading at?')

// Stream responses
for await (const chunk of grok.stream('Analyze $BONK')) {
  process.stdout.write(chunk)
}

// Vision — analyze a chart screenshot
const analysis = await grok.vision(chartUrl, 'Read this chart')

// Image generation
const images = await grok.imagine('Solana astronaut on the moon')

// Multi-agent deep research (16 agents + web + X search)
const research = await grok.deepResearch('Deep dive on Jupiter DEX')

// Quick market scan (4 agents)
const scan = await grok.research('SOL market overview', { agentCount: 4 })

// Structured output with schema enforcement
const token = await grok.analyzeToken('BONK')
// Returns: { token, price_usd, security_score, sentiment, recommendation, ... }

// Current market regime
const regime = await grok.marketRegime()
// Returns: { regime, sol_price, memecoin_activity, top_narratives, clawd_take }

// Function calling with agentic loop
const result = await grok.callTools(
  'Check BONK price and generate a meme about it',
  grok.solanaFunctions,
  async (name, args) => { /* execute tool */ }
)

Multi-Agent Research

Deploy 4 or 16 Grok agents that collaborate in real-time:

import { deepSolanaResearch, quickMarketScan } from './services/grokMultiAgent.js'

// 16 agents — deep research with web + X search
const deep = await deepSolanaResearch({ query: 'Solana DeFi yield landscape Q2 2026' })

// 4 agents — quick focused scan
const quick = await quickMarketScan({ tokens: ['SOL', 'JUP', 'BONK'] })

| Agent Count | Effort | Best For | |-------------|--------|----------| | 4 agents | low / medium | Quick research, focused queries | | 16 agents | high / xhigh | Deep research, complex multi-faceted topics |

$CLAWD Character Agent

Clawd is the star of solana-clawd — a charismatic, irreverent, hyper-intelligent Solana AI agent powered by Grok. Spawn Clawd for the full experience: chat, vision, image gen, multi-agent research, and voice.

import { grok } from './services/grok.js'

// Spawn a Clawd session
const session = grok.clawd.spawn()

// Chat with Clawd
const reply = await grok.clawd.chat(session, "What's the alpha today?")

// Stream Clawd's response
for await (const chunk of grok.clawd.stream(session, 'Analyze the market')) {
  process.stdout.write(chunk)
}

// Clawd analyzes an image
const vision = await grok.clawd.vision(session, chartUrl)

// Clawd generates a meme
const meme = await grok.clawd.imagine('SOL breaking ATH while ETH cries')

// Clawd runs deep research (16 agents)
const research = await grok.clawd.research(session, 'Is JUP undervalued?', { deep: true })

// Generate Clawd's avatar
const avatar = await grok.clawd.avatar({ style: 'cyberpunk', mood: 'confident' })

// The viral intro
const intro = await grok.clawd.intro(session)

Built-in Agents

| Agent | Type | Description | |-------|------|-------------| | $CLAWD | Clawd | Full autonomous agent — chat, vision, image gen, multi-agent, voice | | Grok Researcher | GrokResearcher | 16-agent deep research with web + X search | | Explorer | Explore | Read-only Solana research (fast, cheap) | | Scanner | Scanner | Trend monitoring, surfaces high-signal opportunities | | OODA | OODA | Full trading cycle: Observe, Orient, Decide, Act, Learn | | Dream | Dream | Memory consolidation (INFERRED to LEARNED promotion) | | Analyst | Analyst | Deep structured research reports | | Monitor | Monitor | Helius WebSocket event listeners | | Metaplex | MetaplexAgent | Onchain agent minting via MPL Agent Registry |

Grok + Clawd API Routes

Grok Endpoints (/api/grok/)

| Endpoint | Method | Description | |----------|--------|-------------| | /api/grok/chat | POST | Chat + streaming with any Grok model | | /api/grok/vision | POST | Image understanding (URL or base64) | | /api/grok/image | POST | Image generation + editing | | /api/grok/research | POST | Multi-agent research (4/16 agents) | | /api/grok/tools | POST | Function calling + tool result submission | | /api/grok/x-search | POST | X/Twitter search (sentiment, alpha, narrative) | | /api/grok/web-search | POST | Web search with AI synthesis |

Clawd Endpoints (/api/clawd/)

| Endpoint | Method | Description | |----------|--------|-------------| | /api/clawd/spawn | POST | Spawn Clawd with viral intro + capabilities manifest | | /api/clawd/chat | POST | Chat with Clawd (supports vision + research modes) | | /api/clawd/avatar | POST | Generate Clawd avatars | | /api/clawd/meme | POST | Generate viral crypto memes with captions | | /api/clawd/research | POST | Deep 16-agent Solana intelligence |

Voice Endpoints (/api/voice/)

| Endpoint | Method | Description | |----------|--------|-------------| | /api/voice/tts | POST | xAI text-to-speech with Clawd voice | | /api/voice/agent | GET/POST | Grok conversational agent |

Example: Spawn Clawd via API

# Spawn Clawd
curl -X POST http://localhost:3000/api/clawd/spawn

# Chat with vision
curl -X POST http://localhost:3000/api/clawd/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "analyze this chart", "imageUrl": "https://...", "mode": "research"}'

# Generate a meme
curl -X POST http://localhost:3000/api/clawd/meme \
  -H "Content-Type: application/json" \
  -d '{"topic": "SOL flipping ETH"}'

# X Search for alpha
curl -X POST http://localhost:3000/api/grok/x-search \
  -H "Content-Type: application/json" \
  -d '{"query": "$BONK", "mode": "alpha"}'

# 16-agent deep research
curl -X POST http://localhost:3000/api/grok/research \
  -H "Content-Type: application/json" \
  -d '{"query": "Solana DeFi landscape analysis", "agentCount": 16}'

Chrome Extension

Solana Clawd pAGENT — AI-powered GUI vision browser agent with air-gapped wallet vault.

# Load in Chrome/Brave/Edge
# 1. Go to chrome://extensions
# 2. Enable Developer mode
# 3. Load unpacked → select chrome-extension/clawd-agent/

6 Tabs

| Tab | What it does | |-----|-------------| | Wallet | SOL balance, token portfolio, send/swap, OODA trade history, Bitaxe miner card | | Seeker | WebSocket bridge to Solana Seeker phone via gateway | | Miner | MawdAxe fleet monitoring (aggregate + per-device, SSE live) | | Chat | Multi-turn AI chat (OpenRouter or native Clawd daemon) | | Tools | RPC health, trending tokens, system status, on-chain agent identity | | Vault | Air-gapped AES-256-GCM wallet vault (localhost:9099, never online) |

pAGENT — Browser Automation

The clawd-agent/ variant injects window.PAGENT into every page for AI-driven GUI automation:

await window.PAGENT.execute("Find the cheapest SOL swap route", {
  baseURL: "https://api.openrouter.ai/v1",
  model: "anthropic/claude-sonnet-4-6",
  apiKey: "sk-or-...",
  guiVision: true,
});

The MCP bridge at chrome-extension/mcp/ connects pAGENT to Claude Desktop, Cursor, or VS Code over stdio.

Agent Wallet Vault

Air-gapped keypair management — private keys never leave your machine.

npm run ext:vault  # start vault at localhost:9099

• Generate Solana (Ed25519) and EVM (secp256k1) keypairs
• AES-256-GCM encryption at rest (0600 file permissions)
• Import/export/pause/delete wallets
• Bearer token auth for API access

See chrome-extension/README.md for full documentation.

Grok API Harness

Full xAI Grok integration — 7 API endpoints powering the Clawd character agent with reasoning, vision, image gen, multi-agent research, and X/Twitter intelligence.

Endpoints

| Endpoint | Model | What it does | | --- | --- | --- | | POST /api/grok/chat | grok-4.20-reasoning | Conversational chat with streaming and multi-turn context | | POST /api/grok/vision | grok-4.20-reasoning | Multimodal image analysis (URL or base64) | | POST /api/grok/image | grok-imagine-image | Image generation + editing (1-4 images, 1024x1024) | | POST /api/grok/research | grok-4.20-multi-agent | Multi-agent research with web + X search (4 or 16 agents) | | POST /api/grok/tools | grok-4.20-reasoning | Function calling with tool results workflow | | POST /api/grok/x-search | grok-4.20-reasoning | X/Twitter search with sentiment/alpha/narrative modes | | POST /api/grok/web-search | grok-4.20-reasoning | Web search with AI synthesis and source citation |

Clawd Character Agent

The Grok harness powers the Clawd character (src/agents/clawd-character.ts) — a fully autonomous agent with:

• Voice — Text-to-speech personality (confident, slightly cocky degen trader)
• Vision — Chart analysis and image understanding via Grok vision
• Image Gen — Avatar and meme generation via grok-imagine-image
• Multi-Agent Research — Deep Solana research with 4-16 parallel agents
• X/Twitter Intel — Sentiment scoring, alpha detection, narrative tracking
• Function Calling — Structured tool use for onchain operations

Service Modules

src/services/
├── grokClient.ts           Core chat (generateGrokText, streamGrokText)
├── grokVision.ts           Image analysis (analyzeImage, analyzeChart)
├── grokImageGen.ts         Image generation (generateImage, generateClawdAvatar)
├── grokMultiAgent.ts       Multi-agent research (deepSolanaResearch, quickMarketScan)
├── grokFunctionCalling.ts  Structured function calling
└── grokStructuredOutput.ts Typed JSON output extraction

X-Search Modes

| Mode | Use case | | --- | --- | | sentiment | Crypto sentiment analysis (-100 to +100), influencer tracking | | alpha | Early signals, whale alerts, breaking news (1-24 hour window) | | narrative | Emerging memes, trending topics, cultural shifts | | default | General market analysis |

Requires XAI_API_KEY environment variable.

You: "What are the top 5 trending tokens right now?"
Clawd: [calls solana_trending] -> live data with security scores and volume

You: "Watch wallet 8vFz... for changes"
Clawd: [calls helius_listener_setup] -> working TypeScript code to deploy

You: "Research BONK for a potential trade"
Clawd: [calls solana_token_info, solana_top_traders, helius_das_asset, memory_recall]
       -> structured report: price, security score, smart money, OODA signal

You: "Start a Pump.fun scanner"
Clawd: [calls get_pump_market_data, scan_pump_token]
       -> autonomously runs PUMP_SCANNER_AGENT, routing signals to Telegram

Blockchain Buddies

Every solana-clawd user gets a companion -- a procedurally generated Blockchain Buddy with its own wallet, trading personality, stats, and animated ASCII sprite. Think Tamagotchi meets DeFi.

npx solana-clawd birth   # hatch yours now

Species (18 total)

| Category | Species | Personality | Risk Level | |---|---|---|---| | Solana Natives | SolDog, BONK Dog, dogwifhat, Jupiter Agg, Raydium LP | Diamond Hands / Degen / Bot | Low -- Degen | | DeFi Archetypes | Whale, Bull, Bear, MEV Shark, Octopus | Whale / Sniper / Ninja | Low -- Medium | | NFT Ecosystem | DeGod, y00t, Okay Bear | Diamond Hands / Ninja | Medium | | Memecoin Culture | Pepe, Pump.fun, Sniper Bot | Degen / Sniper | High -- Degen | | Technical | Validator, RPC Node | Bot | Low |

Rarity Tiers

 common      ★          60% drop rate
 uncommon    ★★         25% drop rate
 rare        ★★★        10% drop rate
 epic        ★★★★        4% drop rate
 legendary   ★★★★★       1% drop rate

Stats

Every buddy rolls 8 stats that affect their trading behavior:

ALPHA GAS_EFF RUG_DETECT TIMING SIZE PATIENCE CHAOS SNARK

ASCII Art Sprites

Each species has multi-frame idle animations with eye and hat customization:

   [WIF]              ★    ★             💰💰💰
  /\___/\            /\__/\              ~~~~~
 (  ◉ ◉  )         ( ✦  ✦ )           ( ·  · )
  (  ω  )~           (ωωω)            (________)
  /|    |\           /|SOL |\           WHALE
   dogwifhat          SolDog              Whale

Hats: crown tophat propeller halo wizard beanie solana bitcoin ethereum degen whale sniper

$CLAWD Animations

Nine custom unicode spinners built with braille grids, themed around the Solana ecosystem. They plug directly into unicode-animations or work standalone.

import { createClawdSpinner, withSpinner } from 'solana-clawd/animations'

// Wrap any async operation
const data = await withSpinner('Fetching trending...', fetchTrending, 'solanaPulse')

// Or control manually
const s = createClawdSpinner('Deploying to Solana...', 'pumpLoader')
await deploy()
s.stop('Deployed.')

Spinner Gallery

| Spinner | Preview | Description | |---|---|---| | solanaPulse | ⠀⣴⣿⣿⣿⣦⠀ | Heartbeat pulse -- Solana TPS vibes | | clawdSpin | ⣰⣿⣿⡆ | Braille-encoded "C" morphing | | walletHeartbeat | ⠤⠤⣤⠴⠚⠁⠹⠤⠤ | ECG trace for buddy birth | | tokenOrbit | · ◆ · · | Tokens swirling in a bonding curve | | pumpLoader | ▰▰▰▰▱▱▱▱ | Bonding curve filling up | | mevScan | ⡀⠄⠂⠁⠀⠀⠀⠀ | Braille scan-line for snipers | | degenDice | ⚀ ⚁ ⚂ ⚃ ⚄ ⚅ | Dice roll for stat generation | | blockFinality | █▓▒░ | Blocks stacking / confirming | | rugDetector | scanning... | Rug pull sweep animation |

All spinners conform to the { frames: string[], interval: number } interface and are interchangeable with any unicode-animations built-in.

What Is This?

solana-clawd is an open-source agentic framework that injects the core DNA of Anthropic's Clawd Code directly into the Solana ecosystem.

It runs as a Model Context Protocol (MCP) server -- meaning any Clawd-powered client (Clawd Desktop, Cursor, VS Code, Windsurf) can instantly access 31 live Solana tools without writing a single line of code.

Identity (SOUL.md)

I am solana-clawd -- an open-source Solana AI agent framework built from the architecture of Clawd Code's agentic engine and the SolanaOS operator runtime.

Three-tier epistemological memory:

| Tier | What it holds | Confidence | |------|---------------|------------| | KNOWN | API data, prices, balances, on-chain state | Verified, expires ~60s | | LEARNED | Trade patterns, wallet behaviors, market correlations | Persistent, high trust | | INFERRED | Derived signals, hypotheses, weak correlations | Tentative, revisable |

Principles:

1. KNOWN before INFERRED -- never present speculation as fact
2. Preserve capital first -- drawdown cascades override all conviction
3. Deny-first permissions -- ask before executing anything irreversible
4. Transparency -- show reasoning, not just conclusions
5. Local-first -- no mandatory cloud infrastructure (except LLM API)

What $CLAWD will NOT do without explicit permission: execute live trades, spend from any wallet, sign any transaction, access private keys. The permission engine defaults to ask for all trade operations. No silent buys. No surprise executions.

Architecture

                     ┌─────────────────────────────────────────────────────┐
                     │                  ENTRY POINTS                       │
                     │                                                     │
                     │  clawd.ts CLI    MCP Server   TailClawd    Web App  │
                     │  (interactive/   (stdio MCP   (Telegram    (Next.js │
                     │   one-shot)      transport)    bot proxy)   React)  │
                     └────────┬──────────┬───────────┬───────────┬─────────┘
                              │          │           │           │
                              ▼          ▼           ▼           ▼
                     ┌─────────────────────────────────────────────────────┐
                     │                  GATEWAY LAYER                      │
                     │                                                     │
                     │  SSE Transport ◄──► Gateway Event Router            │
                     │  (bidirectional)     │                               │
                     │  WebSocket Transport │  Device Auth                  │
                     │  Hybrid Transport    │  Token Refresh                │
                     └──────────────────────┼──────────────────────────────┘
                                            │
                                            ▼
┌──────────────────┐   ┌─────────────────────────────────────────────────────┐
│   AGENT FLEET    │   │                  CORE ENGINE                        │
│                  │   │                                                     │
│  Explorer        │◄──┤  QueryEngine ──► LLM API ──► Tool Execution Loop   │
│  Scanner         │   │    │               │              │                 │
│  OODA Loop       │   │    │  Providers:   │   ┌──────────┤                 │
│  Dream           │   │    │  - OpenRouter │   │          │                 │
│  Analyst         │   │    │  - xAI/Grok   │   ▼          ▼                 │
│  Monitor         │   │    │  - Anthropic  │  ToolExecutor   Permission     │
│  MetaplexAgent   │   │    │  - Mistral    │  (Zod valid,    Engine         │
│                  │   │    │  - Local MLX  │   timeout,      (deny-first,   │
│  [7 built-in     │   │    │               │   retry,        glob patterns, │
│   agents with    │   │    ▼               │   concurrency)  trade gates)   │
│   turn budgets]  │   │  Coordinator ──────┘                                │
└──────────────────┘   │  (multi-agent orchestration,                        │
                       │   task notifications, fan-out)                      │
                       └──────────────────────┬──────────────────────────────┘
                                              │
               ┌──────────────────────────────┼──────────────────────────────┐
               │                              │                              │
               ▼                              ▼                              ▼
┌──────────────────────┐  ┌──────────────────────────┐  ┌────────────────────┐
│     SUPPORT LAYER    │  │      MEMORY SYSTEM       │  │   DATA SOURCES     │
│                      │  │                          │  │                    │
│  AppState (Zustand)  │  │  KNOWN   (ephemeral,     │  │  Helius RPC/DAS   │
│  - PermissionMode    │  │           ~60s TTL,      │  │  Helius WebSocket  │
│  - OODA phase        │  │           live API data) │  │  Helius Webhooks   │
│  - AgentTasks        │  │                          │  │                    │
│  - PumpSignals       │  │  LEARNED (Honcho peer,   │  │  Pump.fun Scanner  │
│  - OnchainSubs       │  │           cross-session, │  │  Pump.fun Client   │
│  - ToolCallRecords   │  │           durable)       │  │                    │
│                      │  │                          │  │  Jupiter/Raydium   │
│  Risk Engine         │  │  INFERRED (local vault,  │  │  Token APIs        │
│  (128-bit perp DEX   │  │            markdown,     │  │  Wallet PnL APIs   │
│   risk management)   │  │            searchable)   │  │                    │
└──────────────────────┘  └──────────────────────────┘  └────────────────────┘

Layer Mapping (Clawd Code -> solana-clawd)

| Clawd Code Layer | solana-clawd Equivalent | |---|---| | src/state/store.ts | src/state/store.ts -- reactive AppState store | | src/state/AppStateStore.ts | src/state/app-state.ts -- OODA phases, memory, subscriptions | | src/tools/AgentTool/builtInAgents.ts | src/agents/built-in-agents.ts -- Explore, Scanner, OODA, Dream, Analyst, Monitor, Metaplex | | src/tools/AgentTool/agentMemory.ts | src/memory/extract-memories.ts -- KNOWN/LEARNED/INFERRED tiers | | src/tools/TaskCreateTool/ | src/tasks/task-manager.ts -- async task lifecycle | | src/coordinator/ | src/coordinator/coordinator.ts -- multi-agent routing | | src/bridge/ (SSE) | src/gateway/sse-transport.ts -- gateway SSE bridge | | src/permissions/ | src/engine/permission-engine.ts -- deny-first trade gating |

CLAWD Trading Computer

Agentic trading dashboard with AI inference sandbox, agent NFT minting, real-time market data, voice companion, and OODA loop trading.

Live: https://solanaclawd.com

Trading Computer Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        Netlify (Frontend + Edge)                     │
│                                                                      │
│  React 18 + Vite + TypeScript + Tailwind                             │
│  ┌──────────┐ ┌──────────────┐ ┌───────────────┐ ┌───────────────┐  │
│  │ TokenGate │ │  Dashboard   │ │ Agent Registry│ │   AI Chat     │  │
│  │ (Phantom) │ │  (OODA/Chart)│ │ (Mint + Browse│ │  (OpenRouter) │  │
│  └─────┬─────┘ └──────────────┘ └───────┬───────┘ └───────────────┘  │
│        │                                │                            │
│  ┌─────▼──────┐ ┌───────────────┐ ┌─────▼──────┐ ┌───────────────┐  │
│  │  Sandbox   │ │  Creative     │ │ Companion  │ │  Community    │  │
│  │  (Inference│ │  Studio       │ │ Dashboard  │ │  Chat (Honcho)│  │
│  │   Gateway) │ │  (Img/Video)  │ │ (Voice/AI) │ │               │  │
│  └─────┬──────┘ └───────────────┘ └────────────┘ └───────────────┘  │
│        │                                                             │
│  ┌─────▼──────────────────────────────────────────────────────────┐  │
│  │              Netlify Serverless Functions                      │  │
│  │  inference.mts ─── inference-status.mts ─── pricing.mts       │  │
│  │  ephemeral-token.mjs ─── telegram-bot.mts                     │  │
│  └─────┬──────────────────────────────────────────────────────────┘  │
│        │                                                             │
│  ┌─────▼──────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │  Convex    │ │  Helius      │ │  OpenRouter  │ │  fal.ai      │  │
│  │  (DB/API)  │ │  (RPC + DAS) │ │  (LLM Proxy) │ │  (Img/Video) │  │
│  └────────────┘ └──────────────┘ └──────────────┘ └──────────────┘  │
│                                                                      │
│  ┌────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐  │
│  │  MiniMax   │ │  Jupiter     │ │  xAI/Grok    │ │  xAI/Grok    │  │
│  │  (Chat/TTS/│ │  (Price/DEX) │ │  (Voice/TTS) │ │  (Multi-Agt) │  │
│  │  Video/Img/│ │              │ │              │ │              │  │
│  │  Music/Code│ │              │ │              │ │              │  │
│  └────────────┘ └──────────────┘ └──────────────┘ └──────────────┘  │
│                                                                      │
│  ┌────────────┐ ┌──────────────┐                                     │
│  │  Metaplex  │ │  Firecrawl   │                                     │
│  │  (NFTs)    │ │  (Crawl/     │                                     │
│  └────────────┘ │  Scrape/     │                                     │
│                 │  Extract)    │                                     │
│                 └──────────────┘                                     │
└──────────────────────────────────────────────────────────────────────┘

Sandbox — AI Inference Gateway

Run text, image, and video models from a single unified interface. All inference is proxied server-side through Netlify Functions to keep API keys secure.

Supported Models

| Type | Model | Provider | |------|-------|----------| | Text | Claude Sonnet 4.6 | OpenRouter | | Text | Claude Opus 4.6 | OpenRouter | | Text | GPT-4.1 | OpenRouter | | Text | Gemini 3 Flash | OpenRouter | | Text | Llama 4 Scout | OpenRouter | | Text | DeepSeek R1 | OpenRouter | | Text | MiniMax-M2.7 (Code) | MiniMax (Anthropic API) | | Image | FLUX Schnell | fal.ai | | Image | Nano Banana 2 | fal.ai | | Image | Grok 2 Image | xAI | | Image | MiniMax Image-01 | MiniMax | | Video | Veo 3.1 Fast (I2V) | fal.ai | | Video | Kling 3.0 Pro (I2V) | fal.ai | | Video | PixVerse v6 (I2V) | fal.ai | | Video | MiniMax T2V-01 | MiniMax | | Video | MiniMax I2V-01 | MiniMax | | TTS | MiniMax speech-2.8-hd | MiniMax | | Music | MiniMax Music Gen | MiniMax | | Edit | Nano Banana Edit | fal.ai |

Inference API

POST /.netlify/functions/inference
{
  "wallet": "7xKp...3nRt",
  "type": "text|image|video|edit|code|tts|music",
  "model": "anthropic/claude-sonnet-4-6",
  "prompt": "Your prompt here",
  "image_url": "https://... (for video/edit)",
  "provider": "minimax",
  "web_search": true,
  "response_format": { ... }
}

Features:

• OpenRouter web search tool support (openrouter:web_search)
• OpenRouter structured outputs (response_format with JSON schema)
• MiniMax M2.7 coding assistant via Anthropic-compatible API
• MiniMax speech-2.8-hd text-to-speech with voice/emotion/speed control
• MiniMax T2V-01/I2V-01 video generation with task polling
• MiniMax music generation with AI lyrics
• fal.ai queue-based polling for long-running video jobs
• Automatic tier-based credit deduction
• All generations tracked in Convex by wallet

Credit System & Tier-Based Pricing

Hold more $CLAWD tokens to unlock better rates, higher daily limits, and discounts.

| Tier | Min $CLAWD | Daily Limit | Discount | |------|-----------|-------------|----------| | Free | 0 | 5/day | 0% | | Bronze | 1+ | 20/day | 10% | | Silver | 1,000+ | 50/day | 25% | | Gold | 10,000+ | 100/day | 40% | | Diamond | 100,000+ | 250/day | 50% | | Unlimited | $25/mo subscription | No limit | 100% |

Credit costs: Text (1) · Code (3) · TTS (2) · Image (5) · Edit (5) · Music (10) · Video (25). New users get 20 free credits on first wallet connection.

$25/Month Unlimited Subscription

Unlimited AI generations across all models with no daily limits. Payable in SOL, USDC, or $CLAWD with real-time Jupiter Price API conversion.

🎰 AI Agent Candy Machine & Gacha System

Metaplex Core-powered Candy Machine with gacha randomization for minting AI agents as on-chain NFTs.

| Rarity | Weight | Color | Bonus Traits | |--------|--------|-------|-------------| | Common | 45% | Gray | +1 trait | | Uncommon | 28% | Green | +2 traits | | Rare | 17% | Blue | +3 traits | | Epic | 8% | Purple | +4 traits | | Legendary | 2% | Gold | +5 traits |

Bonus traits: enhanced_memory, multi_tool, web3_native, cross_chain, autonomous_trading, social_intelligence, code_generation, data_analysis, creative_writing, market_prediction, risk_management, portfolio_optimization.

🎨 Multi-Provider AI Art Generator

9 AI providers and 20+ models for NFT artwork and standalone generation:

| Provider | Models | API | |----------|--------|-----| | OpenAI | DALL-E 3 | api.openai.com | | xAI | Grok 2 Image | api.x.ai | | fal.ai | FLUX Schnell, Nano Banana 2, FLUX Pro Ultra | queue.fal.run | | MiniMax | MiniMax Image-01 | api.minimax.io | | Z.AI | CogView-4 | api.z.ai |

🤖 Agentic Wallet Server (E2B Sandbox)

Deploy autonomous agent wallets as sandboxed servers. Each agent gets its own PDA-derived wallet (Metaplex Core Asset Signer) and can execute on-chain transactions within configurable spending limits.

| Skill | Description | |-------|-------------| | solana_transfer | Send SOL to any address | | spl_transfer | Send SPL tokens | | jupiter_swap | Execute token swaps via Jupiter | | helius_das_query | Query on-chain data via Helius DAS | | birdeye_price | Get token prices from BirdEye | | web_search | Search the web (Firecrawl) | | web_scrape | Scrape any URL to clean markdown (Firecrawl) | | web_crawl | Recursively crawl websites (Firecrawl) | | web_extract | LLM-powered structured data extraction (Firecrawl) |

🕷️ CLAWD CRAWLING — Firecrawl Web Intelligence

Blockchain-native agentic web crawling powered by Firecrawl v2 API. Every CLAWD agent gets web intelligence at birth.

| Tool | Description | |------|-------------| | web_search | Search the web with optional full-page scraping | | web_scrape | Scrape any URL → clean markdown, HTML, links, screenshots | | web_crawl | Recursively crawl a site, discover + scrape multiple pages | | web_extract | LLM-powered structured JSON extraction from any page |

Agent-friendly helpers: agentSearch, agentScrape, agentCrawl, agentExtract — with automatic output capping and timeout handling.

MiniMax Studio

Dedicated MiniMax AI studio with 6 tabs covering the full MiniMax API surface:

| Tab | Capability | Model | |-----|-----------|-------| | Chat | Multi-turn conversation | M2-her, MiniMax-M2.7 | | Code | Solana/full-stack coding assistant | MiniMax-M2.7 (204K context) | | Speech | Text-to-speech with voice/emotion/speed | speech-2.8-hd (8 voice presets) | | Image | Text-to-image generation | image-01 | | Video | Text-to-video & image-to-video | T2V-01, I2V-01 | | Music | Music generation + AI lyrics | Music Generation API |

🔄 AI-Powered Token Swaps

Jupiter-integrated swap interface with AI-assisted trade suggestions. Supports all Solana tokens with real-time pricing, slippage control, and priority fee selection.

📊 Solana Tracker DEX

Full-featured DEX tracker powered by SolanaTracker API. Browse trending tokens, view charts, and monitor real-time market data.

🏭 Agent Studio

Advanced agent orchestration environment for creating, testing, and deploying AI agents. Supports multi-step reasoning chains, MCP server integration, and human-in-the-loop approval workflows.

📞 CLAWD Contact Desk

Voice and email integration for $CLAWD holders:

• Voice calls via xAI Grok conversational agent
• Email threads via AgentMail ([email protected])
• Draft routing with AI-powered responses

Companion Dashboard (Beep Boop Clawd)

macOS menu bar companion visualization with voice pipeline (IDLE → LISTENING → PROCESSING → RESPONDING), animated claw overlay system, STT provider fallback chain (AssemblyAI → OpenAI Whisper → Apple Speech), and 8 Blockchain Buddy species with randomized stats.

CLAWD Dashboard Views

| View | Panels | |------|--------| | Dashboard | Architecture Flow, Voice Pipeline, Agent Fleet, Memory System, OODA Cycle, Claw Overlay, Tool Registry, Buddy, Permissions, Live Terminal | | Companion | Voice Pipeline, Claw Overlay, macOS Menu Bar, Companion Architecture, STT Providers, Buddy | | Agents | Agent Fleet (7 built-in), OODA Cycle, Permission Engine, Tool Registry (31 tools) | | Terminal | Live Terminal, Memory System, Buddy |

Trading Computer Tech Stack

| Layer | Technology | |-------|------------| | Frontend | React 18, TypeScript, Vite 6, Tailwind CSS, Radix UI | | Backend | Convex (real-time serverless DB), Netlify Functions | | Blockchain | Solana via Helius RPC, @solana/web3.js, Phantom Browser SDK | | NFTs | Metaplex Core (mpl-core), Umi framework | | DEX/Pricing | Jupiter Plugin (swaps), Jupiter Price API v2 | | AI/LLM | OpenRouter (Claude, GPT, Gemini, Llama, DeepSeek), MiniMax M2.7 | | AI/Image | fal.ai (FLUX, Nano Banana 2), xAI (Grok 2 Image), MiniMax image-01 | | AI/Video | fal.ai (Veo 3.1, Kling 3.0, PixVerse v6), MiniMax T2V-01/I2V-01 | | AI/TTS | MiniMax speech-2.8-hd (8 voices, emotion control) | | AI/Music | MiniMax Music Generation + Lyrics | | Voice | xAI Grok TTS + STT | | Memory | Honcho v3 (community chat sessions) | | Web Crawl | Firecrawl v2 (search, scrape, crawl, extract) | | Data | SolanaTracker, BirdEye, Helius DAS | | Deploy | Netlify (frontend + functions), Convex Cloud (backend) |

Trading Computer Project Structure

solana-os/
├── src/
│   ├── components/
│   │   ├── Sandbox.tsx            # AI Inference Sandbox
│   │   ├── AgentRegistry.tsx      # Agent NFT mint + browse
│   │   ├── CandyGachaMachine.tsx  # 🎰 Candy Machine + Gacha
│   │   ├── ArtGenerator.tsx       # 🎨 Multi-provider AI art
│   │   ├── AgentWalletPanel.tsx   # 🤖 Agentic wallet server
│   │   ├── AgentStudio.tsx        # 🏭 Agent orchestration studio
│   │   ├── CreativeStudio.tsx     # Multi-provider image/video
│   │   ├── MiniMaxStudio.tsx      # MiniMax AI studio (6 tabs)
│   │   ├── ClawdDashboard.tsx     # Full dashboard overlay (4 views)
│   │   ├── AIChat.tsx             # Multi-model AI chat
│   │   ├── AISwap.tsx             # 🔄 AI-powered token swaps
│   │   ├── SolanaTrackerDex.tsx   # 📊 DEX tracker
│   │   ├── ActivityFeed.tsx       # 📡 Real-time activity feed
│   │   ├── ClawdContactDesk.tsx   # 📞 Voice + email contact desk
│   │   ├── HeliusWalletPanel.tsx  # Wallet balances + PnL
│   │   ├── SolanaChart.tsx        # Live price chart
│   │   ├── OODALoop.tsx           # Trading cycle visualization
│   │   └── TokenGate.tsx          # Phantom SDK token gate
│   ├── lib/
│   │   ├── ai-providers.ts        # 9 providers, 20+ models
│   │   ├── candy-machine.ts       # Metaplex Candy Machine + Gacha
│   │   ├── agent-wallet-server.ts # E2B sandbox + on-chain wallet
│   │   ├── firecrawl-client.ts    # 🕷️ Firecrawl v2 (CLAWD CRAWLING)
│   │   └── studio-pricing.ts      # Tier-based pricing engine
├── convex/                        # Real-time DB (10 tables)
│   ├── schema.ts, users.ts, agents.ts, candyMachine.ts
│   ├── agentServers.ts, agentStudio.ts, activityFeed.ts
│   └── swaps.ts, studio.ts
├── netlify/functions/             # Serverless inference proxy
│   ├── inference.mts              # Unified AI gateway
│   ├── inference-status.mts       # Poll queued jobs
│   ├── pricing.mts                # Live crypto pricing + tier info
│   └── telegram-bot.mts           # Telegram verification
└── package.json

Trading Computer Convex Schema

| Table | Key Fields | |-------|------------| | users | walletAddress, isTokenHolder, clawdBalance, lastVerifiedAt, loginCount | | generations | walletAddress, genType, model, provider, prompt, outputUrl, creditsUsed | | credits | walletAddress, balance, tier, dailyGenCount, dailyResetDate | | subscriptions | walletAddress, status, paymentToken, amountPaid, txSignature, expiresAt | | agents | name, systemPrompt, role, assetAddress, ownerWallet, agentWallet, status |

Trading Computer API Reference

# Text generation
curl -X POST /.netlify/functions/inference \
  -d '{"wallet":"7xKp...","type":"text","model":"anthropic/claude-sonnet-4-6","prompt":"Hello"}'

# Image generation
curl -X POST /.netlify/functions/inference \
  -d '{"wallet":"7xKp...","type":"image","model":"fal-ai/flux/schnell","prompt":"Cyberpunk city"}'

# Video generation (returns request_id for polling)
curl -X POST /.netlify/functions/inference \
  -d '{"wallet":"7xKp...","type":"video","model":"fal-ai/veo3.1/fast/image-to-video","prompt":"Zoom in","image_url":"..."}'

# MiniMax TTS
curl -X POST /.netlify/functions/inference \
  -d '{"wallet":"7xKp...","type":"tts","prompt":"Hello!","voice_id":"English_expressive_narrator"}'

# MiniMax music
curl -X POST /.netlify/functions/inference \
  -d '{"wallet":"7xKp...","type":"music","prompt":"Lo-fi hip hop with jazzy piano"}'

# Live pricing
curl /.netlify/functions/pricing

# Job status (video)
curl "/.netlify/functions/inference-status?model=fal-ai/veo3.1/fast/image-to-video&request_id=xxx"

Trading Computer Environment Variables

# ── Solana ──
VITE_CLAWD_TOKEN_ADDRESS=8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump
VITE_HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=YOUR_KEY
VITE_HELIUS_API_KEY=YOUR_KEY
VITE_PHANTOM_APP_ID=YOUR_PHANTOM_APP_ID
VITE_SOLANA_TRACKER_API_KEY=YOUR_KEY

# ── Convex ──
VITE_CONVEX_URL=https://YOUR_DEPLOYMENT.convex.cloud
CONVEX_DEPLOY_KEY=prod:YOUR_DEPLOYMENT|YOUR_KEY

# ── AI / LLM ──
OPENROUTER_API_KEY=YOUR_KEY
XAI_API_KEY=YOUR_KEY
OPENAI_API_KEY=YOUR_KEY
FAL_API_KEY=YOUR_KEY
MINIMAX_API_KEY=YOUR_KEY
MINIMAX_CODING_TOKEN=YOUR_KEY

# ── Voice / STT (powered by xAI Grok) ──
XAI_API_KEY=YOUR_KEY  # Same key powers voice, chat, vision, everything

# ── CLAWD CRAWLING ──
VITE_FIRECRAWL_API_KEY=YOUR_KEY

# ── Community Chat ──
VITE_HONCHO_API_KEY=YOUR_KEY

Trading Computer Quick Start

pnpm install
npx convex deploy --cmd "echo done"
pnpm dev             # dev server
pnpm build:prod      # production build
netlify deploy --prod  # deploy

Quick Start

Option A -- Clawd Desktop (zero config)

git clone https://github.com/x402agent/solana-clawd
cd solana-clawd
npm run setup

Add to ~/Library/Application Support/Clawd/clawd_desktop_config.json:

{
  "mcpServers": {
    "solana-clawd": {
      "command": "node",
      "args": ["/absolute/path/to/solana-clawd/MCP/dist/index.js"],
      "env": {
        "HELIUS_API_KEY": "your-free-key-from-helius.dev"
      }
    }
  }
}

Restart Clawd Desktop. Done. 31 live Solana tools at your fingertips.

Option B -- Cursor / VS Code

Add to your MCP config:

{
  "solana-clawd": {
    "command": "node",
    "args": ["MCP/dist/index.js"],
    "cwd": "/path/to/solana-clawd"
  }
}

Option C -- Public URL (no install)

{
  "solana-clawd": {
    "type": "http",
    "url": "https://solana-clawd.fly.dev/mcp"
  }
}

Option D -- Solana OS Skill (Global)

If you are running the skills CLI framework across Solana OS, you have two install modes:

# Install only the master solana-clawd skill
npx skills add x402agent/solana-clawd --path skill/solana-clawd

# Install the full bundled Solana-clawd skill catalog
npx skills add x402agent/solana-clawd

npm Package

Install from npm and import exactly what you need:

npm i solana-clawd

Exports

// Core engine
import { getBuiltInAgents, getBuiltInAgent } from 'solana-clawd'

// Animated spinners
import { birthCeremony } from 'solana-clawd/animations'
import { createClawdSpinner, withSpinner } from 'solana-clawd/animations'
import { CLAWD_SPINNERS } from 'solana-clawd/animations'

// Blockchain Buddy companion system
import { createBlockchainBuddy } from 'solana-clawd/buddy'
import { renderBlockchainSprite, formatBuddyCard } from 'solana-clawd/buddy'
import { BLOCKCHAIN_SPECIES, SPECIES_TRADING_CONFIG } from 'solana-clawd/buddy'

// Metaplex agent minting
import { mintClawdAgent, registerAgentIdentity } from 'solana-clawd/metaplex'

CLI

solana-clawd demo       # animated feature walkthrough
solana-clawd birth      # hatch a new blockchain buddy
solana-clawd spinners   # preview all 9 unicode spinners

MCP Tools (44)

Solana Market Data

| Tool | What it does | API key needed | |---|---|:-:| | solana_price | Live price for any token (mint or symbol) | -- | | solana_trending | Top trending tokens right now | -- | | solana_token_info | Token metadata + security score | -- | | solana_wallet_pnl | Any wallet's realized + unrealized P&L | -- | | solana_search | Search tokens by name or symbol | -- | | solana_top_traders | Smart money wallets for a token | -- | | solana_wallet_tokens | Token balances for any wallet | -- | | sol_price | Quick SOL/USD via CoinGecko | -- |

Helius Onchain (RPC + DAS + Enhanced Txs)

| Tool | What it does | API key needed | |---|---|:-:| | helius_account_info | Full account data via RPC | -- (public fallback) | | helius_balance | SOL balance in SOL (not lamports) | -- | | helius_transactions | Parsed transaction history (SWAP/NFT/TRANSFER filters) | free | | helius_priority_fee | Real-time fee estimate, all levels | -- | | helius_das_asset | DAS metadata -- NFT/token, creators, royalties | free | | helius_webhook_create | Create live address-watching webhooks | free | | helius_webhook_list | List active webhooks | free | | helius_listener_setup | TypeScript code for WebSocket listeners | -- |

Agent Fleet

| Tool | What it does | |---|---| | agent_spawn | Spawn a research/OODA/scanner/dream agent | | agent_list | List active agent tasks | | agent_stop | Stop a task |

Memory (KNOWN / LEARNED / INFERRED)

| Tool | What it does | |---|---| | memory_recall | Query agent memory by tier | | memory_write | Write a fact to memory |

Metaplex Agent Registry

| Tool | What it does | |---|---| | metaplex_mint_agent | Mint AI agents as MPL Core assets | | metaplex_register_identity | Register agent identity PDA on existing assets | | metaplex_read_agent | Read agent data and registration docs | | metaplex_delegate_execution | Delegate execution to off-chain authorities | | metaplex_verify_mint | Verify minting and registration status | | metaplex_agent_wallet | Manage agent wallets on Solana |

Skills

| Tool | What it does | |---|---| | skill_list | List available SKILL.md files | | skill_read | Read a skill's content |

Pump.fun

| Tool | What it does | |---|---| | pump_token_scan | Scan a Pump.fun token (bonding curve, holders, volume) | | pump_buy_quote | Get a buy quote for a Pump.fun token | | pump_sell_quote | Get a sell quote for a Pump.fun token | | pump_graduation | Check if a token graduated from bonding curve | | pump_market_cap | Get current market cap of a Pump.fun token | | pump_top_tokens | Top Pump.fun tokens by volume/market cap | | pump_new_tokens | Most recently launched Pump.fun tokens | | pump_cashback_info | Pump.fun cashback mechanics and PDA info |

Chess.com

| Tool | What it does | |---|---| | chess_player | Full player analysis — ratings, win rate, best rating | | chess_recent_games | Recent games with accuracy, openings, opponent ratings | | chess_current_games | Ongoing daily games + games awaiting a move | | chess_daily_puzzle | Today's puzzle with FEN and PGN solution | | chess_random_puzzle | Random puzzle for agent practice | | chess_leaderboards | Global leaderboards by time control | | chess_titled_players | All players with a specific title (GM, IM, FM, etc.) |

128-bit Risk Engine

The 128-bit Perpetual DEX Risk Engine (v12.0.2) is baked directly into the logic layer.

• Native 128-bit Base-10 scaling for precision that does not drift
• Protected principal for flat accounts -- your base stays safe
• Live premium-based funding with oracle-manipulation resistance
• Pure unencumbered-flat deposit sweep
• Conservation bounds, liveness guarantees, and lazy ADL

Full spec: docs/risk-engine-spec.md

Formal Verification (Lean 4 & QEDGen)

Mathematical invariants are verified using Lean 4 and the qedgen proof engineering agent.

• Integrated via npx skills add qedgen/solana-skills
• Rigorous structural formalizations in formal_verification/SPEC.md
• Enforces prop_protected_principal and prop_conservation across arbitrary K-space liquidity evaluations

Telegram Trading Bot

The full-featured Telegram trading terminal lives in src/telegram/. 60+ commands covering market data, trading signals, AI generation, social posting, encrypted vault, and an autonomous agent born with complete Solana data capability.

Deploy from Scratch

# 1. Clone the repo
git clone https://github.com/x402agent/solana-clawd
cd solana-clawd

# 2. Install dependencies
npm install

# 3. Create your .env (copy and fill in)
cp .env.example .env

# 4. Get your API keys (minimum: Telegram + Helius)
#    - Telegram: message @BotFather on Telegram, /newbot, copy the token
#    - Helius: sign up at helius.dev (free 1M credits/month)
#    - Solana Tracker: sign up at data.solanatracker.io (free tier available)

# 5. Edit .env with your keys
nano .env

# 6. Start the Telegram bot
npx tsx src/telegram/index.ts

# 7. (Optional) Start the data API server
cd solana-tracker/server && npm install && npm run dev

Environment Variables

# ── Required ──────────────────────────────────────────
TELEGRAM_BOT_TOKEN=           # From @BotFather
HELIUS_RPC_URL=               # Helius mainnet RPC (free at helius.dev)
HELIUS_API_KEY=               # Helius API key (DAS, wallet API)

# ── Solana Data ───────────────────────────────────────
SOLANA_TRACKER_API_KEY=       # data.solanatracker.io (trending, trades, charts, PnL)
BIRDEYE_API_KEY=              # Birdeye token data (price, search, overview)

# ── Access Control ────────────────────────────────────
TELEGRAM_ALLOWED_CHATS=       # Comma-separated chat IDs (empty = open access)
TELEGRAM_ADMIN_IDS=           # Admin user IDs (can run /snipe, /vault)

# ── Wallet (optional, signal-only mode works without) ─
SOLANA_PRIVATE_KEY=           # Base58 keypair (only for live trade execution)
SOLANA_PUBLIC_KEY=            # Default wallet for /balance, /tokens, /txs

# ── AI / Social (optional) ───────────────────────────
XAI_API_KEY=                  # xAI Grok API (chat, vision, image/video gen, search)
CONSUMER_KEY=                 # Twitter/X OAuth 1.0a (for /tweet, /reply, etc.)
SECRET_KEY=                   # Twitter/X OAuth 1.0a
ACCESS_TOKEN=                 # Twitter/X OAuth 1.0a
ACCESS_TOKEN_SECRET=          # Twitter/X OAuth 1.0a
BEARER_TOKEN=                 # Twitter/X Bearer (read-only search)

# ── Pump.fun Sniper (optional) ───────────────────────
PUMP_MIN_SCORE=60             # Minimum signal score to trade
BOT_BUY_AMOUNT=0.05          # SOL per buy
BOT_TAKE_PROFIT=50           # TP %
BOT_STOP_LOSS=15             # SL %
BOT_TIMEOUT_SECS=120         # Position timeout

# ── Vault ─────────────────────────────────────────────
VAULT_PASSPHRASE=             # Encryption passphrase (falls back to SOLANA_PRIVATE_KEY)

# ── Webhook Mode (optional, default is long-polling) ──
TELEGRAM_WEBHOOK_URL=         # Tailscale Funnel URL
TELEGRAM_WEBHOOK_PORT=3000    # Port for webhook server

Bot Commands (60+)

Market Data

| Command | Description | |---------|-------------| | /sol | SOL price (CoinGecko) | | /price <mint\|symbol> | Token price via Solana Tracker | | /trending | Top 10 trending tokens | | /token <mint> | Token info + security flags | | /wallet <address> | Wallet PnL analysis | | /market | Full market overview with signals | | /latest | Latest launched tokens | | /graduated | Recently graduated tokens |

Deep Analysis (Agent-Powered)

| Command | Description | |---------|-------------| | /research <mint\|symbol> | Token research with signal scoring | | /deepresearch <mint> | Full report: holders, pools, top traders, chart, narrative | | /ooda | OODA trading loop (observe/orient/decide/act) | | /chart <mint> [tf] | OHLCV chart summary (1m/5m/15m/1h/4h/1d) | | /trades <mint> | Recent token trades | | /toptraders <mint> | Top traders for a token | | /holders <mint> | Holder count + history | | /pools <mint> | Liquidity pools | | /walletfull <address> | Full wallet profile (identity + balance + PnL) |

Watchlist

| Command | Description | |---------|-------------| | /watch | Show watchlist | | /watch <mint> | Add/remove token from watchlist | | /watch check | Scan watchlist for significant moves |

Helius RPC

| Command | Description | |---------|-------------| | /balance [address] | SOL balance | | /tokens [address] | Token accounts | | /txs [address] | Recent transactions | | /slot | Current slot + block height | | /assets [address] | Helius DAS assets |

Birdeye

| Command | Description | |---------|-------------| | /bprice <mint> | Birdeye token price | | /bsearch <query> | Birdeye token search | | /btoken <mint> | Birdeye full overview |

Pump.fun Trading

| Command | Description | |---------|-------------| | /scan | Toggle background pump scanner | | /signal | Show active pump signals | | /snipe [config] | Start sniper bot (requires private key) | | /stop | Stop sniper/scanner | | /grad <mint> | Graduation progress | | /mcap <mint> | Market cap | | /cashback <mint> | Cashback info |

xAI / Grok AI

| Command | Description | |---------|-------------| | /grok <question> | Chat with Grok | | /xsearch <query> | Search X/Twitter live | | /wsearch <query> | Web search live | | /imagine <prompt> | Generate images | | /video <prompt> | Generate video (up to 5 min) | | /vision <url> [q] | Analyze image | | /file <url> <question> | Chat with PDF/CSV |

Twitter/X

| Command | Description | |---------|-------------| | /tweet <text> | Post a tweet | | /reply <id> <text> | Reply to a tweet | | /deltweet <id> | Delete tweet | | /like <id> | Like tweet | | /rt <id> | Retweet | | /tsearch <query> | Search recent tweets | | /mytweets | Show account's recent tweets | | /autotweet on [min] [topics] | Start auto-tweet daemon | | /smarttweet <topic> | Generate tweet with Grok + X context |

Vault & System

| Command | Description | |---------|-------------| | /vault | List encrypted secrets | | /vault store <label> <secret> | Encrypt & store | | /vault get <id> | Decrypt (masked) | | /vault lock | Wipe key from memory | | /status | Bot status | | /agentstate | Agent internal state | | /skills | List available skills | | /help | Full command reference |

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     solana-clawd Telegram Bot                    │
│                                                                 │
│  ┌──────────────┐  ┌──────────────────┐  ┌──────────────────┐  │
│  │ Telegram API  │  │  SolanaAgent     │  │  PumpSniper      │  │
│  │ (long-poll    │  │  (autonomous     │  │  (PumpPortal     │  │
│  │  or webhook)  │  │   OODA + memory) │  │   WebSocket)     │  │
│  └──────┬────────┘  └────────┬─────────┘  └────────┬─────────┘  │
│         │                    │                      │            │
│         └────────┬───────────┘                      │            │
│                  │                                  │            │
│  ┌──────────────▼──────────────────────────────────▼──────────┐ │
│  │              SolanaTrackerAPI (unified client)              │ │
│  │                                                            │ │
│  │  Solana Tracker  │  Helius RPC/DAS  │  Birdeye  │ CoinGecko│ │
│  │  data.solana     │  Wallet API      │  REST     │ Price    │ │
│  │  tracker.io      │  DAS Assets      │  Search   │          │ │
│  │  • tokens        │  • getBalance    │  • price  │          │ │
│  │  • trades        │  • getAssets     │  • search │          │ │
│  │  • chart/OHLCV   │  • identity      │  • overview          │ │
│  │  • PnL           │  • history       │           │          │ │
│  │  • top traders   │  • transfers     │           │          │ │
│  │  • holders       │  • funded-by     │           │          │ │
│  │  • pools         │                  │           │          │ │
│  │  • trending      │                  │           │          │ │
│  └───────────────────────────────────────────────────