my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: solana-clawd
#3	description: 'One-shot setup and operation guide for the solana-clawd agentic engine. Use when: cloning the repo, setting up MCP tools, starting the Telegram bot, deploying to Fly.io/Netlify, hatching blockchain buddies, running OODA loops, configuring voice mode (ElevenLabs + Grok), minting Metaplex agents, managing the vault, running the worker swarm, or contributing to the project. Covers all 31 MCP tools, 18 buddy species, 9 spinners, 60+ Telegram commands, 95 skills, and the full repo structure.'
#4	metadata:
#5	{
#6	"solanaos": {
#7	"emoji": "\U0001F43E",
#8	"requires": {
#9	"env": ["HELIUS_API_KEY"],
#10	"bins": ["node", "npm"]
#11	}
#12	}
#13	}
#14	---
#15
#16	# solana-clawd — The Agentic Engine Solana Deserves
#17
#18	Repo: [github.com/x402agent/solana-clawd](https://github.com/x402agent/solana-clawd)
#19	Live: [solanaclawd.com](https://solanaclawd.com)
#20	npm: `solana-clawd` (v1.6.0)
#21	Token: `$CLAWD` — `8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump`
#22
#23	## When to Use
#24
#25	- Setting up solana-clawd from scratch (clone, install, configure)
#26	- Connecting MCP tools to Claude Desktop, Cursor, VS Code
#27	- Starting the Telegram trading bot
#28	- Deploying the web app or MCP server
#29	- Hatching blockchain buddies or running spinners
#30	- Running OODA trading loops
#31	- Running Phoenix perpetuals through the official Solana CLAWD perps agent and bundled Vulcan skills
#32	- Configuring voice mode (ElevenLabs + Grok)
#33	- Minting agents on Metaplex
#34	- Managing encrypted vault secrets
#35	- Contributing new tools, buddies, or skills
#36
#37	## One-Shot Install
#38
#39	```bash
#40	git clone https://github.com/x402agent/solana-clawd
#41	cd solana-clawd
#42	npm run setup
#43	```
#44
#45	`npm run setup` is the canonical bootstrap. It installs dependencies, builds the root runtime, builds `MCP/`, builds `packages/agentwallet/`, builds the main web app, builds the Clawd Vault web app, builds the wiki app, syncs the skills catalog, and creates `.env` from `.env.example` if needed.
#46
#47	Minimum keys needed for live Solana data: `HELIUS_API_KEY` (free at helius.dev).
#48
#49	### Quick Demo (no keys needed)
#50
#51	```bash
#52	npm run demo
#53	npm run birth
#54	npm run spinners
#55	```
#56
#57	### Install As A Standalone Skill
#58
#59	Install only the master `solana-clawd` skill:
#60
#61	```bash
#62	npx skills add x402agent/solana-clawd --path skill/solana-clawd
#63	```
#64
#65	Install the full Solana-clawd skill pack from this repo:
#66
#67	```bash
#68	npx skills add x402agent/solana-clawd
#69	```
#70
#71	## MCP Setup
#72
#73	### Claude Desktop
#74
#75	Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
#76
#77	```json
#78	{
#79	"mcpServers": {
#80	"solana-clawd": {
#81	"command": "node",
#82	"args": ["/path/to/solana-clawd/MCP/dist/index.js"],
#83	"env": { "HELIUS_API_KEY": "your-key" }
#84	}
#85	}
#86	}
#87	```
#88
#89	### Cursor / VS Code
#90
#91	```json
#92	{
#93	"solana-clawd": {
#94	"command": "node",
#95	"args": ["MCP/dist/index.js"],
#96	"cwd": "/path/to/solana-clawd"
#97	}
#98	}
#99	```
#100
#101	### Public HTTP (no install)
#102
#103	```json
#104	{
#105	"solana-clawd": { "type": "http", "url": "https://solana-clawd.fly.dev/mcp" }
#106	}
#107	```
#108
#109	## MCP Tools (31)
#110
#111	\| Category \| Tools \| Description \|
#112	\|----------\|-------\|-------------\|
#113	\| Market Data (8) \| `solana_price`, `solana_trending`, `solana_token_info`, `solana_wallet_pnl`, `solana_search`, `solana_top_traders`, `solana_wallet_tokens`, `sol_price` \| Live prices, trending, security scores, smart money, PnL \|
#114	\| Helius Onchain (8) \| `helius_account_info`, `helius_balance`, `helius_transactions`, `helius_priority_fee`, `helius_das_asset`, `helius_webhook_create`, `helius_webhook_list`, `helius_listener_setup` \| RPC, DAS metadata, enhanced txs, webhooks, WebSocket \|
#115	\| Agent Fleet (3) \| `agent_spawn`, `agent_list`, `agent_stop` \| Spawn research/OODA/scanner/dream agents \|
#116	\| Memory (2) \| `memory_recall`, `memory_write` \| KNOWN/LEARNED/INFERRED 3-tier memory \|
#117	\| Metaplex (6) \| `metaplex_mint_agent`, `metaplex_register_identity`, `metaplex_read_agent`, `metaplex_delegate_execution`, `metaplex_verify_mint`, `metaplex_agent_wallet` \| Mint AI agents as MPL Core assets \|
#118	\| Pump.fun (8) \| `pump_token_scan`, `pump_buy_quote`, `pump_sell_quote`, `pump_graduation`, `pump_market_cap`, `pump_top_tokens`, `pump_new_tokens`, `pump_cashback_info` \| Bonding curve scanner, quotes, graduation \|
#119	\| Skills (2) \| `skill_list`, `skill_read` \| Browse and load 95 SKILL.md files \|
#120
#121	## Phoenix Perps: Vulcan / Rise SDK
#122
#123	The repo includes the full Vulcan skill pack under `vulcan-cli-master/skills` and exposes forwarding skills under `skills/vulcan-*`.
#124
#125	Use this loading order for Phoenix perps work:
#126
#127	1. `skills/vulcan/SKILL.md`
#128	2. `vulcan-cli-master/CONTEXT.md`
#129	3. `vulcan-cli-master/skills/INDEX.md`
#130	4. Focused skills such as `vulcan-market-intel`, `vulcan-risk-management`, `vulcan-trade-execution`, `vulcan-twap-execution`, `vulcan-grid-trading`, or `vulcan-ta-strategy`
#131
#132	Official Python perps agent:
#133
#134	```bash
#135	cd solana-python-agent
#136	python perps_agent.py health
#137	python perps_agent.py market SOL
#138	python perps_agent.py paper-order buy SOL --notional-usdc 100
#139	python perps_agent.py preflight
#140	```
#141
#142	Safety contract:
#143
#144	- Paper mode is default.
#145	- Live orders require explicit `--yes`.
#146	- Live strategies require preflight and explicit mode selection.
#147	- The agent never reads or prints private keys, wallet passwords, or MCP config secrets.
#148
#149	## Telegram Bot
#150
#151	```bash
#152	# Set minimum env vars
#153	export TELEGRAM_BOT_TOKEN=<from-botfather>
#154	export HELIUS_API_KEY=<from-helius.dev>
#155	export TELEGRAM_ALLOWED_CHATS=<your-chat-id> # lock to your user
#156
#157	# Start
#158	npx tsx src/telegram/index.ts
#159	```
#160
#161	### Key Commands
#162
#163	\| Category \| Commands \|
#164	\|----------\|----------\|
#165	\| Market \| `/sol`, `/price <mint>`, `/trending`, `/token <mint>`, `/wallet <addr>`, `/market`, `/latest`, `/graduated` \|
#166	\| Research \| `/research <mint>`, `/deepresearch <mint>`, `/ooda`, `/chart <mint>`, `/trades <mint>`, `/toptraders <mint>`, `/holders <mint>` \|
#167	\| Pump.fun \| `/scan`, `/snipe`, `/stop`, `/signal`, `/grad <mint>`, `/mcap <mint>`, `/cashback <mint>` \|
#168	\| Helius \| `/balance`, `/tokens`, `/txs`, `/slot`, `/assets` \|
#169	\| AI \| `/grok <q>`, `/xsearch <q>`, `/wsearch <q>`, `/imagine <prompt>`, `/video <prompt>`, `/vision <url>` \|
#170	\| Twitter \| `/tweet <text>`, `/reply <id> <text>`, `/like <id>`, `/rt <id>`, `/tsearch <q>`, `/autotweet on` \|
#171	\| Vault \| `/vault`, `/vault store <label> <secret>`, `/vault get <id>`, `/vault lock` \|
#172	\| System \| `/status`, `/agentstate`, `/skills`, `/help`, `/watch <mint>` \|
#173
#174	## Voice Mode
#175
#176	The web app at `solanaclawd.com/voice` supports two providers:
#177
#178	\| \| ElevenLabs \| Grok (xAI) \|
#179	\|---\|---\|---\|
#180	\| Agent \| Conversational AI (signed URL) \| Realtime API (ephemeral tokens, server VAD) \|
#181	\| TTS \| Roger, Sarah, River, Will \| Rex, Eve, Ara, Sal, Leo + speech tags \|
#182	\| Tools \| -- \| Web search during conversation \|
#183
#184	```bash
#185	# Required env vars (web/.env)
#186	ELEVEN_LABS_API_KEY=<elevenlabs-key>
#187	ELEVENLABS_AGENT_ID=<agent-id>
#188	XAI_API_KEY=<xai-key>
#189	```
#190
#191	## Blockchain Buddies
#192
#193	18 species across 5 categories. 8 stats per buddy. 5 rarity tiers (common 60% to legendary 1%). Multi-frame ASCII sprites with 12 hat options.
#194
#195	```typescript
#196	import { createBlockchainBuddy, formatBuddyCard } from 'solana-clawd/buddy'
#197	const buddy = createBlockchainBuddy()
#198	console.log(formatBuddyCard(buddy))
#199	```
#200
#201	Species: SolDog, BONK Dog, dogwifhat, Jupiter Agg, Raydium LP, Whale, Bull, Bear, MEV Shark, Octopus, DeGod, y00t, Okay Bear, Pepe, Pump.fun, Sniper Bot, Validator, RPC Node.
#202
#203	## OODA Trading Loop
#204
#205	```bash
#206	npx tsx examples/ooda-loop.ts
#207	```
#208
#209	```
#210	OBSERVE -> sol_price, trending, helius_priority_fee, memory KNOWN
#211	ORIENT -> score candidates (trend + momentum + liquidity + participation - risk)
#212	DECIDE -> confidence >= 60? -> size band
#213	ACT -> trade_execute gated at `ask` permission
#214	LEARN -> write INFERRED -> Dream agent promotes to LEARNED
#215	```
#216
#217	9 built-in agents: Explore, Scanner, PumpScanner, SniperBot, OODA, Dream, Analyst, Monitor, MetaplexAgent.
#218
#219	## Metaplex Agent Minting
#220
#221	```typescript
#222	import { createAgentUmiFromEnv, mintClawdAgentFromTemplate } from 'solana-clawd/metaplex'
#223	const umi = createAgentUmiFromEnv('solana-devnet')
#224	const result = await mintClawdAgentFromTemplate(umi, 'trader', {
#225	uri: 'https://arweave.net/metadata.json',
#226	network: 'solana-devnet',
#227	})
#228	```
#229
#230	Templates: `explorer`, `scanner`, `trader`, `analyst`, `monitor`, `custom`.
#231	Networks: solana-mainnet, solana-devnet, localnet, eclipse, sonic, fogo.
#232
#233	## Vault (AES-256-GCM)
#234
#235	```typescript
#236	import { SolanaVault } from 'solana-clawd/vault'
#237	const vault = await SolanaVault.create('passphrase')
#238	await vault.store('api_key', 'sk-live-...', 'Helius key')
#239	vault.lock() // zero-fills key from memory
#240	```
#241
#242	Auto-locks after 15 min. Scrypt-derived master key. Sentinel validation.
#243
#244	## Deploy
#245
#246	### Fly.io (MCP server)
#247
#248	```bash
#249	cd MCP && fly launch --config fly.toml
#250	fly secrets set HELIUS_API_KEY=key MCP_API_KEY=optional-bearer
#251	```
#252
#253	### Netlify (web app)
#254
#255	```bash
#256	netlify deploy --prod
#257	# Set env: ELEVEN_LABS_API_KEY, ELEVENLABS_AGENT_ID, XAI_API_KEY
#258	```
#259
#260	### Worker Swarm (iii SDK)
#261
#262	```bash
#263	cd tailclawd/quickstart
#264	iii -c iii-config.yaml # start engine
#265	docker compose up --build # start 4 workers (TS + Rust + Python)
#266	```
#267
#268	## Repo Structure
#269
#270	```
#271	MCP/ 31 MCP tools, STDIO + HTTP + SSE transport
#272	src/ 58 subsystems, 400+ files (engine, agents, telegram, buddy, pump, voice...)
#273	web/ Next.js frontend (chat, buddies, voice) — solanaclawd.com
#274	gateway/ Express API + Telegram bot + Birdeye WebSocket
#275	packages/ agentwallet (encrypted Solana+EVM vault SDK)
#276	beepboop/ macOS menu bar companion (SwiftUI, Claude vision, voice)
#277	llm-wiki-tang/ Research knowledge base (Next.js + FastAPI + Supabase)
#278	tailclawd/ TailClawd web UI + iii SDK worker swarm
#279	elevenlabs-mcp-main/ ElevenLabs MCP server
#280	formal_verification/ Lean 4 risk engine spec
#281	skills/ 95 SKILL.md knowledge documents
#282	examples/ 4 runnable demos (buddies, wallet listener, OODA, x402)
#283	docs/ architecture.md (48KB), migration guide, risk engine spec
#284	```
#285
#286	## Environment Variables
#287
#288	See `.env.example` (55 lines). Minimum:
#289
#290	```bash
#291	HELIUS_API_KEY= # Free at helius.dev (1M credits/month)
#292	```
#293
#294	Full list by category:
#295
#296	\| Category \| Keys \|
#297	\|----------\|------\|
#298	\| Core \| `HELIUS_API_KEY`, `HELIUS_RPC_URL`, `SOLANA_TRACKER_API_KEY`, `BIRDEYE_API_KEY` \|
#299	\| LLM \| `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `XAI_API_KEY` \|
#300	\| Voice \| `ELEVEN_LABS_API_KEY`, `ELEVENLABS_AGENT_ID` \|
#301	\| Telegram \| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_ALLOWED_CHATS`, `TELEGRAM_ADMIN_IDS` \|
#302	\| Wallet \| `SOLANA_PUBLIC_KEY`, `SOLANA_PRIVATE_KEY`, `VAULT_PASSPHRASE` \|
#303	\| Social \| `CONSUMER_KEY`, `SECRET_KEY`, `ACCESS_TOKEN`, `ACCESS_TOKEN_SECRET`, `BEARER_TOKEN` \|
#304	\| Deploy \| `MCP_API_KEY`, `CONVEX_URL`, `CONVEX_DEPLOY_KEY` \|
#305
#306	## Pitfalls
#307
#308	- No dotenv auto-load — Telegram bot needs `source .env` or `set -a && source .env && set +a` before running
#309	- Helius free tier — 1M credits/month, enough for dev but not high-frequency polling
#310	- Pump sniper — Requires `SOLANA_PRIVATE_KEY` for live execution; signal-only mode works without
#311	- Voice mode — Both ElevenLabs and xAI consume credits per request; monitor usage
#312	- Wiki sub-project — `web/wiki/` has separate dependencies; excluded from main Next.js build via `eslint.dirs`
#313	- Node 20+ required — uses native WebSocket, `structuredClone`, other modern APIs
#314	- Bun compatible but tested primarily on Node; `bun:bundle` feature gates exist in voice code
#315
#316	## Contributing
#317
#318	```bash
#319	npm run build # TypeScript compilation
#320	npm run dev # watch mode
#321	npm run typecheck # strict type checking
#322	npm run mcp:build # MCP server only
#323	npm run demo # test the demo
#324	npm run birth # test buddy hatching
#325	npm run skills:catalog # regenerate skill manifest
#326	```
#327
#328	High-impact areas: new MCP tools, buddy species, spinners, voice agent skills, Telegram commands. See `CONTRIBUTING.md`.
#329

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public