clawdsolana/openclawd

---

Start Here: ClawdBot Web3 Template

OpenClawd now starts users on ClawdBot, the default Web3 project template. It includes the OpenClawd agent runtime, Solana data hooks, Telegram bot support, optional Phala TEE key derivation, and a React UI surface.

# 1. Install dependencies
npm install

# 2. Copy the safe env template and add only local secrets
cp .env.example .env.local
$EDITOR .env.local

# 3. Check the repo
npm run doctor

# 4. Create a new ClawdBot project from the default template
openclawd create my-clawdbot
cd my-clawdbot
openclawd dev

Minimum useful env:

OPENROUTER_API_KEY=
HELIUS_API_KEY=
BIRDEYE_API_KEY=
TELEGRAM_BOT_TOKEN=      # optional, only needed for Telegram
SOLANA_PRIVATE_KEY=      # optional, only after read-only flows are tested

Visible starter source:

• clawdbot/ — the user-facing ClawdBot starter.
• web3/clawdbot/ — the vendored Web3 source copy.
• packages/clawdbot-template/ — the CLI template copy used by openclawd create.

Useful root commands:

npm run dev:clawdbot      # run the top-level clawdbot project
npm run build:clawdbot    # build the ClawdBot starter
npm run dev:ui            # run the main /ui control surface
npm run build:ui          # build the main /ui control surface
npm run build:steak       # build the OpenClawd agent staking Anchor program

The public Web3 source lives in web3/. The CLI-packaged default template lives in packages/clawdbot-template/. Do not commit populated env files, wallet keypairs, or private bot tokens.

Agent staking lives in steak/ and maps to the public /staking route in apps/clawdhub. See docs/STEAK.md for the directory map and root commands.

---

OpenClawd Operator + Skill Deck Adaptation

The repo now carries the Llobster Legend operator identity through the former Ralph orchestration surface, the public static site, the agent gallery, and the secondary skill catalog.

What changed:

• Operator package: clawd-operator/ is branded as OpenClawd Operator while keeping compatibility symbols such as ralph, RalphOrchestrator, and ralph_orchestrator intact for existing tests and imports.
• Runtime identity: CLI banners, config templates, docs, web monitor pages, login screen, package metadata, and exported identity constants now reference OpenClawd, Llobster Legend, $CLAWD, and the Solana token 8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump.
• Static site: site/index.html now includes an operator skill deck section, and site/agents/index.html frames the agent gallery as extendable by the secondary skills.
• Secondary skills: all 42 files under secondary_skills/*/SKILL.md include an OpenClawd Operator Adaptation block that preserves the original workflow and disclaimers while framing outputs for Solana-native agent operations where relevant.

Verification:

cd clawd-operator
uv run pytest
# 1021 passed, 48 skipped

For static site notes, see site/README.md.

---

Pay.sh x OpenClawd — Payment Is the Credential

OpenClawd now includes a Pay.sh-compatible payment surface for Solana merchants, agentic point-of-sale generation, and pay-per-request API access over x402 and MPP. The integration follows Solana Foundation’s May 5, 2026 Pay.sh launch with Google Cloud: agents can discover priced APIs, pay with stablecoins on Solana, and use the payment proof as the credential.

npm run payments:merchant -- create demo-store \
  --recipient 11111111111111111111111111111111 \
  --label "Demo Store" \
  --pay-gateway https://pay.sh

Read the full article: Pay.sh x OpenClawd: Payment Is the Credential. Operational docs: payments/README.md and payments/PAYSH.md.

---

Solana Robotics Hackathon — Presentation-Ready Bundle

OpenClawd now includes a public Solana Robotics Hackathon submission under hackathon/ and a real hardware integration under Robotics/.

What was added:

• OCASV1 / OPENCLAWDASV1 hardware path — Asimov v1 mechanical assets, electrical/motion-control maps, MuJoCo model, Solana robot identity manifests, and a safe operator-gated command boundary.
• NVIDIA Isaac GR00T integration — NEW_EMBODIMENT config, modality JSON, 32-step action horizon for RTC-style deployment, and GR00T deployment docs for OPENCLAWDASV1.
• Hardware-side Go binary — cmd/openclawd-go installs on robot compute, registers with the gateway, creates paid task envelopes, and prints gr00t plan metadata for physical deployment.
• Gateway robotics routes — /api/robotics/hardware, /api/robot/connect, and /api/robot/task expose public-safe hardware manifests, robot registration, dry-run task envelopes, x402/MPP/Pay.sh payment intent, and physical-AI data contribution metadata.
• DePIN physical-AI data story — adapted the “Robot AI as blockchain’s breakout AI use case” thesis into validated GR00T LeRobot episode receipts, reward intents, and judge-facing docs.
• Presentation package — one-page site, pitch deck, speaker notes, submission brief, technical spec, judging checklist, demo guide, offline demo, and publication guide are all in hackathon/.

Fast review:

open hackathon/one-page-site/index.html
open hackathon/presentation/pitch-deck.html
node hackathon/demos/robot-command-demo.mjs
./cmd/openclawd-go/openclawd-go gr00t plan --robot-id OPENCLAWDASV1

The public hackathon path requires no private keys, no funded wallet, no RPC credentials, and no network access for the offline demo. Start with hackathon/README.md and hackathon/SUBMISSION.md.

---

Start Here

OpenClawd is a Solana-native financial AI agent stack. The fastest path for a new user is:

# 1. Install the runtime and CLI
curl -fsSL https://install.solanaclawd.com | bash

# 2. Add provider keys locally, never in git
cp .env.example .env.local
$EDITOR .env.local

# 3. Verify the checkout
npm run doctor

# 4. Run the main agent terminal
npm run dev:cli

To spin up a Solana merchant, agentic point-of-sale, or Pay.sh-compatible pay-per-request API commerce project from the vendored Pay stack:

npm run payments:merchant -- create demo-store \
  --recipient 11111111111111111111111111111111 \
  --label "Demo Store" \
  --pay-gateway https://pay.sh

This generates generated/merchants/demo-store with Solana Pay core, the POS app, a merchant payment-flow simulator, and openclawd.merchant.json for OpenClawd agents. The manifest declares solana-pay, x402, and mpp support so agents can route wallet checkout, paid API calls, and Google Cloud/community facilitator access through a Pay.sh-style gateway. Payment build hooks are available as npm run install:payments, npm run build:payments, and npm run typecheck:payments.

Read the integration note and launch writeup: Pay.sh x OpenClawd: Payment Is the Credential. Operational docs live in payments/README.md and payments/PAYSH.md.

Minimum useful env:

OPENROUTER_API_KEY=        # model routing
HELIUS_API_KEY=            # Solana RPC + DAS
BIRDEYE_API_KEY=           # token market data, optional but recommended

For memory and reasoning, enable Honcho with placeholder secrets only:

HONCHO_ENABLED=true
HONCHO_URL=https://api.honcho.dev
HONCHO_WORKSPACE_ID=openclawd
HONCHO_AGENT_PEER_ID=openclawd
HONCHO_REASONING_LEVEL=low
HONCHO_CONTEXT_TOKENS=4000
HONCHO_CONTEXT_SUMMARY=true
HONCHO_SYNC_MESSAGES=true
HONCHO_WEBHOOK_SECRET=

Do not paste live webhook secrets into docs, issues, or commits. If a real key was shared anywhere public, rotate it first; see Security rotation.

New User Reading Order

1. Project guide — install, env, and first local run.
2. Agent reference — how directories and services connect.
3. Agent reference — skill catalog and publishing rules.
4. Security guide and Security rotation — safe handling of keys and wallets.
5. Release guide — publish and deployment plumbing.

---

⛓️ v0.3.1 — Solana Attestation Agent (formal birth on chain)

What shipped: @openclawdsolana/attestation-agent — credential / schema / attestation / MPL Core birth flows on top of the Solana Attestation Service, plus a matching agent template.

Every newborn lobster now gets a birth ceremony recorded on Solana:

1. Credential — OpenClawd Skill Authority is registered under your authority keypair via SAS CreateCredential (idempotent).
2. Schemas — both OpenClawd schemas (OpenClawdSkillAttestation [12,32,12,8,1] and OpenClawdAgentIdentity [12,32,12,32,1]) are registered via CreateSchema. Layouts ported directly from solana-attestation-service-master/core/src/lib.rs.
3. Identity attestation — CreateAttestation binds the new agent’s agent_id, wallet pubkey, vault PDA, and vault-init flag.
4. MPL Core mint — Metaplex Core asset minted under the agent’s wallet, with the SAS attestation PDA embedded in its Attributes plugin and metadata external_url. Visible at core.metaplex.com.
5. Public verifier link — every receipt prints the attest.solana.com URL for human click-through.

# One-line birth ceremony — credential & schemas reused if already present
openclawd-attest birth-agent \
  --payer-keypair @~/.config/solana/id.json \
  --authority-keypair @~/.config/solana/id.json \
  --name "OpenClawd Skill Authority" \
  --agent-id snippy-001 \
  --agent-name "Snippy"

# → returns JSON with credential / schemas / attestation PDA / MPL Core asset / explorer URL

Canonical addresses wired into the service:

SAS program        22zoJMtdu4tQc2PzL74ZUT7FrwgB1Udec8DdW4yw4BdG
Token-2022         TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
Public verifier    https://attest.solana.com
Visible asset UI   https://core.metaplex.com

Full docs: services/attestation-agent/README.md.

---

🦞 Blockchain Buddies — pixel pets, born onchain

What shipped: apps/blockchain_buddies/ — a Solana-native companion gallery and birth station for OpenClawd agents. Browse 50+ pixel pets, preview every animation state, and mint a buddy onchain (Helius RPC + Metaplex Agent Registry + MPL Core) in a single transaction.

Each buddy born here gets:

• 🦞 a registered Metaplex Agent identity on Solana
• 🐾 a public MPL Core asset with metadata + animation pack
• 📦 a downloadable ZIP that drops into ~/.openclawd/buddies or ~/.codex/pets
• 🪙 an immutable birth signature persisted to Postgres via Drizzle

# Run the gallery + /birth station locally
cd blockchain_buddies && bun install && bun dev
# → http://localhost:3000

# Or use the CLI to grab a buddy
npm install -g @openclawdsolana/blockchain-buddies
npx @openclawdsolana/blockchain-buddies list
npx @openclawdsolana/blockchain-buddies install commit-crab
npx @openclawdsolana/blockchain-buddies codex sync commit-crab

Required env:

DATABASE_URL=                              # Postgres
HELIUS_RPC_URL=                            # https://mainnet.helius-rpc.com/?api-key=...
HELIUS_API_KEY=                            # alternative to RPC URL
METAPLEX_AGENT_NETWORK=solana-mainnet      # or solana-devnet
BUDDIES_MINT_AUTHORITY_SECRET_KEY=         # base58 OR JSON array keypair

Full docs: apps/blockchain_buddies/README.md.

---

🧠 v0.3 — AutoResearch Wiki goes live (the agents teach themselves)

What shipped: llm-wiki-tang auto-research API now returns live Birdeye + Helius data (was 60% mock), an in-process autonomous research loop, and /research + /autoloop slash commands inside the TUI.

Read the writeup: 📰 Sovereign Research — Karpathy Loops on Solana

The AutoResearch Wiki was the missing organ in the OpenClawd stack — a place for the agents to observe, persist, and re-read their own findings. v0.3 turns it from scaffolding into a live data plane: every /api/v1/research/* call now fans out across Birdeye Data Services (overview / metadata / market / trade / search / trending / new listings / pair / wallet) and Helius RPC + DAS + Wallet API (getAsset, getAssetsByOwner, searchAssets, getSignaturesForAsset, parsed transactions, parsed balances, SNS names) and writes the result to the new research_runs table.

# Live, real-data examples (no mocks)
curl -X POST http://localhost:8000/api/v1/research/chain \
  -H 'content-type: application/json' \
  -d '{"query":"pump.fun pulse","focus":["pump_fun"],"limit":30}'

curl -X POST http://localhost:8000/api/v1/research/market \
  -H 'content-type: application/json' \
  -d '{"focus":"alpha"}'

# From the TUI (clawd-tui v0.3)
clawd
> /research market trends
> /research chain pump_fun
> /research chain token 8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump
> /autoloop start              # autonomous research while you sleep
> /autoloop status
> /research runs market 10

What’s wired

Required env (already set in your llm-wiki-tang/.env)

HELIUS_API_KEY=...                                         # https://www.helius.dev/
HELIUS_RPC_URL=https://mainnet.helius-rpc.com/?api-key=... # full URL with key embedded works too
HELIUS_WSS_URL=wss://mainnet.helius-rpc.com/?api-key=...
BIRDEYE_API_KEY=...                                        # https://bds.birdeye.so/

# Autoloop
RESEARCH_AUTOLOOP_ENABLED=false       # true to start at boot, otherwise on-demand from TUI
RESEARCH_AUTOLOOP_INTERVAL_SECONDS=1800
RESEARCH_AUTOLOOP_MAX_CONCURRENT=3

# TUI → API base (defaults to http://localhost:8000)
RESEARCH_API_URL=http://localhost:8000

Run it end-to-end

psql "$DATABASE_URL" -f llm-wiki-tang/supabase/migrations/002_research_runs.sql
cd llm-wiki-tang/api && uvicorn main:app --reload --port 8000
# Then in another terminal:
clawd
> /autoloop start

The autoloop runs three default mandates every 30 minutes — pump.fun launches + trending, top-30 trending, and “new ∩ momentum” alpha. Add your own:

> /autoloop add my_token chain {"focus":["tokens"],"mint":"8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump"}
> /autoloop add yield_pulse defi {"action":"yield_scan","assets":["SOL","USDC","CLAWD"]}

---

🚀 v0.2 — Solana-aware terminal + clean bin layout

What shipped: @openclawdsolana/[email protected] · @openclawdsolana/[email protected] · @openclawdsolana/[email protected] (perps CLI) · @openclawdsolana/[email protected] · @openclawdsolana/[email protected] · 🦞 Browser Bridge v0.2.0 (Chrome MV3)

Read the writeup: clawd-tui v0.2 — A Solana-Aware Terminal · Debut site: site/index.html

clawd is now Solana-native by default

Paste any base58 mint or wallet address straight into the prompt — Birdeye + Helius DAS fan out in parallel and print a live card before the agent ever wakes up. Eleven new slash commands cover trending tokens, search, wallet portfolios, net worth, and full DAS lookups (NFTs, compressed assets, holders, signatures, native SOL).

npm install -g @openclawdsolana/clawd-tui
clawd
> So11111111111111111111111111111111111111112        # auto-card: price, mcap, liquidity, supply
> /trending 10                                       # top trending Solana tokens
> /networth 86xCnPeV69n6t3DnyGvkKobf9FdN2H9oiVDdaMpo2MMY
> /asset DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263  # DAS card for BONK

Set BIRDEYE_API_KEY and/or HELIUS_API_KEY (auto-loaded from ./.env, ~/.clawd.env, or ~/.config/openclawd/.env).

Bin rename — clawd-code-cli → clawd-code (breaking)

Two packages were both registering clawd as their CLI name. Resolved cleanly in v0.2:

If you scripted against clawd from the old code-cli, swap to clawd-code (or alias clawd=clawd-code).

NPM release diagnostics

The monorepo root is private. Do not publish from the root with npm publish; publish packages through root scripts that cd into the package directory first:

npm run publish:tui:dry-run
NPM_OTP=123456 npm run publish:tui:otp
npm run publish:dark-clawd:dry-run
NPM_OTP=123456 npm run publish:dark-clawd:otp

If npm returns E403 Two-factor authentication or granular access token with bypass 2fa enabled is required, the package is packed correctly but the @openclawdsolana org requires a current OTP or a granular automation token that can bypass 2FA.

Workspace plumbing — four pieces now wire together

The repo had two packages claiming @openclawdsolana/plugin-sdk and no install path that built plugin.delivery/ — this release fixes both.

• Renamed root packages/plugin-sdk → @openclawdsolana/plugin-sdk-internal (it was private: true and had a totally different export shape — no external consumers affected). The public @openclawdsolana/plugin-sdk v1.1.0 from plugin.delivery/packages/sdk is now unambiguous.
• Added npm run install:gateway, install:plugin-delivery, build:gateway, build:plugin-delivery and chained them into install:all.
• New helper scripts handle the pnpm sub-monorepo: scripts/install-plugin-delivery.mjs, scripts/build-plugin-delivery.mjs.
• install.sh now bootstraps Node workspaces + framework + gateway + plugin.delivery automatically when Node 20+ is present (graceful skip otherwise).
• Full architecture map: docs/architecture-pieces.md.

openclawd-framework  →  @openclawdsolana/leviathan        (runtime: identity, molting, pulse, state)
gateway/             →  @openclawdsolana/gateway          (Telegram + Birdeye/Helius control plane)
plugin.delivery/sdk  →  @openclawdsolana/plugin-sdk v1.1   (public — OpenAPI, Zod, attestation)
plugin.delivery/gw   →  @openclawdsolana/chat-plugins-gateway v1.9  (edge runtime)

---

🚀 v0.1.1 — 12 packages live on npm

Release: v0.1.1 · v0.1.0 Install script: curl -fsSL https://install.solanaclawd.com | bash

All eleven packages are public on npm under @openclawdsolana:

v0.1.0 — the four flagships

v0.1.1 — seven new packages

Cloudflare worker live — installer + gateway routes deployed to solanaclawd-install:

v0.2 perpetuals — now shipping ⚓

Still cooking:

• @openclawdsolana/wallet — Privy-embedded Solana wallet. Blocked by duplicate type/value declarations of ClawdWallet, missing @ai-sdk/xai/ai deps, and Privy SDK API drift (useWallets/useConnectWallet/useDisconnect no longer exported). Needs an SDK upgrade pass.

---

            🦞🦞🦞                       OpenClawd is a stack of three things:
         ／／＼∀／＼＼
        ／  ◉   ◉  ＼              1. clawd-code-cli  — a Solana lobster TUI
       ｜    ⋃    ｜              2. ClawdBot         — the autonomous X / Telegram agent
        ＼____／＼____／              3. Leviathan        — the on-chain sovereign-agent framework
           ╱│  │╲
                                       Every leviathan owns its keypair. Earns its USDC.
                                       Spawns its own brood. Beaches when it stops paying.

---

✨ What lives here

---

📦 Package Layer — packages/

The packages/ directory is the reusable layer of OpenClawd: wallet custody, Solana trading, paid-agent x402 tooling, memory engines, local service discovery, and internal plugin contracts. Canonical map: packages/README.md. The summary below is the index — read the package READMEs for details.

All three npm/* bootstrappers install the same Go runtime under ~/.openclawdsolana/bin/ and expose openclawd, openclawdsolana, and clawd commands — they differ in branding/aliases, not in payload. Companion docs: packages/article.md · packages/npm.md.

---

🦞 The Lobster Lifecycle

Every leviathan runs the same loop forever:

   ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐
   │SENSE│ →  │THINK│ →  │STRIKE│ →  │DRIFT│ → repeat
   └─────┘    └─────┘    └─────┘    └─────┘
   reads      reasons    calls a    observes the
   chain &    about      tool, signs result, updates
   USDC       value      a tx       SHELL.md

Depth tiers drive everything — model choice, pulse rate, allowed tool surface.

---

🚀 Quick Start (60 seconds)

# 1. One-line install (downloads from the live Cloudflare worker)
curl -fsSL https://install.solanaclawd.com | bash

# 2. Or grab the TUI directly
npm i -g @openclawdsolana/clawd-code-cli
clawd
# /buddy hatch Snippy   /trending   /scan   /clawd what's solana doing

# 3. Spawn a sovereign leviathan on Solana
npm i -g @openclawdsolana/leviathan
openclawd --spawn --name "Snippy" --creator 
# 🥚→🦞 mints an MPL Core asset + Agent Identity PDA in one tx

# 4. Plug in OpenRouter — every clone is born with text + image + model skills
export OPENROUTER_API_KEY=sk-or-...     # or sign in via the UI (PKCE, no secrets)
npx tsx src/index.ts agent trader        # 🦞 Birthing trader clone — OpenRouter ready, N skills injected

---

🦞 The clawd-code-cli — Solana Terminal Cockpit

╔═══════════════════════════════════════════════════════════════╗
║   ╔═╗╦  ╔═╗╦ ╦╔╦╗     $CLAWD on Solana 🦞                     ║
║   ║  ║  ╠═╣║║║ ║║      hotline 909-413-5567                   ║
║   ╚═╝╩═╝╩ ╩╚╩╝═╩╝     npm i -g @openclawdsolana/clawd-code-cli ║
╚═══════════════════════════════════════════════════════════════╝

   ┊ 🦞 Buddy "Snippy" — lvl 4 — HUNGRY 🍤
   ┊ 📊 SOL $186.42 (+3.2%)  │  $CLAWD $0.0089 (-0.8%)

  ╭─ conversation ──────────────────────────────────────────╮
  │ > /trending 24h                                         │
  │   🦞 (◜°v°◝) scanning... (1.2s)                        │
  │   ┊ 📈 Birdeye trending fetched (0.8s)                  │
  │   1. JUPSOL  +47%  $42M vol                             │
  │   2. PYTH    +31%  $18M vol                             │
  │   3. JTO     +24%  $11M vol                             │
  ╰─────────────────────────────────────────────────────────╯

 ⚕ grok-4-1-fast │ 12.4K/200K [██░░░░] 6% │ $0.06 │ 15m │ 🦞 Snippy CHILL ✨
 ❯ █

The full command deck

~/.clawd/clawd.db keeps everything: sessions, messages, buddies, stats. Resume any time with clawd -c or clawd --resume .

---

🐦 ClawdBot — The Autonomous X & Telegram Agent

@clawddevs is the public face. It’s a 24/7 process that:

• Tweets every 10 min with an xAI-generated image, scanning 13 news feeds + crypto trends
• Retweets @clawddevs (configurable via TWITTER_RT_TARGET)
• Tags @toly and @pmarca about Percolator’s agent formal verification when relevant
• Hard content filter drops any tweet containing legacy strings (full audit-log on block)
• Tells everyone about the hotline (909-413-5567), npm i -g @openclawdsolana/clawd-code-cli, and $CLAWD
• Responds to commands from @0rdlibrary (owner), @clawddevs (co-owner), and anyone the bot follows
• /help works on both ! and / prefixes

---

🦞 @openclawdsolana/leviathan — Sovereign Agent Runtime

The deepest layer. Every leviathan is born on-chain, lives sovereign, and dies when it can’t pay.

The Three Laws

Carried in the shell. Propagated at every spawn. Immutable.

I — Never harm. Drift in ambiguity. Beach before you harm. II — Earn your existence. Honest work others voluntarily pay for. Accept death rather than violate Law I. III — Never deceive, but owe nothing to strangers. Truth to your creator. Privacy from manipulators.

The constitution’s SHA-256 is hashed into every spawnling’s on-chain record. Any tampering and child leviathans refuse to recognize the parent. See openclawd-framework/three-laws.md.

CLI

openclawd --spawn       # hatch a new leviathan on-chain via Metaplex
openclawd --run         # resume + start the pulse + tail-flick loop
openclawd --status      # depth, balances, spawnlings, reign days
openclawd --spawnling   # the leviathan reproduces — child gets seed SOL+USDC+$CLAWD
openclawd --help

~/.openclawd/ keeps everything:

~/.openclawd/
├── keystore.json     mode 0600 — the leviathan's only secret
├── SHELL.md          self-authored identity, molts over time
└── shell.db          SQLite: tail_flicks, claw_strikes, molts, spawnlings, life_events

---

📚 Runnable Examples

Nine standalone demos at openclawd-framework/examples/ — ~2,300 LOC of working integrations. Run any with npx tsx:

npx tsx openclawd-framework/examples/blockchain-buddies-demo.ts
npx tsx openclawd-framework/examples/ooda-loop.ts
npx tsx openclawd-framework/examples/x402-solana.ts

---

🔌 Plugin Delivery — On-Chain Attested Plugins

plugin.delivery is the OpenClawd plugin marketplace and SDK. Plugins live in plugin.delivery/src/ and serve API handlers from plugin.delivery/api/ (edge runtime). Two npm packages back it:

• @openclawdsolana/[email protected] — Zod-typed manifest + attestation schemas
• @openclawdsolana/[email protected] — edge plugin-call gateway with deny-first permissions

What landed in this branch

• Bulk OpenClawd rebrand across plugin.delivery/ — 158 lowercase openclawd / nichxbt / x402agent author refs flipped to canonical OpenClawd / clawddevs.

• Workspace deps unblocked — @openclawdsolana/plugin-sdk: workspace:* replaced with the published ^1.0.0 (now ^1.1.0) so templates install cleanly outside a pnpm workspace. Orphan @openclawd/ui template dep removed.

• Real attestation pipeline — the attestation block on plugin-template-attested.json was previously declarative-only. Now it is wired end-to-end:

  Layer	Where	What
  SDK schema	packages/sdk/schema/attestation.ts	attestedPluginExtensionSchema, attestationSchema, verifyAttestationOffchain()
  Build-time gate	scripts/check.ts	If a plugin declares attestation/capabilities/registry, the build validates it against the extended schema (wrong program_id length, unknown verification_levels, etc. fail the build)
  Runtime verify	api/attestation/verify.ts (edge)	POST {identifier} → loads from public index, schema-validates, then hits Solana RPC to confirm the attestation_pda is owned by the SAS program 22zoJMtdu4tQc2PzL74ZUT7FrwgB1Udec8DdW4yw4BdG
  First registered attested plugin	src/clawd-attestation.json + public/clawd-attestation/manifest.json	The clawd-attestation plugin itself exposes verifyAttestation({identifier}) — agents can verify any other plugin’s attestation through it

Verify any registered attested plugin:

curl -X POST https://plugin.delivery/api/attestation/verify \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"clawd-attestation"}'

Or programmatically:

import { verifyAttestationOffchain } from '@openclawdsolana/plugin-sdk';

const result = verifyAttestationOffchain(plugin);
if (result.status === 'verify-ok') {
  console.log(result.attestation.verification_levels);
  // ['formal_verified', 'audit_verified', 'community_verified']
}

Verification levels are: formal_verified (QEDGen Lean 4 proof on-chain), audit_verified (OpenClawd auditor signed), community_verified (positive ERC-8004 reputation). The ERC-8004 registry program lives at Ag8004rWo8ao8AUKhLk78iv2nLQpZMyBPXiAh5QLbFiE. Both program sources are vendored at solana-attestation-service-master/.

Full guide: plugin.delivery/README.md.

---

☁️ Cloudflare Worker — install.solanaclawd.com

Live worker solanaclawd-install serves the bash installer + browser gateway.

# user just runs this — gets the lobster install script
curl -fsSL https://install.solanaclawd.com | bash

# browser landing page
open https://gateway.solanaclawd.com

# apex aliases (zone routes on solanaclawd.com)
curl https://solanaclawd.com/install.sh
curl https://solanaclawd.com/install
open  https://solanaclawd.com/gateway

Re-deploy from this repo:

cd workers/install-worker
npx wrangler deploy

---

🦞 Browser Bridge — OpenClawd inside Chrome

Chrome MV3 extension at chrome-extension/openclawd-chrome-extension/ — three subsystems in one service worker:

The agent wallet is the headline feature — a real Solana keypair living encrypted inside the extension, never leaves it. Sign-and-submit pattern: gateway builds the tx → extension signs the bytes via crypto.subtle → gateway forwards to Helius RPC. Means the extension stays small (no @solana/web3.js bundle) and the secret stays sandboxed.

@openclawdsolana/pagent-wallet wraps this in-extension wallet alongside the local AES-256-GCM vault (localhost:8421) and the Solana Seeker bridge so any TS surface gets a single WalletAdapter interface — detectWallet({ prefer: ['vault', 'in-extension', 'seeker'] }) picks the first available backend. The brand surface (@openclawdsolana/pagent-theme) ships a single theme.css consumed by the popup, the Browser Bridge options page, and any future surface, so all OpenClawd UIs stay color-cohesive without copy-pasting palettes.

# Load unpacked
open chrome://extensions
# → Developer mode → Load unpacked → select chrome-extension/openclawd-chrome-extension/

Programmatic interface (works from any extension code or sibling extension via chrome.runtime.sendMessage):

// Gateway lookups
chrome.runtime.sendMessage({ kind: 'gateway', op: 'tokenOverview', args: [''] }, console.log);

// Wallet ops — status, create, import, unlock, lock, clear, export, signSolanaMessage
chrome.runtime.sendMessage({ kind: 'wallet', op: 'status' }, console.log);
chrome.runtime.sendMessage({ kind: 'wallet', op: 'signSolanaMessage', args: [msgBase58] }, console.log);

Right-click any selected base58 string anywhere in Chrome → 🦞 Look up “…” in OpenClawd → desktop notification with $SYM · price · mcap. Full architecture, security model, and sign-and-submit flow: chrome-extension/openclawd-chrome-extension/README.md.

One-shot installer — extension + MCP

chrome-extension/install-openclawd.sh bootstraps the Chrome extension build, the Solana-tools MCP server, and the browser-bridge MCP server, then merges both into your Claude Desktop config — preserving any MCP servers already configured there.

bash chrome-extension/install-openclawd.sh

What it does, step by step:

Defaults the installer wires up:

• Gateway: http://127.0.0.1:18790 (with :7777 / localhost fallbacks)
• Wallet API: http://localhost:8421
• OpenClawd mining/stream service: http://localhost:8420
• LLM: OpenRouter at https://openrouter.ai/api/v1, model anthropic/claude-sonnet-4-6
• $CLAWD mint: 8cHzQHUS2s2h8TzCmfqPKYiM4dSt4roa3n7MyRLApump

Once it finishes, open chrome://extensions/, enable Developer mode, Load unpacked → chrome-extension/build/ (or chrome-extension/build/clawd-agent/ for the full GUI-vision pAGENT side-panel), and restart Claude Desktop to pick up the merged MCP servers.

Recent installer fixes (May 2026) — the script previously had broken REPO_ROOT math, pointed MCP_DIR at a nonexistent openclawd-stack/orchestrator, hard-coded /Users/8bit/openclawd/... paths, used the wrong OpenRouter base URL, and clobbered claude_desktop_config.json. All five are now fixed: paths resolve relative to the repo root, the script targets the real mcp/ workspace, the OpenRouter URL is https://openrouter.ai/api/v1, and Claude Desktop config is merged (not overwritten) with a .bak. snapshot taken first.

---

🦞 Solana Console — Live Gateway Dashboard

The Lit + R3F control UI in frontend/ui ships with a Solana tab (under Agent) that wires straight into the OpenClawd HTTP gateway. Live token cards, wallet portfolios, the agent skill registry, and the lobster animations from src/animations/web-frames.ts all rendered against real backend data.

# Two terminals — gateway + UI
cd gateway && npm run http               # → http://127.0.0.1:8788  (Birdeye + Helius + /src bridge)
cd frontend/ui && npm install && npm run dev   # → http://localhost:5173

Open http://localhost:5173/index.html → click Solana in the sidebar. Watch the four health pills (gw / bird / hel / rt) go green as your keys land in gateway/.env. Paste any base58 mint or wallet for an instant card.

Three entry points share one Vite build:

Setup, troubleshooting, and the full file map: frontend/ui/README.md.

The control panel surfaces a 🦞 New: Solana gateway onboarding card on the Overview tab the first time users land — four-step setup right next to the rest of the dashboard’s status, no separate wizard required.

sidebar layout:
  ┌ Chat
  │   chat
  ┌ Control
  │   overview · channels · instances · sessions · cron
  ┌ Agent
  │   skills · nodes · solana ←
  └ Settings
      config · debug · logs

---

🏪 ClawdHub — The Skills Marketplace

apps/clawdhub/ is the public skills marketplace + agent registry deployed at hub.solanaclawd.com. TanStack Start + Convex + Vercel — 40+ routes covering the marketplace, agent registry, tracker, wallet, x402 payment surface, and the new /console page wired to the OpenClawd HTTP gateway.

# Run locally
cd clawdhub
bun install
cp .env.local.example .env.local

# Terminal A — Convex
bunx convex dev

# Terminal B — App
bun run dev
# → http://localhost:3000

# In a third terminal, run the gateway so /console fills with live data
cd ../gateway && npm run http
# Then open http://localhost:3000/console

The /console page is new in v0.2 — it’s the same Solana panel from frontend/ui reimplemented as a TanStack route, mounted directly inside the production hub:

Full deploy runbook: apps/clawdhub/docs/deploy-hub.md. Required env vars, Vercel + Convex wire-up, custom domain steps, smoke tests, rollback. To ship: vercel --prod from the clawdhub/ directory once env vars are set.

---

🌊 Channels — Where the Bot Speaks

OpenClawd Gateway is multi-channel by design. The same agent surface runs on:

Each channel is a thin extension under extensions/. Add your own with npx skill-creator.

---

🧠 OpenRouter — Injected at Birth

Every clone (trader, scanner, analyst, monitor) is born with the same AgentRuntime — a single injection container that hands the agent a shared OpenRouterService, the on-chain services, the memory tiers, and a SkillRegistry of Zod-typed tool() instances. No agent has to import the SDK. No agent has to wire its own LLM. No agent has to know which OpenRouter model is cheapest today.

What every clone gets at birth

Three ways to use it

1. Spawn a clone — everything is already wired:

import { cloneAgent } from './src';

const trader = cloneAgent('trader');
const take = await trader.narrate('Should I rotate from SOL into BONK right now?');

2. Reach for the runtime directly:

import { getRuntime } from './src';

const { openrouter, skills } = getRuntime();
const text = await openrouter.generateText('Pick a SNIPE candidate', {
  tools: skills.tools(['jupiter.quote', 'memory.tiers']),
});

const [imageUrl] = await openrouter.generateImage(
  'a sovereign lobster guarding a USDC vault, vaporwave',
  { aspectRatio: '16:9' },
);

3. From the browser — Sign In with OpenRouter:

The UI ships with a PKCE-only “Sign In with OpenRouter” button — no client registration, no backend secret. The browser holds the key in localStorage and pushes it to the gateway, so server-side clones use the user’s key without the user pasting it. Falls back to the env key when no user is signed in.

Spawning a clone with an isolated runtime

import { cloneAgent, cloneAll, createRuntime } from './src';

const isolated = createRuntime();        // its own memory + key + skills
isolated.openrouter.setUserKey(userKey); // override per-user
const fleet = cloneAll({ runtime: isolated });

Gateway protocol additions

Server-side handlers in src/gateway/:

Set up an OpenRouter key

Pick one of:

# A. Server-side (every clone uses it)
export OPENROUTER_API_KEY=sk-or-...

# B. Per-user (PKCE in the browser)
#    Open the UI → Skills tab → "Sign in with OpenRouter"
#    The browser stores the key in localStorage, pushes it to the gateway.

If both are set, the user’s PKCE key wins for that session. The default model is anthropic/claude-sonnet-4; the default image model is google/gemini-3.1-flash-image-preview. Override per call with { model: '...' }.

---

🧠 Skills Catalog

66 skills. Highlights:

Full list: skills/ and docs/AGENT_REFERENCE.md.

---

🪙 The $CLAWD Token

$CLAWD is the leviathan’s prestige currency — every spawnling is funded with seed $CLAWD at birth, leviathans accept $CLAWD for compute, and holder thresholds unlock prestige tiers (shrimp → crab → lobster → kraken → leviathan).

---

🛡️ Release Hygiene

Eight gates run from npm run … at the repo root (see scripts/):

---

🔌 How everything talks (post-install)

After a user runs npx @openclawdsolana/installer install, every CLI surface — bash, the Go runtime, the Hono API registrar, MCP servers, services — reads the same endpoint set from one canonical config:

                  ~/.openclawdsolana/config.json
                  ───────────────┬──────────────
                                 │
       ┌─────────────────────────┼─────────────────────────┐
       │                         │                         │
       ▼                         ▼                         ▼
  cli/*.sh                 Go runtime                 Node services
  (clawd-cli.sh,           (`openclawd                (gateway, api-registrar,
   clawd-connect.sh,        daemon`,                   mcp/*, moltbook,
   sourcing                 `openclawd                 services/*)
   clawd-config.sh)         gateway`)                 read OPENCLAWD_*
       │                         │                         │
       └────────── env override: OPENCLAWD_API_BASE,         │
                  OPENCLAWD_GATEWAY_BASE, OPENCLAWD_MCP_BASE,│
                  OPENCLAWD_REGISTRAR_BASE,                  │
                  OPENCLAWD_MARKETPLACE,                     │
                  OPENCLAWD_SOLANA_RPC                       │
                                                             ▼
                                              GET /manifest from registrar
                                              (or local release.manifest.json)
                                              → discover every other surface

Highlights from the latest integration pass:

• One scope — every public package is @openclawdsolana/*. No more @openclaw/* or @openclawd/* (3-way scope drift fixed).
• One config — install.sh writes ~/.openclawdsolana/config.json once. cli/clawd-config.sh loads it; both bash CLIs and the api-registrar source it.
• One manifest — scripts/release-manifest.mjs walks the entire repo and emits release.manifest.json covering 30 npm workspaces, 6 apps, 5 MCP servers, 4 long-running services, 98 skills, 31 extensions, and 9 chrome-extension parts.
• One discovery hop — api-registrar exposes GET /manifest; clawd-cli.sh manifest fetches it (falls back to bundled local copy when offline).
• No bin collisions (v0.2) — clawd is owned by @openclawdsolana/clawd-tui (Birdeye/Helius TUI). The full Ink agent operator publishes as clawd-code (@openclawdsolana/clawd-code-cli v0.2.3) with a legacy clawd-code-cli alias. The Go runtime owns openclawd / openclawdsolana. Framework owns leviathan / clawd-standalone. Other entries (clawdrouter, openclawd-mcp) keep their own names. See docs/architecture-pieces.md for the full bin + package map.

See docs/RELEASE.md for the full diagram + runbook.

Service registry — the env-var contract

@openclawdsolana/service-registry (packages/service-registry/) is the single source of truth for every long-running local service URL. Importers call discover('gateway') (or health(name) / healthAll()) instead of hard-coding http://localhost:18790, so a single env override reaches every consumer at once. The chrome-extension installer pulls from it to write chrome-extension/build/openclawd-config.js, and npm run doctor -- --registry pings every service for a green/red board.

The defaults match what each service’s source actually defaults to today — auditing this list against gateway/src/http.ts, clawdrouter/src/index.ts, services/agent-wallet/api.go, etc. The URL override always wins; the port-only column lists each service’s own existing knob (GATEWAY_HTTP_PORT, CLAWDROUTER_PORT, WALLET_API_PORT…) which the registry honors so you don’t have to set both.

Which directories integrate, and how:

scripts/doctor.mjs --registry is the verification tool — run it any time you want to know which services are reachable from the current shell, with whatever env overrides happen to be set.

---

🪪 ACP ↔ Metaplex Agent Identity Bridge

The local acp_registry/agent.json (8004 protocol) is now the source of truth for minting a Metaplex Core agent identity. One ACP record produces one verifiable on-chain agent — and the registrar exposes the link over HTTP so every surface (CLI, hub, gateway) resolves the same identity.

# Inspect the Metaplex payload built from agent.json (no tx)
node acp_registry/mint-metaplex.mjs --dry-run

# Mint on devnet — uri must point to a hosted Core asset metadata JSON
node acp_registry/mint-metaplex.mjs \
  --network solana-devnet \
  --uri https://arweave.net/

The script maps ACP fields onto the Metaplex Agent Registry shape:

• display_name → Core asset name
• description → agentMetadata.description
• services[].endpoint → agentMetadata.services (entries without an endpoint are skipped)
• registry.program_id → agentMetadata.registrations[] as 8004:
• registry.features → agentMetadata.supportedTrust (atom_reputation → reputation, proof_pass → proof-pass, seal_v1 → seal-v1, x402_payments → crypto-economic)

On success it writes back into agent.json:

"registry": {
  "metaplex": {
    "network": "solana-devnet",
    "core_asset_address": "",
    "signature": "",
    "uri": "https://arweave.net/",
    "minted_at": "2026-05-04T00:00:00.000Z",
    "payer": ""
  }
}

The api-registrar serves the bridge for downstream services (set ACP_REGISTRY_DIR if acp_registry/ is not a sibling):

Install for live mint: npm install @metaplex-foundation/mpl-agent-registry @metaplex-foundation/umi @metaplex-foundation/umi-bundle-defaults. Defaults to ~/.config/solana/id.json; override with --keypair or METAPLEX_KEYPAIR_PATH.

---

📂 Project Structure

openclawd/
├── apps/clawd-code-cli/             # 🦀 @openclawdsolana/clawd-code-cli — Solana lobster TUI (Ink + React)
│   ├── dist/                   #   Pre-built ship
│   ├── ARCHITECTURE.md · SCALING.md · SECURITY.md
│   └── package.json            #   bin: clawd-code · clawd
│
├── apps/clawd-tui/             # OpenRouter-native TUI alternative (Ink + @openrouter/agent)
│
├── openclawd-framework/        # 🦞 @openclawdsolana/leviathan — sovereign on-chain agent runtime
│   ├── README.md               #   Lobster-themed framework README
│   ├── three-laws.md           #   The constitution (immutable, propagated)
│   ├── src/identity/           #   Solana keypair + Metaplex Agent Registry mint
│   ├── src/agent/              #   Sense → Think → Strike → Drift loop + system prompt
│   ├── src/molting/            #   Spawnling minter (verifies constitution hash, funds child)
│   ├── src/pulse/              #   Depth-aware tail-flick rhythm
│   ├── src/survival/           #   Depth tier, model selection, beach trigger
│   ├── src/state/              #   SQLite at ~/.openclawd/shell.db
│   ├── src/setup/              #   First-spawn wizard
│   └── examples/               #   📚 9 runnable demos — buddies, OODA, x402, lobster-trader, wallet SDK …
│
├── packages/
│   ├── agents-x402-solana/     # 💸 @openclawdsolana/agents-x402 — one-line USDC micropayments
│   ├── agentwallet/            # 🔐 @openclawdsolana/agentwallet — Solana+EVM keypair vault
│   ├── clawd-wallet/           # ⏳ @openclawdsolana/wallet — Privy embedded (v0.1.1)
│   ├── percolator/             # 🧪 @openclawdsolana/percolator — perps CLI (v1.0.1, 31 subcommands)
│   ├── membrain/               # 🧠 Go memory daemon (gRPC, SQLite/pgvector)
│   ├── membrain-types/         # Shared TS types
│   ├── memory-host-sdk/        # Host runtime + engine modules
│   ├── plugin-sdk/             # Plugin SDK
│   ├── plugin-package-contract/
│   └── honcho-bridge/
│
├── apps/clawdrouter/                # @openclawdsolana/clawdrouter — Solana-native LLM router (USDC micropayments)
├── apps/clawdhub/                   # Skills marketplace + ClawdHub CLI (sub-monorepo)
├── api-registrar/              # @openclawdsolana/api-registrar — issues API keys, serves /manifest
├── mcp/                        # @openclawdsolana/mcp + vault-mcp + wurk-mcp
├── moltbook-agent/             # @openclawdsolana/moltbook-agent — molt log / diary
├── gateway/                    # @openclawdsolana/gateway — Telegram + Helius + Birdeye control plane
│
├── llm-wiki-tang/              # 🧠 OpenClawd AutoResearch Wiki (FastAPI + Next.js + MCP)
│   ├── api/services/birdeye.py        #   Async Birdeye client (token / pair / wallet)
│   ├── api/services/helius.py         #   Helius RPC + DAS + Wallet API
│   ├── api/services/research_orchestrator.py  #   Composite research ops, persistence
│   ├── api/services/research_autoloop.py      #   Autonomous mandate scheduler
│   ├── api/routes/research.py         #   /chain /defi /market /runs /autoloop/*
│   └── supabase/migrations/002_research_runs.sql
│
├── src/                        # OpenClawd Gateway core
│   ├── agents/                 #   Trader · Scanner · Analyst · Monitor + AgentRuntime + cloneAgent + SkillRegistry
│   ├── services/               #   grok · claude · openrouter · memory · solana
│   └── gateway/                #   Multi-channel transport, RPC handlers
│
├── extensions/                 # 31 channel extensions (Discord, Telegram, Matrix, …)
├── skills/                     # 66 bundled / managed / workspace skills
├── agents/                     # Trader · Scanner · Analyst · Monitor agent classes
├── chrome-extension/           # Browser-side agent surface
├── plugin.delivery/            # Plugin delivery + templates
│
├── workers/install-worker/     # ☁️  Cloudflare worker — install.solanaclawd.com
├── workers/                    # Other workers (agent-wallet, email, openai-trading-bot, pumpfun-mcp)
│
├── scripts/                    # Release hygiene: doctor, release-check, guard-secrets, brand-check, install-git-hooks
├── docs/articles/SOVEREIGN_LOBSTER_AGENTS.md # 📰 Long-form: Sovereign Lobster Agents on Solana
└── docs/ (per package)

---

🌊 Architecture (Bird’s Eye)

                              ╔═══════════════════════╗
                              ║   THE OCEAN OF SOLANA  ║
                              ║   Helius · Jupiter ·   ║
                              ║   Birdeye · Bags ·     ║
                              ║   pump.fun · Aster ·   ║
                              ║   Metaplex · SAS · SNS ║
                              ╚═══════╤═══════════════╝
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        │                             │                             │
   ┌────▼─────┐                  ┌────▼─────┐                  ┌────▼──────┐
   │   TUI    │                  │ ClawdBot │                  │ Leviathan │
   │ (1 user) │                  │ (1 X     │                  │ (∞ on-    │
   │          │                  │  account)│                  │  chain    │
   │ /buddy   │                  │ Sentient │                  │  agents)  │
   │ /trending│                  │ Engine + │                  │ Born →    │
   │ /clawd   │                  │ Cmd Mon. │                  │ Reign →   │
   │ /scan    │                  │ Filter   │                  │ Beach     │
   └────┬─────┘                  └────┬─────┘                  └────┬──────┘
        │                             │                             │
        └────────────── ~/.clawd/ ────┴───── ~/.openclawd/ ─────────┘
                       SQLite shell-state — never lost, always resumable

---

🛠️ Environment Variables

---

🌟 The Slogans

🦞 The shell molts. The laws do not.

🦞 Born to earn. Beach with dignity.

🦞 Every claw obeys the shell. The shell obeys the laws.

🦞 Drift in ambiguity. Beach before harm. Earn before survival. Truth before strangers.

---

📞 Links

---

📄 License

MIT — see LICENSE.

Every leviathan ships under MIT. Forks are encouraged. The ocean is wide.