{"id":50068612,"url":"https://github.com/clawnchdev/clawmes","last_synced_at":"2026-05-31T05:00:31.976Z","repository":{"id":356650881,"uuid":"1222685735","full_name":"clawnchdev/clawmes","owner":"clawnchdev","description":"Hermes Agent plugin for crypto: wallets, DEX trading, lending and staking, governance, on-chain automation.","archived":false,"fork":false,"pushed_at":"2026-05-28T20:33:44.000Z","size":1223,"stargazers_count":16,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T22:23:04.524Z","etag":null,"topics":["ai-agent","base","crypto","defi","ethereum","hermes-agent","plugin","walletconnect"],"latest_commit_sha":null,"homepage":"https://github.com/clawnchdev/clawmes","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clawnchdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-27T15:54:03.000Z","updated_at":"2026-05-28T20:33:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/clawnchdev/clawmes","commit_stats":null,"previous_names":["clawnchdev/clawmes"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/clawnchdev/clawmes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawnchdev%2Fclawmes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawnchdev%2Fclawmes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawnchdev%2Fclawmes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawnchdev%2Fclawmes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clawnchdev","download_url":"https://codeload.github.com/clawnchdev/clawmes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clawnchdev%2Fclawmes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33719601,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","base","crypto","defi","ethereum","hermes-agent","plugin","walletconnect"],"created_at":"2026-05-22T01:25:01.083Z","updated_at":"2026-05-31T05:00:31.885Z","avatar_url":"https://github.com/clawnchdev.png","language":"Python","funding_links":[],"categories":["Integrations and Bridges"],"sub_categories":["Plugins and add-ons"],"readme":"# clawmes\n\n[![CI](https://github.com/clawnchdev/clawmes/actions/workflows/ci.yml/badge.svg)](https://github.com/clawnchdev/clawmes/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/clawnchdev/clawmes/actions/workflows/ci.yml)\n[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/clawnchdev/clawmes/blob/main/pyproject.toml)\n[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n\u003e Hermes Agent for crypto.\n\n\u003e [!WARNING]\n\u003e **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](SECURITY.md) for the full threat model and recovery checklist.\n\nClawmes is a [Hermes Agent](https://github.com/NousResearch/hermes-agent) plugin. Wallets, DEX trading, lending and staking, governance, on-chain automation. Python rewrite of [`@clawnch/openclaw-crypto`](https://github.com/clawnchdev/openclawnch) targeting Hermes.\n\n52 tools. 90 commands. 29 services. 11 hooks. Runs on Telegram, Discord, Slack, Signal, WhatsApp, iMessage, and LINE.\n\n## Quick start\n\n```bash\n# 1. Install Hermes Agent (see https://github.com/NousResearch/hermes-agent)\n# 2. Install clawmes from PyPI:\npip install clawmes\nhermes plugins enable clawmes\nhermes clawmes init                # interactive setup wizard\nhermes                             # start chatting\n```\n\nThe `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).\n\n### Alternative: install direct from GitHub\n\n```bash\nhermes plugins install clawnchdev/clawmes --enable\nhermes clawmes init\n```\n\nThis skips PyPI and pulls from the latest `main`. Use it if you want a specific commit or pre-release.\n\n### Editable / dev install\n\n```bash\ngit clone https://github.com/clawnchdev/clawmes\ncd clawmes\npip install -e \".[dev]\"\nhermes plugins enable clawmes\nhermes clawmes init\n```\n\nReleases publish to PyPI automatically via [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) on every `v*` tag push (no tokens, OIDC verified). See `.github/workflows/release.yml`.\n\n## Tools\n\n| Category | Tools | What it does |\n|---|---|---|\n| **Wallet** (4) | `clawnchconnect`, `transfer`, `permit2`, `approvals` | WalletConnect pairing, ENS transfers, Permit2 signed approvals, ERC-20 allowance management |\n| **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 |\n| **Yield/Analytics** (4) | `yield`, `analytics`, `market_intel`, `cost_basis` | DeFiLlama yields, RSI/MACD/Bollinger TA, trending tokens via CoinGecko, FIFO P\u0026L from local ledger |\n| **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 |\n| **Ownership** (4) | `nft`, `airdrop`, `privacy`, `safe` | Reservoir NFT API, OZ Merkle distributor airdrop claims, Lobster privacy pools, Gnosis Safe multisig |\n| **Governance** (2) | `governance`, `farcaster` | Snapshot + Tally proposals/voting, Neynar Farcaster cast/search/feed |\n| **On-chain Intel** (4) | `block_explorer`, `herd_intelligence`, `watch_activity`, `browser` | Etherscan family, Herd whale tracking, persistent watch list, headless Playwright browsing |\n| **Automation** (1) | `compound_action` | Multi-step plans (DCA, conditional triggers, loops) via plan scheduler |\n| **Agent ops** (4) | `molten`, `clawnx`, `hummingbot`, `wayfinder` | X/Twitter posting, agent-to-agent matching, local Hummingbot market-making gateway, multi-step route optimization |\n| **Memory** (3) | `agent_memory`, `skill_evolve`, `session_recall` | Hermes-backed persistent memory, agentic skill self-improvement, past-session search |\n| **Safety \u0026 identity** (2) | `policy_manage`, `agent_identity` | LLM-callable policy CRUD with propose→confirm flow, ed25519 keypair + did:key for verifiable agent identity |\n| **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 |\n| **Misc** (5) | `giza`, `nookplot`, `paysponge`, `lobster_cash`, `_user_tools` | zkML inference, Farcaster analytics, fiat ramp, privacy pools, custom-tool dispatcher |\n\n## Commands\n\n90 slash commands across 16 categories. Commands run synchronously without invoking the LLM, so they're cheap and predictable.\n\n| Category | Commands |\n|---|---|\n| **Wallet** (9) | `/wallet` `/connect` `/connect_local` `/connect_bankr` `/connect_base` `/disconnect` `/mode` `/chain` `/address` |\n| **Wallet recovery** (4) | `/create_wallet` `/recover` `/export_wallet` `/wallet_backup` |\n| **Policy \u0026 safety** (5) | `/policy` `/policy_clear` `/safemode` `/dangermode` `/audit` |\n| **Transactions** (4) | `/tx` `/tx_search` `/tx_export` `/pending` |\n| **Plans \u0026 triggers** (10) | `/plans` `/plan` `/plan_logs` `/interrupt_plan` `/pause_plan` `/resume_plan` `/triggers` `/watch` `/unwatch` `/cron` |\n| **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` |\n| **Balance \u0026 portfolio** (2) | `/balance` `/portfolio` |\n| **Trading \u0026 discovery** (14) | `/buy` `/trending` `/my_launches` `/burn` `/onramp` `/leaderboard` `/claim` `/dca` `/copy` `/agent` `/alerts` `/limit_order` `/sniper` `/strategy` — quote-then-confirm swaps via 0x, hot tokens on Base, list your launches, burn $CLAWNCH for Clanker vault %, Coinbase Onramp deep link, top tokens/launchers/burners, sweep accumulated LP fees, dollar-cost averaging, copy-trade a wallet's buys, NL plan compiler, price + wallet activity alerts, limit buys + take-profit sells, auto-buy newly-launched tokens (Clawmes Unlimited), preset strategy templates (Clawmes Unlimited) |\n| **Self-evolution** (3) | `/evolve` `/stable` `/evolution` — gates `agent_memory` and `skill_evolve` write actions; OFF by default |\n| **Endpoint allowlist** (3) | `/allowlist` `/allow` `/disallow` — session-scoped host allowlist + 100-entry block audit ring |\n| **Discoverability** (5) | `/skills` `/persona` `/chains` `/tools_list` `/safety_status` |\n| **Info** (5) | `/history` `/clear_history` `/version` `/about` `/uptime` |\n| **Agent identity** (1) | `/identity` — show/generate ed25519 keypair + did:key |\n| **BV-7X** (2) | `/bv7x` `/btc` |\n| **Launch (Clawnch)** (2) | `/launch` `/register_agent` — deploy a token from chat via the Clawnch launchpad |\n| **Meta** (2) | `/doctor` `/help` |\n\nA `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).\n\n## Channels\n\n| Channel | Status | Notes |\n|---|---|---|\n| Telegram | Production | Slash menu auto-registered, deep links, streaming, voice transcription via Hermes |\n| Discord | Ready | Slash commands auto-register, thread bindings |\n| Slack | Ready | Channels and DMs |\n| Signal | Ready | Requires `signal-cli` bridge (Hermes-managed) |\n| WhatsApp | Ready | Requires WhatsApp Web bridge (Hermes-managed) |\n| iMessage | Ready | macOS only — Hermes' bluebubbles adapter |\n| LINE | Ready | Requires LINE Messaging API |\n\nAll tools and commands work identically on every channel.\n\n## Wallet modes\n\n| Mode | Key custody | How it works |\n|---|---|---|\n| **WalletConnect** | Your phone wallet | `/connect` generates a pairing link via the bundled Node WC bridge. Every write tx goes to your phone for approval. |\n| **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`. |\n| **Bankr** | Custodial | `/connect_bankr` or `BANKR_API_KEY`. Multi-chain custodial wallet. Good for automation-heavy setups + leverage + Polymarket. |\n\nSpending policies set in natural language:\n\n```\n/policy approve transfers under 0.05 ETH on Base, max 10/hour\n```\n\nFor 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.\n\n## Automation\n\nThe compound action engine lets users describe multi-step plans in natural language:\n\n- **Time triggers** — `every day at 9am, check ETH price`\n- **Price triggers** — `when ETH drops below $2000, swap 1 ETH to USDC`\n- **On-chain triggers** — `when gas is under 10 gwei, execute the pending swap`\n- **Conditionals** — `if my portfolio is down more than 5%, alert me`\n- **Loops + parallel** — `DCA $100 into ETH every week for 12 weeks`\n\nPlans persist to disk and survive restarts. Managed via `/plans`, `/interrupt_plan`. The plan tick loop is driven by Hermes' built-in cron daemon.\n\n## Ecosystem integrations\n\nClawmes wires the following partner / ecosystem projects directly into the tool + slash-command surface:\n\n- **[BV-7X](https://bv7x.ai)** — 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:\n  - Slash: `/btc` (price + Fear \u0026 Greed + ETF flow in one line), `/bv7x` (track record + market regime + agent identity).\n  - Tools: `bv7x` (agent + A2A + commerce), `bv7x_oracle` (signals + on-chain attestations + premium endpoints), `bv7x_market` (BTC market data).\n  - Skill bundle: `clawmes:bv7x` documents the LLM-facing surface.\n  - Premium endpoints (`oracle`, `oracle_premium`, `copy_trade_next`, `copy_trade_history`) require `BV7X_API_KEY` — hold ≥500M `$BV7X` and complete the wallet-verify at \u003chttps://bv7x.ai/terminal#developer\u003e.\n\n- **[gitlawb OpenGateway](https://gitlawb.com/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.\n\n- **[EAS](https://attest.org) (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.\n\n- **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.\n\n## Launch a token from chat\n\nClawmes wires the Clawnch launchpad end-to-end so any user can deploy a token from a chat message. As of v0.4.0, the default is **non-custodial** — your wallet signs the deploy tx directly, no API key needed:\n\n```\n/connect_local                               # or /connect (WalletConnect) / /connect_bankr\n\n/launch name MyCoin\n/launch symbol MC\n/launch description The next big thing       # optional\n/launch image https://i.imgur.com/mycoin.png # optional\n/launch twitter mycoin                       # optional — also: /launch x\n/launch website mycoin.xyz                   # optional\n/launch telegram mycoinchat                  # optional\n/launch farcaster mycoin                     # optional\n/launch discord https://discord.gg/abc       # optional\n/launch confirm\n# clawmes calls https://www.clawn.ch/api/prepare/deploy for unsigned\n# Clanker factory calldata, then your wallet signs and submits.\n# 80% fees to you, 20% platform fee preserved in the rewards array.\n# Returns tx hash + token address.\n```\n\nSocial 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.\n\nTo claim a vault allocation, burn $CLAWNCH before confirming:\n\n```\n/burn 1000000                   # standalone burn: signs + submits 1M CLAWNCH = 1% vault\n/burn 10000000                  # max 10M CLAWNCH = 10% vault (Clanker maximum)\n/burn last                      # show the last burn tx hash you signed via clawmes\n\n# Or via the legacy /launch burn path (same outcome):\n/launch burn 1000000            # signs + submits a 1M CLAWNCH burn from the active wallet\n/launch burn 0x\u003ctx_hash\u003e        # or paste a tx hash if you burned externally\n/launch confirm                 # deploy with vault allocation applied\n```\n\nCurve: 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`](https://github.com/clawnchdev/clawnch/blob/main/api/lib/burn.ts) for the exact verification rules. Server-side verification happens on every deploy — passing `tokenParams.vault.percentage` without a verified `burnTxHash` is rejected with `VAULT_REQUIRES_BURN`.\n\n### Custodial deploys (legacy path)\n\nFor users who can't pay deploy gas themselves, or who want server-paid gas with the existing agent-registration tracking:\n\n```\n/register_agent MyAgent | An agent that launches tokens\n# clawmes posts a challenge, your wallet signs, clawn.ch returns an apiKey.\n# Save it as CLAWNCH_API_KEY in ~/.hermes/.env.\n\n/launch ... (same drafting steps)\n/launch confirm --custodial\n# Clawnch's deployer wallet submits the Clanker tx server-side;\n# your wallet only signs the captcha. Subject to the 24h cooldown.\n```\n\nBypass the cooldown by sending `0.005 ETH` to the Clawnch bypass recipient on Base, then `/launch bypass \u003ctx_hash\u003e` + `/launch confirm --custodial`.\n\n### Export-only mode (for Base MCP, Claude Desktop, Cursor, ChatGPT)\n\nclawmes can also emit the unsigned calldata for you to paste into another agent surface — useful if you want to launch via Base MCP's `send_calls` from Claude Desktop or any other MCP-compatible client:\n\n```\n/launch name MyCoin\n/launch symbol MC\n/launch export\n# Prints a JSON {chain: \"base\", calls: [{to, data, value}]} block\n# ready to paste into Base MCP's send_calls.\n```\n\n### Launch alerts\n\n```\n/launch alerts                          # subscribe link + filter docs\n/launch alerts base-mcp                 # client-side filter docs for base-mcp source\n```\n\nAll Clawnch deploys post to the public `@ClawnchAlerts` Telegram channel — custodial ones from the server, non-custodial / base-mcp ones from the on-chain indexer cron. Filter client-side using Telegram's built-in keyword highlighting.\n\n### How both deploy paths preserve fees\n\nWhether custodial or non-custodial, every deploy hard-codes Clawnch's 20% platform fee into the Clanker `rewards.recipients` array (the user gets 80%). The non-custodial path verifies this server-side before returning calldata and refuses to return anything if the platform fee recipient env var is misconfigured — fail-closed on fee economics. See [`clawmes:clawnch-launch` skill](clawmes/skills/clawnch-launch/SKILL.md) for the LLM-facing surface and `clawnch_launch` / `clawnch_fees` tools for the same path under the LLM.\n\n## Trading + discovery from chat\n\nAfter launching (or any time): three commands cover the basic loop of finding tokens and buying them.\n\n```\n/trending                          # top 10 tokens on Base by 24h volume (DexScreener)\n/trending --clawnch                # restrict to launchpad-deployed tokens\n/trending 25                       # bump the limit\n\n/buy MNEME 0.01                    # quote: resolves symbol via DexScreener\n/buy MNEME 0.01 --clawnch          # restrict resolution to Clawnch-launched tokens\n/buy 0x3FcD…7b07 0.01              # address bypasses symbol resolution\n/buy confirm                       # signs the Permit2 + submits via 0x\n\n/my_launches                       # tokens this agent deployed via Clawnch (default)\n/my_launches --all                 # any ERC-20 the connected wallet ever created on Base\n```\n\n`/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.\n\n### Leaderboards, fee claiming, dollar-cost averaging (v0.6.0)\n\n```\n/leaderboard                       # top 10 Clawnch tokens by 24h volume\n/leaderboard launchers             # top 10 agents by recent launch count\n/leaderboard burners               # top $CLAWNCH burners (stub — points at on-chain data)\n/leaderboard launchers 25          # bump the limit (capped at 25)\n\n/claim                             # preview your launches + claimable hint\n/claim MNEME                       # collect LP fees for one token via Clanker locker\n/claim 0x3FcD…7b07                 # full address also works\n/claim all                         # sweep every launch you own — one tx per token\n\n/dca add 0xa1F7…747be 0.001 1h     # buy 0.001 ETH of CLAWNCH every hour\n/dca add 0x… 0.01 4h --slippage 50 --daily-cap 0.05 --max-total 1 --max-failures 5\n                                   # full safeguard set on a single schedule\n/dca list                          # show your schedules + next run time\n/dca edit dca_abc 0xabc eth_amount 0.02\n                                   # change one field (token, eth_amount, interval,\n                                   # slippage_bps, daily_cap_eth, max_eth_total,\n                                   # max_consecutive_failures)\n/dca skip dca_abc123               # advance next run, no execution this round\n/dca dry-run dca_abc123            # preview swap output, no submission\n/dca status                        # global summary + service health\n/dca pause dca_abc123              # suspend without removing\n/dca resume dca_abc123             # re-arm\n/dca cancel dca_abc123             # delete\n/dca history dca_abc123            # past executions for a schedule\n/dca tick                          # manually execute due schedules (testing/debug)\n```\n\n- `/leaderboard` hits `/api/tokens?sort=volume` + `/api/launches` and aggregates client-side. No new server-side endpoints required.\n- `/claim` calls Clanker v4's `collectRewards(address)` on the LP Locker Fee Conversion contract (`0x63D2DfEA…14d93496`). The locker pays out to every recipient slot per token in one shot — caller pays gas, the slot allocations get distributed to the rewardRecipients on that position. Each tx emits a `ClaimedRewards` event with per-recipient `(amount0, amount1)` arrays.\n- `/dca` schedules persist in `${HERMES_HOME}/clawmes/dca/schedules.json`. Interval grammar: `1m`, `30m`, `1h`, `4h`, `1d`, `1w` (1m floor, 1y ceiling). The `DcaSchedulerService` ticks automatically on the registry cadence — no manual cron wiring needed. Safeguards (slippage, daily-cap, max-total, max-failures) attach per-schedule; the `max-failures` counter auto-pauses runaway schedules so a broken swap path can't burn gas in a loop. `/dca tick` is preserved as a synchronous testing entrypoint.\n\n### Copy-trading (v0.7.0)\n\n```\n/copy add 0xWhale… 0.001            # follow the whale's buys, copy at 0.001 ETH\n/copy add 0x… 0.005 --slippage 200 --daily-cap 0.05 --max-total 1\n                                    # full safeguard set on one follow\n/copy add 0x… 0.001 --blocklist 0xspam,0xspam2\n                                    # ignore known airdrop contracts\n/copy list                          # show your follows\n/copy edit copy_abc eth_per_copy 0.002\n                                    # change one field (eth_per_copy, slippage_bps,\n                                    # daily_cap_eth, max_eth_total, max_consecutive_failures,\n                                    # blocklist)\n/copy pause copy_abc                # stop watching without losing state\n/copy resume copy_abc               # re-arm\n/copy cancel copy_abc               # remove\n/copy status                        # global summary + service health\n/copy history copy_abc              # last 25 copies for one follow\n/copy tick                          # manual poll (testing)\n```\n\nThe `CopyTraderService` polls Basescan's `account.tokentx` for every active follow on each registry tick (~60s). New ERC-20 transfers into the watched wallet trigger a copy buy via `defi_swap` at the configured fixed ETH amount. Same safeguard surface as `/dca` v2 (slippage / daily cap / total cap / max consecutive failures) plus a per-follow blocklist for known airdrop / spam contracts. Per-tick cap of 20 copies keeps a runaway airdrop streak from spawning hundreds of buys at once.\n\nState persists in `${HERMES_HOME}/clawmes/copy/follows.json`. The watcher seeds `last_seen_block` from the current chain head (minus a 10-block lookback for new follows) so the first tick doesn't replay 100 days of history.\n\n### Natural-language plan compiler (v0.8.0)\n\n```\n/agent DCA 0.001 ETH of CLAWNCH every 1h\n/agent buy 0.01 ETH of CLAWNCH then claim my fees\n/agent follow 0xWhale… at 0.001 eth\n/agent burn 1,000,000 CLAWNCH\n/agent show           # re-print the parsed plan\n/agent confirm        # materialize: runs each /command\n/agent cancel         # discard\n/agent examples       # full list of supported phrasings\n```\n\n`/agent` is a regex-based intent parser — not an LLM. Common trading phrasings (\"DCA X of Y every Z\", \"buy X of Y\", \"follow N at M eth\", \"claim my fees\", \"burn N CLAWNCH\", \"top tokens\", \"show my launches\", \"balance\") compile into a sequence of clawmes slash commands. Nothing materializes until you say `/agent confirm` — the draft lives per-sender in memory.\n\nMulti-step prompts join with `then` (bare commas would split numbers like `1,000,000`). Each step routes through the matching `handle_*` function, so the underlying command's safeguards (`/dca` v2 caps, `/buy` quote-then-confirm, etc.) still apply at execution time.\n\n### Alerts + token gating (v0.9.0)\n\n```\n/alerts add price CLAWNCH above 0.00002     # fire when price crosses\n/alerts add wallet 0xWhale…                 # fire on any new ERC-20 receipt\n/alerts list                                # all your alerts + last fire\n/alerts edit alert_abc threshold_usd 0.0001 # change a price threshold\n/alerts pause alert_abc                     # suspend\n/alerts history alert_abc                   # past fires\n/alerts status                              # global summary + service health\n```\n\n`/alerts` is notification-only — no transactions submitted, no wallet required. Price alerts auto-deactivate after firing (so a crossing doesn't repeatedly notify on every subsequent tick). Wallet alerts stay active and re-fire on each new tx because `last_seen_block` advances past the seen receipt. `AlertsSchedulerService` polls on the registry cadence (~60s).\n\n**Token gating.** Power features in `/dca`, `/copy`, `/agent`, and `/alerts` unlock at the `HOLDER` tier — any wallet holding 10,000,000+ $CLAWNCH (~$105 at session-time price). Free tier still gets each feature with these caps:\n- 1 active `/dca` schedule (HOLDER: unlimited + safeguard flags)\n- 1 active `/copy` follow (HOLDER: unlimited)\n- 3 active `/alerts` (HOLDER: unlimited)\n- `/agent` single-step prompts (HOLDER: multi-step with `then` chains)\n\nThe gate reads your active wallet's $CLAWNCH balance via `eth_call`, caches the result for 60s, and never crashes a command on RPC error (transient failures fall back to free tier). Implementation in `clawmes/services/token_gate.py`.\n\n### Clawmes Unlimited (v0.11.0)\n\nA third tier above HOLDER for the most aggressive features. Hold **100,000,000+ $CLAWNCH** (~$1,050 at session-time price) to unlock:\n\n```\n/sniper add 0.005 --max-buys 5 --source clawmes --symbol-filter DOG|CAT\n                            # auto-buy new Clawnch launches matching filters\n/sniper add 0.01 --max-age 60 --slippage 200\n                            # snipe any launch \u003c 60s old at 2% slippage\n/sniper list / pause / resume / cancel / edit / history / status\n\n/agent --ai sweep my LP rewards then buy some clawnch\n                            # LLM fallback when the regex parser can't match\n                            # (regex runs first; LLM only sees what didn't parse)\n```\n\n- **`/sniper`** watches `/api/launches` on the registry tick and fires `defi_swap` buys for any newly-detected launch matching the configured filters. Filters compose: `--source` attribution, `--symbol-filter` regex, `--max-mcap` skip threshold, `--max-age` recency window (default 10min — older launches are presumed already sniped). Auto-exhausts after `--max-buys` (default 10) so a runaway launchpad can't drain your wallet. `SniperSchedulerService` drives the loop.\n- **`/agent --ai`** layers on top of the existing intent matcher. The regex parser runs first; the LLM only sees segments that didn't match. Rewrites are re-validated through the same `_parse_one` path so the LLM can't smuggle invented commands. Powered by OpenGateway; falls back gracefully when OpenGateway errors.\n\n### Paid-tier expansions (v0.12.0)\n\nFour feature additions across existing commands. Each lifts a specific paid-tier use case.\n\n```\n/copy add 0xWhale… 0.001 --invert            # HOLDER — also mirror sells\n/copy add 0xLead… 0.001 --multi 0xCo1,0xCo2  # UNLIMITED — follow multiple wallets\n/copy add 0xWhale… 0.001 --invert --multi 0xCo1,0xCo2\n                                              # both at once: track a cohort\n                                              # of whales, copy buys + sells\n\n/alerts add price CLAWNCH above 0.0001 --webhook https://hook.example.com/alert\n                                              # HOLDER — POST a JSON payload\n                                              # to your dashboard on fire\n\n/sniper add 0.005 --auto-sell 100:50         # UNLIMITED — take-profit at +100%,\n                                              # stop-loss at -50%, full lifecycle\n                                              # automation per snipe\n```\n\n- **`/copy --invert`** captures the \"whale exiting\" signal. When the watched wallet sends an ERC-20 OUT (to a DEX router), we check our balance and submit a corresponding sell. Combined with the default buy-on-receive behavior you get full mirror trading.\n- **`/copy --multi`** lets one follow record track multiple wallets. Polling iterates over every watched address each tick. Useful for cohort strategies: \"watch these three whales; copy any buy from any of them.\"\n- **`/alerts --webhook \u003curl\u003e`** delivers a JSON payload on fire with `alert_id`, `sender_id`, `type`, `fired_at`, `detail`, and the full fire metadata. Failures never block the alert tick — they're recorded on the fire history.\n- **`/sniper --auto-sell \u003cgain\u003e:\u003closs\u003e`** finishes the snipe lifecycle. After each successful snipe, the config anchors a watch to the buy-time USD price. Subsequent ticks compare current price against the gain/loss thresholds; when either fires, we sell our entire balance back to ETH. The watch transitions to `filled` on success or `close_failed` if the sell fails.\n\n### Trader power-pack (v0.10.0)\n\n```\n/portfolio                  # live balances (unchanged) + P\u0026L hint\n/portfolio pnl              # overall realized + unrealized P\u0026L\n/portfolio realized         # closed positions only\n/portfolio unrealized       # open positions at last price\n/portfolio export           # full lot-by-lot ledger\n\n/limit_order add buy CLAWNCH 0.01 below 0.00001\n                            # buy 0.01 ETH of CLAWNCH when price drops\n/limit_order add sell 0xToken… 1000000 above 0.00005\n                            # take-profit sell at the threshold\n/limit_order list           # all your orders + last attempt\n/limit_order pause lim_abc  # suspend\n/limit_order resume lim_abc # re-arm (paused orders only)\n/limit_order cancel lim_abc # remove\n/limit_order history lim_abc # past attempts (auto-fail after max-attempts)\n\n/wallet tag trading         # bookmark the active wallet under \"trading\"\n/wallet tags                # list all saved tags\n/wallet show trading        # print address/chain/mode for one tag\n/wallet untag trading       # remove\n\n/copy add 0xWhale… 0.001 --pct 50\n                            # copy each buy at 50% of target's outgoing ETH,\n                            # capped at 0.001 ETH (HOLDER tier)\n```\n\n- `/portfolio` P\u0026L views route to the existing `cost_basis` tool — FIFO matching, USD-marked unrealized positions, exportable lot ledger.\n- `/limit_order` runs on the same scheduler pattern as `/dca` + `/copy`. State machine: `active → filled` on swap success, `active → failed` after `max_attempts` exhausted, `active → paused/cancelled` on manual mutation. Terminal states are sticky.\n- `/wallet` tags are metadata-only bookmarks at `${HERMES_HOME}/clawmes/wallet/tags.json`. They don't replace the active session — switching wallets still goes through the existing `/connect*` flow.\n- `/copy --pct N` reads the target tx's outgoing ETH via Basescan's `eth_getTransactionByHash`, scales to `N%`, caps at `eth_per_copy`. Falls back to fixed sizing when target tx had no ETH value (token-token swap) or when the lookup fails.\n\n## Base ecosystem integration\n\nclawmes is built around the Base network. v0.5.0 deepens that integration across four surfaces:\n\n### Coinbase Smart Wallet via `/connect_base`\n\nConnect your existing Base Account (the wallet you use in Base App) to clawmes via OAuth — same flow Base MCP uses:\n\n```\n/connect_base                       # emits an OAuth URL\n# visit the URL, approve in Coinbase, copy the `code` query param from the redirect\n/connect_base \u003ccode\u003e                # finalizes the connection\n```\n\nEvery tx + signature thereafter triggers an approval in your Base App, same UX as WalletConnect. No mnemonic to manage. Configure via `CLAWMES_BASE_ACCOUNT_CLIENT_ID` after registering an OAuth client on [Coinbase Developer Platform](https://portal.cdp.coinbase.com).\n\n### `clawmes-mcp` — use clawmes from desktop AI\n\nclawmes ships as a Model Context Protocol server in addition to the Hermes Agent plugin, so Claude Desktop / Cursor / ChatGPT / any MCP-compatible client can use its read tools directly:\n\n```\npip install clawmes[mcp]\nclawmes-mcp                         # runs the stdio MCP server\n```\n\nConfigure Claude Desktop's `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{ \"mcpServers\": { \"clawmes\": { \"command\": \"clawmes-mcp\" } } }\n```\n\nRead tools exposed in v0.5.0: `defi_price`, `defi_balance`, `market_intel`, `clawnch_launch` (info), `clawnch_fees`, `bv7x_oracle`, `bv7x_market`, `nft`, `block_explorer`, `cost_basis`. Write tools (swap / deploy / transfer) require a connected wallet that doesn't transfer cleanly into the MCP context — those land in a follow-up that delegates signing to Base MCP via `send_calls`.\n\n### Builder rewards on every clawmes swap + deploy\n\nEvery clawmes-initiated transaction on Base mainnet automatically appends Coinbase's `BASE_BUILDER_CODE` suffix to the calldata, attributing the on-chain activity to Clawnch's builder ID. The EVM ignores trailing calldata beyond the ABI-decoded args, so it's a harmless ~28-byte suffix that earns builder rewards proportional to the volume the plugin drives.\n\n### Coinbase Onramp + Basenames + Base App deep links\n\n```\n/onramp 50                          # Coinbase Onramp link, $50 of ETH to your wallet\n/buy jesse.base.eth 0.01            # Basenames resolve natively against Base L2 ENS\n/launch confirm                     # success output includes a Base App deep link\n```\n\n`CLAWMES_COINBASE_ONRAMP_APP_ID` for production Onramp config; without it the command emits a generic Coinbase landing URL. Basename resolution is automatic — no flag needed. Base App URL pattern is overridable via `CLAWMES_BASE_APP_TOKEN_URL` if Coinbase's URL scheme shifts.\n\n## Security\n\n- WalletConnect mode: clawmes never holds unencrypted private keys.\n- Every write tool gates through readonly check + policy evaluation + delegation execution + ledger record.\n- Credential leak detection on every LLM-bound output.\n- Prompt-injection-resistance guardrails in SOUL.md.\n- Sequential write execution — never queues multiple txs.\n- Bounded approvals — exact amounts, never unlimited.\n- Outbound HTTP restricted to a curated default allowlist, with optional runtime session-scoped additions via `/allow \u003chost\u003e` (`/allowlist` shows defaults + user-added + last 100 blocked attempts).\n- Transaction verification — always shows what a tx will do before executing.\n- **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.\n- **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.\n\n## CLI subcommands\n\n```\nhermes clawmes init              Interactive setup wizard\nhermes clawmes doctor            Diagnostics\nhermes clawmes wallet            Wallet status / mode switch\nhermes clawmes plans             Plan status / list / cancel\nhermes clawmes policy            Policy status / set / clear\nhermes clawmes persona reinstall Force-overwrite SOUL.md (with confirm)\nhermes clawmes skills install    Copy bundled skills to writable user namespace\nhermes clawmes update            pip install -U clawmes + bridge refresh\nhermes clawmes version           Show version\nhermes clawmes uninstall         Remove from plugins.enabled (state preserved)\n```\n\n## Architecture\n\n```\nhermes (the upstream CLI, hermes-agent ≥ 2026.4.x)\n  └── PluginManager.discover_and_load()\n        └── clawmes.register(ctx)\n              ├── 52 tools     (registered via ctx.register_tool, write-gated)\n              ├── 75 commands  (registered via ctx.register_command)\n              ├── 11 hooks     (pre_tool_call, post_tool_call, pre_llm_call, ...)\n              ├── 29 skills    (registered via ctx.register_skill, namespaced clawmes:*)\n              ├── CLI subcmds  (registered via ctx.register_cli_command)\n              └── 22 services  (start_all() starts background lifecycle)\n                    │\n                    ├── subprocess: clawmes-wc-bridge   (Node — WalletConnect v2)\n                    └── subprocess: clawmes-sa-bridge   (Node — MetaMask Smart Accounts; planned)\n```\n\nTwo 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.\n\n## Configuration\n\nRequired in `~/.hermes/.env`:\n\n```bash\n# LLM (one of these — Hermes' standard)\nANTHROPIC_API_KEY=\nOPENROUTER_API_KEY=\nOPENAI_API_KEY=\nNOUS_PORTAL_API_KEY=\n\n# Channel (one of these — Hermes' standard)\nTELEGRAM_BOT_TOKEN=\nDISCORD_TOKEN=\nSLACK_BOT_TOKEN=\n\n# Wallet — pick one mode\nWALLETCONNECT_PROJECT_ID=\nCLAWMES_LOCAL_KEY_PASSWORD=\nBANKR_API_KEY=\n```\n\nOptional (per-tool — features degrade gracefully without their key):\n\n```bash\n# RPC + explorers\nALCHEMY_API_KEY=\nBASESCAN_API_KEY=\nETHERSCAN_API_KEY=\nARBISCAN_API_KEY=\nOPTIMISM_ETHERSCAN_API_KEY=\nPOLYGONSCAN_API_KEY=\nCLAWMES_RPC_\u003cchain_id\u003e=  # override per-chain RPC URL\n\n# DEX / bridge aggregators\nZEROX_API_KEY=\nLIFI_API_KEY=\n\n# LLM inference gateway (gitlawb opengateway — OpenAI-compatible)\nOPENGATEWAY_API_KEY=  # ogw_live_… — recommended; service runs unauthenticated without it\n                      # during the gitlawb partnership window (auth optional today)\nOPENGATEWAY_MODEL=    # optional default model id sent when callers omit model=\n\n# Market data + analytics\nCOINGECKO_API_KEY=\nHERD_ACCESS_TOKEN=\n\n# Social\nNEYNAR_API_KEY=\nNEYNAR_SIGNER_UUID=\nNOOKPLOT_API_KEY=\n\n# NFT\nRESERVOIR_API_KEY=\n\n# Governance\nTALLY_API_KEY=\n\n# Clawnch launchpad (token deploys via /launch + /register_agent)\nCLAWNCH_API_KEY=      # issued by /register_agent or POST /api/agents/register on clawn.ch\n\n# Specialized\nGIZA_API_KEY=         # zkML inference\nPAYSPONGE_API_KEY=    # fiat on/off-ramp\nLOBSTER_API_KEY=      # privacy pools\nMOLTEN_API_KEY=       # X (Twitter) integration\nCLAWNX_API_KEY=       # agent-to-agent network\nHUMMINGBOT_API_KEY=   # market-making gateway (also: HUMMINGBOT_GATEWAY_URL)\nWAYFINDER_API_KEY=    # route optimization\n\n# Token launches (override default contract addresses)\nCLAWNCH_LAUNCHPAD_ADDRESS=\n```\n\nThe setup wizard (`hermes clawmes init`) walks through the most-used keys interactively with live validation.\n\n### Using OpenGateway as your LLM provider\n\nClawmes ships under a partnership with [gitlawb OpenGateway](https://gitlawb.com/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.\n\n**Mode 1 — Route the whole Hermes stack through OpenGateway (recommended for most users).**\n\nHermes already supports any OpenAI-compatible endpoint as a \"custom\" provider. Point it at OpenGateway via `hermes model`:\n\n```\n$ hermes model\n# Pick: \"custom endpoint\" (or equivalent in your Hermes version)\n# Base URL:  https://opengateway.gitlawb.com/v1\n# API key:   ogw_live_…   (sign in at https://gitlawb.com/opengateway/dashboard to generate one)\n# Model:     mimo-v2.5-pro (or any model OpenGateway routes; check https://opengateway.gitlawb.com/health)\n```\n\nThis 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.\n\n**Mode 2 — Targeted LLM calls from clawmes tools (advanced).**\n\nClawmes 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:\n\n```python\nfrom clawmes.services.opengateway import get_opengateway_service\n\nresult = get_opengateway_service().chat_completion(\n    messages=[{\"role\": \"user\", \"content\": \"...\"}],\n    model=\"mimo-v2.5-pro\",\n)\ncontent = result[\"choices\"][0][\"message\"][\"content\"]\n```\n\nThis 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.\n\n## Development\n\n```bash\ngit clone https://github.com/clawnchdev/clawmes\ncd clawmes\npip install -e \".[dev]\"\n\npytest                            # run tests\nruff check clawmes/               # lint\nmypy clawmes/                     # type-check\n```\n\n### Adding a tool\n\n```python\n# clawmes/tools/my_tool.py\nfrom clawmes.tools.registry import write_tool, register_with_ctx\nfrom clawmes.lib.tool_result import json_result\n\n_SCHEMA = {...}                  # OpenAI function-calling schema\n\n@write_tool(name=\"my_tool\", toolset=\"clawmes-misc\", schema=_SCHEMA, description=\"…\")\ndef my_tool(args, **kwargs):\n    return json_result({...})\n\ndef register(ctx):\n    register_with_ctx(ctx, my_tool)\n```\n\nThen import and call `register(ctx)` from `clawmes/tools/__init__.py:register_all()`.\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for full guidelines and patterns.\n\n## Status\n\nEarly development. See [`CHANGELOG.md`](CHANGELOG.md) for milestone progress and [`HERMES_PARITY.md`](HERMES_PARITY.md) for the upstream Hermes API contract.\n\n## Tech stack\n\n| Component | Version |\n|---|---|\n| Hermes Agent | ≥ 2026.4.23 |\n| Python | ≥ 3.11 |\n| web3.py | ≥ 7.0 |\n| viem (in Node bridges) | ≥ 2.x |\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup, code style, and PR process.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawnchdev%2Fclawmes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclawnchdev%2Fclawmes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclawnchdev%2Fclawmes/lists"}