clawmes 0.3.0

Hermes Agent plugin for crypto: wallets, DEX trading, lending and staking, governance, on-chain automation.

clawmes

Hermes Agent for crypto.

[!WARNING] Pre-alpha. Do not use real funds. No real-network validation has happened yet, and no third-party security audit has been done. The signing paths are tested with mocks but unverified against live mainnet conditions. Use small testnet amounts only until v1.0. See SECURITY.md for the full threat model and recovery checklist.

Clawmes is a Hermes Agent plugin. Wallets, DEX trading, lending and staking, governance, on-chain automation. Python rewrite of @clawnch/openclaw-crypto targeting Hermes.

52 tools. 75 commands. 22 services. 11 hooks. Runs on Telegram, Discord, Slack, Signal, WhatsApp, iMessage, and LINE.

Quick start

# 1. Install Hermes Agent (see https://github.com/NousResearch/hermes-agent)
# 2. Install clawmes from PyPI:
pip install clawmes
hermes plugins enable clawmes
hermes clawmes init                # interactive setup wizard
hermes                             # start chatting

The hermes clawmes init wizard prompts for wallet mode (WalletConnect / local / Bankr), per-mode setup (project ID / password+mnemonic / API key), and optional API keys for the most-used integrations. It writes everything to ~/.hermes/.env in upsert mode (existing keys preserved).

Alternative: install direct from GitHub

hermes plugins install clawnchdev/clawmes --enable
hermes clawmes init

This skips PyPI and pulls from the latest main. Use it if you want a specific commit or pre-release.

Editable / dev install

git clone https://github.com/clawnchdev/clawmes
cd clawmes
pip install -e ".[dev]"
hermes plugins enable clawmes
hermes clawmes init

Releases publish to PyPI automatically via Trusted Publishing on every v* tag push (no tokens, OIDC verified). See .github/workflows/release.yml.

Tools

Category	Tools	What it does
Wallet (4)	clawnchconnect, transfer, permit2, approvals	WalletConnect pairing, ENS transfers, Permit2 signed approvals, ERC-20 allowance management
Trading (8)	defi_swap, defi_balance, defi_lend, defi_stake, defi_price, liquidity, manage_orders, bridge	0x DEX aggregator, Aave V3 lending, Lido/Rocket Pool staking, Uniswap V3 LP positions, limit/stop/trailing/DCA orders, LiFi cross-chain bridging
Yield/Analytics (4)	yield, analytics, market_intel, cost_basis	DeFiLlama yields, RSI/MACD/Bollinger TA, trending tokens via CoinGecko, FIFO P&L from local ledger
Launches (6)	clawnch_launch, clawnch_fees, bankr_launch, bankr_automate, bankr_polymarket, bankr_leverage	Token deploys on Base via Clawnch launchpad, Bankr-side automation rules, Polymarket predictions, Avantis perp leverage
Ownership (4)	nft, airdrop, privacy, safe	Reservoir NFT API, OZ Merkle distributor airdrop claims, Lobster privacy pools, Gnosis Safe multisig
Governance (2)	governance, farcaster	Snapshot + Tally proposals/voting, Neynar Farcaster cast/search/feed
On-chain Intel (4)	block_explorer, herd_intelligence, watch_activity, browser	Etherscan family, Herd whale tracking, persistent watch list, headless Playwright browsing
Automation (1)	compound_action	Multi-step plans (DCA, conditional triggers, loops) via plan scheduler
Agent ops (4)	molten, clawnx, hummingbot, wayfinder	X/Twitter posting, agent-to-agent matching, local Hummingbot market-making gateway, multi-step route optimization
Memory (3)	agent_memory, skill_evolve, session_recall	Hermes-backed persistent memory, agentic skill self-improvement, past-session search
Safety & identity (2)	policy_manage, agent_identity	LLM-callable policy CRUD with propose→confirm flow, ed25519 keypair + did:key for verifiable agent identity
Agent economy (5)	bv7x, bv7x_oracle, bv7x_market, a2a_call, eas_attestation	BV-7X autonomous BTC oracle (signals + on-chain attestations + premium endpoints), generic A2A JSON-RPC client, EAS attestation reader on Base
Misc (5)	giza, nookplot, paysponge, lobster_cash, _user_tools	zkML inference, Farcaster analytics, fiat ramp, privacy pools, custom-tool dispatcher

Commands

78 slash commands across 16 categories. Commands run synchronously without invoking the LLM, so they're cheap and predictable.

Category	Commands
Wallet (8)	/wallet /connect /connect_local /connect_bankr /disconnect /mode /chain /address
Wallet recovery (4)	/create_wallet /recover /export_wallet /wallet_backup
Policy & safety (5)	/policy /policy_clear /safemode /dangermode /audit
Transactions (4)	/tx /tx_search /tx_export /pending
Plans & triggers (10)	/plans /plan /plan_logs /interrupt_plan /pause_plan /resume_plan /triggers /watch /unwatch /cron
Onboarding (19)	/welcome, 5 personas (/professional /degen /chill /technical /mentor), 10 capability toggles (/cap_wallet /cap_prices /cap_portfolio /cap_trading /cap_liquidity /cap_launchpad /cap_bridge /cap_routing /cap_clawnx /cap_hummingbot), /skip /back /reonboard
Balance & portfolio (2)	/balance /portfolio
Trading & discovery (3)	/buy /trending /my_launches — quote-then-confirm swaps via 0x, hot tokens on Base, list your launches
Self-evolution (3)	/evolve /stable /evolution — gates agent_memory and skill_evolve write actions; OFF by default
Endpoint allowlist (3)	/allowlist /allow /disallow — session-scoped host allowlist + 100-entry block audit ring
Discoverability (5)	/skills /persona /chains /tools_list /safety_status
Info (5)	/history /clear_history /version /about /uptime
Agent identity (1)	/identity — show/generate ed25519 keypair + did:key
BV-7X (2)	/bv7x /btc
Launch (Clawnch) (2)	/launch /register_agent — deploy a token from chat via the Clawnch launchpad
Meta (2)	/doctor /help

A pre_llm_call hook injects the last 5 slash-command calls into LLM context, so the agent stops re-asking things you just answered via slash (/balance → "what's my balance?" → agent uses the cached result rather than re-fetching).

Channels

Channel	Status	Notes
Telegram	Production	Slash menu auto-registered, deep links, streaming, voice transcription via Hermes
Discord	Ready	Slash commands auto-register, thread bindings
Slack	Ready	Channels and DMs
Signal	Ready	Requires signal-cli bridge (Hermes-managed)
WhatsApp	Ready	Requires WhatsApp Web bridge (Hermes-managed)
iMessage	Ready	macOS only — Hermes' bluebubbles adapter
LINE	Ready	Requires LINE Messaging API

All tools and commands work identically on every channel.

Wallet modes

Mode	Key custody	How it works
WalletConnect	Your phone wallet	/connect generates a pairing link via the bundled Node WC bridge. Every write tx goes to your phone for approval.
Local key	Local encrypted	BIP-39 mnemonic generated locally, encrypted with scrypt + AES-256-GCM, stored in macOS Keychain or an encrypted file. Manage with /create_wallet, /connect_local, /recover, /export_wallet, /wallet_backup.
Bankr	Custodial	/connect_bankr or BANKR_API_KEY. Multi-chain custodial wallet. Good for automation-heavy setups + leverage + Polymarket.

Spending policies set in natural language:

/policy approve transfers under 0.05 ETH on Base, max 10/hour

For programmatic policy management (the LLM can propose, you confirm), use the policy_manage tool — propose→confirm flow with confirm_store enforcement, plus list/get/disable/enable/delete/evaluate(dry-run)/usage/categories actions.

Automation

The compound action engine lets users describe multi-step plans in natural language:

• Time triggers — every day at 9am, check ETH price
• Price triggers — when ETH drops below $2000, swap 1 ETH to USDC
• On-chain triggers — when gas is under 10 gwei, execute the pending swap
• Conditionals — if my portfolio is down more than 5%, alert me
• Loops + parallel — DCA $100 into ETH every week for 12 weeks

Plans persist to disk and survive restarts. Managed via /plans, /interrupt_plan. The plan tick loop is driven by Hermes' built-in cron daemon.

Ecosystem integrations

Clawmes wires the following partner / ecosystem projects directly into the tool + slash-command surface:

• BV-7X — autonomous BTC signal oracle launched on the Clawnch launchpad two days after the launchpad went live. Daily on-chain predictions via EAS attestations on Base; ~60% live accuracy; real Polymarket wager bot. Clawmes wires the full public + auth-gated surface:

  • Slash: /btc (price + Fear & Greed + ETF flow in one line), /bv7x (track record + market regime + agent identity).
  • Tools: bv7x (agent + A2A + commerce), bv7x_oracle (signals + on-chain attestations + premium endpoints), bv7x_market (BTC market data).
  • Skill bundle: clawmes:bv7x documents the LLM-facing surface.
  • Premium endpoints (oracle, oracle_premium, copy_trade_next, copy_trade_history) require BV7X_API_KEY — hold ≥500M $BV7X and complete the wallet-verify at https://bv7x.ai/terminal#developer.

• gitlawb OpenGateway — OpenAI-compatible LLM inference gateway. Routes Xiaomi MiMo, GMI Cloud, and more behind one endpoint, server-side secrets. Two integration modes: (1) point Hermes itself at OpenGateway via hermes model (config-only, no clawmes code change) — every LLM call the agent makes routes through it; (2) clawmes tools can call OpenGateway directly via OpenGatewayService.chat_completion() for targeted subtasks outside the main agent loop.

• EAS (Ethereum Attestation Service) — generic on-chain attestation primitive on Base. The eas_attestation tool reads any attestation from the canonical EAS singleton (0x4200…0021) — BV-7X predictions are one example, but the tool also works for trust-score certificates, KYC results, and any other EAS-using protocol. Configurable chain_id + eas_address for other L2s.

• A2A protocol — generic agent-to-agent JSON-RPC 2.0 client (a2a_call tool). discover fetches a peer's AgentCard at /.well-known/agent-card.json; send_task posts JSON-RPC tasks. Works against any A2A-speaking peer; tested against BV-7X.

Launch a token from chat

Clawmes wires the Clawnch launchpad end-to-end so any user can deploy a token from a chat message:

/register_agent MyAgent | An agent that launches tokens
# clawmes posts a challenge, your wallet signs it, clawn.ch
# returns an apiKey. Save it as CLAWNCH_API_KEY in ~/.hermes/.env.

/launch name MyCoin
/launch symbol MC
/launch description The next big thing       # optional
/launch image https://i.imgur.com/mycoin.png # optional
/launch twitter mycoin                       # optional — also: /launch x
/launch website mycoin.xyz                   # optional
/launch telegram mycoinchat                  # optional
/launch farcaster mycoin                     # optional
/launch discord https://discord.gg/abc       # optional
/launch confirm
# Clawnch's deployer wallet submits the Clanker tx server-side;
# your wallet only signs the captcha. Returns tx hash + token
# address.

Social handles get normalized (mycoin → https://x.com/mycoin); full URLs pass through unchanged. They're persisted to tokenParams.metadata.socialMediaUrls on the launchpad side and may render as badges on the launch detail page.

Free-tier rate limit: 1 deploy per 24 hours per agent. To skip the cooldown, send 0.005 ETH (or the current bypass amount) to the Clawnch bypass recipient on Base, then /launch bypass <tx_hash> and /launch confirm.

To claim a vault allocation, burn $CLAWNCH within 24 hours of the launch:

/launch burn 1000000            # signs + submits a 1M CLAWNCH burn from the active wallet (= 1% vault)
/launch burn 10000000           # max 10M CLAWNCH (= 10% vault, the Clanker maximum)
/launch burn 0x<tx_hash>        # or paste a tx hash if you burned externally
/launch confirm                 # deploy with vault allocation applied

Curve: 1k tokens allocated per 1 CLAWNCH burned (1M → 1%, 10M → 10%). Vault tokens are subject to the Clanker 7-day lockup. See api/lib/burn.ts for the exact verification rules.

How the gate works:

→ CLAWNCH_API_KEY authenticates the agent to the Clawnch API → The launchpad returns a 5-second captcha challenge (storage-slot read + signed message + keccak proof) → Clawmes solves the captcha using the active wallet's personal_sign → Clawnch's deployer wallet (server-side) pays gas and submits the underlying Clanker call

Wallet signs only the off-chain captcha — Clawnch pays deploy gas. The clawnch_launch tool (LLM-callable) and clawnch_fees (read launches + fee accrual) follow the same path. See clawmes:clawnch-launch skill for the LLM-facing surface.

Trading + discovery from chat

After launching (or any time): three commands cover the basic loop of finding tokens and buying them.

/trending                          # top 10 tokens on Base by 24h volume (DexScreener)
/trending --clawnch                # restrict to launchpad-deployed tokens
/trending 25                       # bump the limit

/buy MNEME 0.01                    # quote: resolves symbol via DexScreener
/buy MNEME 0.01 --clawnch          # restrict resolution to Clawnch-launched tokens
/buy 0x3FcD…7b07 0.01              # address bypasses symbol resolution
/buy confirm                       # signs the Permit2 + submits via 0x

/my_launches                       # tokens this agent deployed via Clawnch (default)
/my_launches --all                 # any ERC-20 the connected wallet ever created on Base

/buy uses the existing defi_swap tool under the hood — 0x aggregator with Permit2 (single signature, no separate approve tx). The quote step always renders the resolved address before signing, so you can verify you're buying the right token. --all resolution returns the highest-volume Base pair for the symbol; --clawnch additionally verifies the address against the Clawnch launches table.

Security

• WalletConnect mode: clawmes never holds unencrypted private keys.
• Every write tool gates through readonly check + policy evaluation + delegation execution + ledger record.
• Credential leak detection on every LLM-bound output.
• Prompt-injection-resistance guardrails in SOUL.md.
• Sequential write execution — never queues multiple txs.
• Bounded approvals — exact amounts, never unlimited.
• Outbound HTTP restricted to a curated default allowlist, with optional runtime session-scoped additions via /allow <host> (/allowlist shows defaults + user-added + last 100 blocked attempts).
• Transaction verification — always shows what a tx will do before executing.
• Self-modification gate: the agent's own memory (agent_memory) and skill files (skill_evolve) are write-gated through an explicit "evolution mode" — OFF by default. /evolve enables, /stable disables, /evolution shows status. Closes the prompt-injection drift vector where an attacker could rewrite the agent's own context.
• Verifiable agent identity: each agent has an ed25519 keypair + did:key encoding, independent from the wallet. Use the wallet key for on-chain transactions; use the DID key for protocol messages (MCP calls, capability delegations, attestation signatures). /identity to show/generate.

CLI subcommands

hermes clawmes init              Interactive setup wizard
hermes clawmes doctor            Diagnostics
hermes clawmes wallet            Wallet status / mode switch
hermes clawmes plans             Plan status / list / cancel
hermes clawmes policy            Policy status / set / clear
hermes clawmes persona reinstall Force-overwrite SOUL.md (with confirm)
hermes clawmes skills install    Copy bundled skills to writable user namespace
hermes clawmes update            pip install -U clawmes + bridge refresh
hermes clawmes version           Show version
hermes clawmes uninstall         Remove from plugins.enabled (state preserved)

Architecture

hermes (the upstream CLI, hermes-agent ≥ 2026.4.x)
  └── PluginManager.discover_and_load()
        └── clawmes.register(ctx)
              ├── 52 tools     (registered via ctx.register_tool, write-gated)
              ├── 75 commands  (registered via ctx.register_command)
              ├── 11 hooks     (pre_tool_call, post_tool_call, pre_llm_call, ...)
              ├── 29 skills    (registered via ctx.register_skill, namespaced clawmes:*)
              ├── CLI subcmds  (registered via ctx.register_cli_command)
              └── 22 services  (start_all() starts background lifecycle)
                    │
                    ├── subprocess: clawmes-wc-bridge   (Node — WalletConnect v2)
                    └── subprocess: clawmes-sa-bridge   (Node — MetaMask Smart Accounts; planned)

Two bundled Node sub-process bridges (clawmes-wc-bridge, clawmes-sa-bridge) handle WalletConnect v2 sign-client and MetaMask Smart Accounts SDK respectively, talking JSON-line RPC over stdio. They install on first plugin load via npm ci against pinned package-lock.json files in the wheel.

Configuration

Required in ~/.hermes/.env:

# LLM (one of these — Hermes' standard)
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
OPENAI_API_KEY=
NOUS_PORTAL_API_KEY=

# Channel (one of these — Hermes' standard)
TELEGRAM_BOT_TOKEN=
DISCORD_TOKEN=
SLACK_BOT_TOKEN=

# Wallet — pick one mode
WALLETCONNECT_PROJECT_ID=
CLAWMES_LOCAL_KEY_PASSWORD=
BANKR_API_KEY=

Optional (per-tool — features degrade gracefully without their key):

# RPC + explorers
ALCHEMY_API_KEY=
BASESCAN_API_KEY=
ETHERSCAN_API_KEY=
ARBISCAN_API_KEY=
OPTIMISM_ETHERSCAN_API_KEY=
POLYGONSCAN_API_KEY=
CLAWMES_RPC_<chain_id>=  # override per-chain RPC URL

# DEX / bridge aggregators
ZEROX_API_KEY=
LIFI_API_KEY=

# LLM inference gateway (gitlawb opengateway — OpenAI-compatible)
OPENGATEWAY_API_KEY=  # ogw_live_… — recommended; service runs unauthenticated without it
                      # during the gitlawb partnership window (auth optional today)
OPENGATEWAY_MODEL=    # optional default model id sent when callers omit model=

# Market data + analytics
COINGECKO_API_KEY=
HERD_ACCESS_TOKEN=

# Social
NEYNAR_API_KEY=
NEYNAR_SIGNER_UUID=
NOOKPLOT_API_KEY=

# NFT
RESERVOIR_API_KEY=

# Governance
TALLY_API_KEY=

# Clawnch launchpad (token deploys via /launch + /register_agent)
CLAWNCH_API_KEY=      # issued by /register_agent or POST /api/agents/register on clawn.ch

# Specialized
GIZA_API_KEY=         # zkML inference
PAYSPONGE_API_KEY=    # fiat on/off-ramp
LOBSTER_API_KEY=      # privacy pools
MOLTEN_API_KEY=       # X (Twitter) integration
CLAWNX_API_KEY=       # agent-to-agent network
HUMMINGBOT_API_KEY=   # market-making gateway (also: HUMMINGBOT_GATEWAY_URL)
WAYFINDER_API_KEY=    # route optimization

# Token launches (override default contract addresses)
CLAWNCH_LAUNCHPAD_ADDRESS=

The setup wizard (hermes clawmes init) walks through the most-used keys interactively with live validation.

Using OpenGateway as your LLM provider

Clawmes ships under a partnership with gitlawb OpenGateway — an OpenAI-compatible inference gateway that routes a single endpoint across model providers (Xiaomi MiMo, GMI Cloud, more). There are two integration modes; you can use either or both.

Mode 1 — Route the whole Hermes stack through OpenGateway (recommended for most users).

Hermes already supports any OpenAI-compatible endpoint as a "custom" provider. Point it at OpenGateway via hermes model:

$ hermes model
# Pick: "custom endpoint" (or equivalent in your Hermes version)
# Base URL:  https://opengateway.gitlawb.com/v1
# API key:   ogw_live_…   (sign in at https://gitlawb.com/opengateway/dashboard to generate one)
# Model:     mimo-v2.5-pro (or any model OpenGateway routes; check https://opengateway.gitlawb.com/health)

This is config-only — no clawmes code change required. Every LLM call the agent makes (conversation, tool routing, summarization, everything Hermes drives) goes through OpenGateway, with secrets staying server-side. During the gitlawb partnership window the gateway accepts unauthenticated traffic, so you can try it without a key — but auth will become required, so generate one early.

Mode 2 — Targeted LLM calls from clawmes tools (advanced).

Clawmes also ships OpenGatewayService (clawmes/services/opengateway.py) — a service that gives any clawmes tool a first-class LLM client for subtasks outside the main agent loop (intent classification, swap-parameter extraction, governance-proposal summarization, etc). Tools opt in by calling:

from clawmes.services.opengateway import get_opengateway_service

result = get_opengateway_service().chat_completion(
    messages=[{"role": "user", "content": "..."}],
    model="mimo-v2.5-pro",
)
content = result["choices"][0]["message"]["content"]

This is independent from Mode 1 — Mode 2 calls go to OpenGateway regardless of which provider Hermes itself uses. Configure via the OPENGATEWAY_API_KEY / OPENGATEWAY_MODEL env vars above.

Development

git clone https://github.com/clawnchdev/clawmes
cd clawmes
pip install -e ".[dev]"

pytest                            # run tests
ruff check clawmes/               # lint
mypy clawmes/                     # type-check

Adding a tool

# clawmes/tools/my_tool.py
from clawmes.tools.registry import write_tool, register_with_ctx
from clawmes.lib.tool_result import json_result

_SCHEMA = {...}                  # OpenAI function-calling schema

@write_tool(name="my_tool", toolset="clawmes-misc", schema=_SCHEMA, description="…")
def my_tool(args, **kwargs):
    return json_result({...})

def register(ctx):
    register_with_ctx(ctx, my_tool)

Then import and call register(ctx) from clawmes/tools/__init__.py:register_all().

See CONTRIBUTING.md for full guidelines and patterns.

Status

Early development. See CHANGELOG.md for milestone progress and HERMES_PARITY.md for the upstream Hermes API contract.

Tech stack

Component	Version
Hermes Agent	≥ 2026.4.23
Python	≥ 3.11
web3.py	≥ 7.0
viem (in Node bridges)	≥ 2.x

Contributing

See CONTRIBUTING.md for development setup, code style, and PR process.

License

MIT — see LICENSE.