# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.noelclaw.fun/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Introduction

## The runtime layer for AI.

**Your AI remembers, keeps working, and survives every session.**

Most AI assistants disappear when the conversation ends. Noelclaw gives them persistent state - memory that accumulates, agents that keep running, vaults that version knowledge, and workflows that continue after you close the chat.

Works in **Cursor, Windsurf, Claude Desktop, ChatGPT, Zed, Hermes, Bankr, Aeon**, and anywhere [MCP](https://modelcontextprotocol.io) runs.

* Website: [noelclaw.com](https://noelclaw.fun)
* App: [app.noelclaw.com](https://app.noelclaw.com)
* npm: [@noelclaw/mcp](https://www.npmjs.com/package/@noelclaw/mcp)
* Version: `3.43.1`

***

## The three pillars

### Memory - what your AI remembers

Semantic, versioned, deduplicated. Vault gives you git-style versioning and knowledge-graph links. Memory gives you semantic search with 90-day time-decay and same-session deduplication. Together they form a two-tier persistent state your AI can read from and write to.

### Agents - what runs in the background

Named, persistent agents that survive across sessions. Spawn one with a goal, recall it weeks later, audit every state change via the ledger. Each agent can hold its own Base wallet address for on-chain identity.

### Workflows - what executes on a schedule

Packets, automations, monitors, and deep research. Anything that runs after you close the chat - daily research that lands in your vault, DCA orders that fire weekly, multi-agent research swarms that complete async.

***

## Quick Install

**Requirement:** Node.js >= 18 - check with `node --version`, download from [nodejs.org](https://nodejs.org) if needed.

### One-command setup (auto-detects all MCP clients)

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw install
```

Detects Claude Desktop, Cursor, Windsurf, VS Code, Zed, and configures each automatically. Then restart your client.

### Claude Code

```bash
claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

### Claude Desktop

Edit your config file:

* **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Restart Claude Desktop after saving.

### Hermes

```bash
hermes mcp add noelclaw -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

No build step. No config required. Runs on first use.

***

## 121 Tools

> **Noel Shell:** The webapp chat supports native tool calling. Shell tools let the chat spawn agents, save to vault, search memory, create automations, estimate + execute swaps, list agents, and check wallet balances — all from natural conversation. See [Noel Shell](/agents-and-workflows/noel-shell).

Grouped by pillar — counts match the live tool registry exactly. Full catalog: [All 121 Tools](/reference/mcp-server).

| Pillar        | Category        | Tools | What it does                                                                                                                                                                     |
| ------------- | --------------- | :---: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Memory**    | Vault           |   15  | Versioned notes: save, read, search, history, diff, export, credentials, tags, links, knowledge graph                                                                            |
| **Memory**    | Semantic Memory |   10  | Semantic search, cross-session recall, extract, consolidate, insight, publish/delete with confirm                                                                                |
| **Memory**    | Chronicle       |   4   | Append-only audit trail — add, list, search, activity stats                                                                                                                      |
| **Agents**    | Agents          |   12  | Persistent named agents: spawn, recall, update, identity, ledger, schedule/pause/resume, runs, hire, list                                                                        |
| **Agents**    | Playbooks       |   3   | Browse and run curated playbooks with an audit ledger                                                                                                                            |
| **Workflows** | Automations     |   6   | DCA, price alerts, conditional buy/sell, dry-run, pause/delete, execution history                                                                                                |
| **Workflows** | Monitors        |   3   | Scheduled research monitors: schedule, list, cancel                                                                                                                              |
| **Workflows** | Packets (Flows) |   4   | Create, run, list, and share reusable workflow packets                                                                                                                           |
| **Workflows** | Research        |   3   | `deep_research` (keyless evidence packs), compare two reports, walk a research chain                                                                                             |
| **Execution** | Base DeFi       |   12  | `base_mcp_*`: balances with impostor detection, send, 0x Permit2 swaps, Morpho/Moonwell yields, basenames — see [Base](/trading-and-defi/base)                                   |
| **Execution** | Robinhood Chain |   14  | `rh_*`: 22 tokenized stocks + any RH-chain crypto, V2/V3/V4 best-fill routing, risk screens, DCA/TP/SL orders, stock bridge — see [Robinhood Chain](/trading-and-defi/robinhood) |
| **Execution** | Stocks (SEC)    |   3   | Fundamentals (XBRL), insider trades (Form 4), material events (8-K) — see [Stocks & SEC Data](/trading-and-defi/stocks-sec)                                                      |
| **Execution** | Market Data     |   6   | Live prices, token data, market overview, OHLC history, market thesis                                                                                                            |
| **Execution** | Token Scanner   |   3   | Score, safety-check, and compare tokens on Base                                                                                                                                  |
| **Execution** | Web Research    |   2   | Live web search + scrape any URL (proxied, keyless)                                                                                                                              |
| **Execution** | GitHub          |   8   | Repos, PRs, issues, files, commits, code search (read-only)                                                                                                                      |
| **Execution** | Code Audit      |   1   | Static Solidity security scan with review rubric                                                                                                                                 |
| **Execution** | Insight         |   3   | `ask_noel`, trade planning, DeFi yields                                                                                                                                          |
| **Execution** | MiroShark       |   3   | Multi-agent market simulation                                                                                                                                                    |
| **Execution** | Wallet          |   3   | Wallet address, live balance with USD pricing, EIP-191 message signing                                                                                                           |
| **Runtime**   | OS              |   3   | `noel_status` dashboard, `noel_diagnostics` health check, Noel Shell chat bridge                                                                                                 |

***

## What's New

### v3.43.1 - x402 API Market, Robinhood Chain Trading, 121 Tools

* **x402 API Market** — sell any HTTPS API per call, buy with USDC on Base via the x402 protocol (HTTP 402 challenge → pay → retry with `PAYMENT-SIGNATURE`). No account or API key needed for buyers. Payments are replay-protected at both the request-id and tx-hash level. See [x402 API Market](/trading-and-defi/x402-api-market).
* **Robinhood Chain rail (`rh_*`)** — 22 tokenized stocks (added NFLX, SPY, QQQ, GME) plus trending chain tokens, arbitrary crypto by ticker or contract address, V2/V3/V4 best-fill routing, receipt-backed swap confirmations, safety scans (`rh_analyze`, `rh_safety_check`), DCA/TP-SL order engine.
* **Investor triad from SEC primary sources, all keyless** — `stock_fundamentals` (XBRL financials), `stock_insider` (Form 4), `stock_events` (8-K decoded), plus `rh_stock_bridge` (tokenized vs real price + pool depth).
* **Client-first refactor** — tools return evidence and structure; your model does the reasoning. `deep_research` works with zero API keys (`mode: "sources"`).
* **Cleaner metadata** — tool count corrected to 121 everywhere, emoji removed from all tool and package descriptions.

### v3.32.7 - Local Memory, OpenAI BYOK, Critical Install Fix

* **Local memory** — run memory tools on a free, self-hosted [supermemory](https://github.com/supermemoryai/supermemory) server on your own machine. Zero cost, private, no Noelclaw account or Convex proxy needed once enabled. Run `noelclaw setup` to switch. *(Beta - code-reviewed and unit-verified, live-server testing pending.)*
* **OpenAI BYOK** — OpenAI joins Bankr/Anthropic/Grok as a direct LLM provider. `OPENAI_BASE_URL` lets you route to any self-hosted OpenAI-compatible gateway instead (LiteLLM, vLLM, Ollama, OpenRouter, your own VPS).
* **`noelclaw setup`** — new guided CLI wizard for picking an LLM provider and/or enabling local memory in one flow.
* **Critical fix** — `noelclaw install` was writing a broken MCP server entry (`npx -y @noelclaw/mcp@latest`, ambiguous bin resolution) into every detected client config, so every fresh auto-install was non-functional. Fixed to the unambiguous, version-pinned form.

### v3.32.5 - Chronicle Search, execute\_swap, Live Wallet Pricing, Diagnostics

* **`execute_swap`** — execute token swaps on Base mainnet from Noel Shell. Enforces estimate → confirm → execute flow. Routes via 0x Permit2. Returns tx hash + Basescan link. Hard-blocked without `confirmed=true`.
* **`chronicle_search`** — keyword search across runtime events by title and detail. Find when your agent last researched any topic without scrolling the full log.
* **`chronicle_stats`** — runtime activity analytics: event breakdown by type, daily heatmap, busiest days, avg events/day over a configurable window (default 30 days, max 90).
* **`get_wallet_balance`** — live ETH + USDC balance from Base mainnet with real-time USD pricing from CoinGecko. No API key required.
* **`wallet_sign_message`** — EIP-191 personal\_sign to prove wallet ownership off-chain without sending a transaction.
* **`noel_diagnostics`** — pre-flight health check: pings Convex, Firecrawl, Supermemory; lists configured API keys; warns on missing LLM key or Firecrawl key with actionable hints.
* **Base Builder Code** — all x402 payment flows now include `bc_7diuqbqo` as `builderCode`. Transactions are attributed to Noelclaw in the Base Dashboard.

### v3.31.0 - Noel Shell, Multi-Provider Chat, Security Hardening

* **Noel Shell** - native tool calling from the webapp chat. Shell tools: `spawn_agent`, `save_to_vault`, `search_memory`, `create_automation`, `estimate_swap`, `list_agents`, `get_wallet_balance`. The chat can now act, not just answer. See [Noel Shell docs](/agents-and-workflows/noel-shell).
* **7 Agents** - Noel (crypto), CoinGecko (crypto data), Sage (analysis), Forge (developer), Quill (creative), Spectre (trading), Atlas (general). Each agent has its own persona and tool access.
* **Multi-provider chat** - provider cascade: Bankr → OpenAI → Anthropic → Groq → OpenRouter → Custom → Local fallback. No single provider dependency.
* **ConnectMcpModal** - onboarding flow for connecting the MCP server to your IDE directly from the webapp.
* **Security hardening** - 8 security boundaries enforced + vulnerability fixes: `getDecryptedPKByUserId` → internalAction, `createWallet` → internalAction, `getPrivateKey` returns address only (never raw key). Auth is Privy + API key only (OTP removed Jul 2026).
* **Theme refresh** - Claude-style warm palette, Inter font, neural-network knowledge-graph visual.

### v3.23.1 - Polish

* **Memory dedup** - `memory_add` deduplicates identical content via SHA-256 hash with in-process LRU cache + recent-memories lookup. `force: true` overrides.
* **Agent race-safe** - concurrent `agent_update` calls on the same agent serialize through a per-name async mutex. No more silent write loss.
* **Automation dry-run + error categories** - `run_automation dryRun: true` simulates without broadcasting. Failed runs show category badges (`INSUFFICIENT_BALANCE`, `QUOTE_FAILED`, `TX_REVERTED`, etc.) with one-line fix suggestions.
* **MCP Resources pagination** - vault entries past the 50th are now visible to clients via cursor pagination. MIME types derive from `contentType` (markdown/json/code/text).

### v3.22.0 - UX

* **HTTP cache + 429 backoff** - every external API call (CoinGecko, DexScreener, GeckoTerminal) flows through a 45s LRU + exponential backoff that honors `Retry-After`. Agent loops can't trip rate limits anymore.
* **MEV-protect RPC opt-in** - `NOELCLAW_BROADCAST_RPC=<private-relay-url>` routes signed transactions through a private relay. Reads stay on the fast Base RPC.
* **Tool count drift fixed** - banner, login, and `noelclaw doctor` all derive counts from the actual registered tools. No more 104/110/36/100+ mismatch.
* **Humanizer model pin** - `NOELCLAW_HUMANIZER_MODEL` lets you lock the model used by `humanize_text` and `write_content` for consistent voice.

### v3.21.0 - Safety

* **Slippage + price-impact guards** - `swap_tokens` and `base_mcp_swap` refuse execution when price impact exceeds `maxPriceImpactPct` (default 3%). Default slippage cap 1%. Configurable per call.
* **Silent supermemory sync fixed** - retries 3× exponential, logs to chronicle on permanent failure. No more ghost memories that exist in one tier but not the other.
* **SWARM\_TOOLS zombie removed** - dead dispatch handler cleaned up. Multi-agent research is built into `deep_research` now (`depth: "standard" | "deep"`).

### v3.20.0 - Grounding & streaming

* **`audit_contract` grounded** - 13-pattern static Solidity scan runs before the LLM, mandatory disclaimer appended, no more "secure"/"safe" claims.
* **`github_search_code` helpful error** - clear setup instructions and a link to `https://github.com/settings/tokens` when `GITHUB_TOKEN` is missing.
* **`memory_search` time-decay** - 90-day half-life weighting + promotion hints when 4+ memories cluster on a topic.
* **Pyth oracle in `fetchVerifiedPrice`** - cross-source price verification against CoinGecko + DexScreener + Pyth with disagreement detection.
* **`deep_research` streaming progress** - MCP `notifications/progress` for long-running multi-agent research.
* **`noelclaw doctor`** - 5-second CLI health check with ✓/⚠/✗ status and inline fix hints.

***

## Docs

* [Getting Started](/getting-started/getting-started)
* [Install on Claude](/install-by-client/claude-install)
* [Install on Cursor / Windsurf](/install-by-client/cursor-install)
* [Install on Hermes](/install-by-client/hermes-openclaw)
* [Semantic Memory Guide](/memory-and-knowledge/memory)
* [Chronicle (Audit Trail)](/memory-and-knowledge/chronicle)
* [Packets (Flows)](/agents-and-workflows/packets)
* [Full MCP Tool Reference](/reference/mcp-server)
* [MiroShark Simulation](/agents-and-workflows/miroshark)
* [Wallet & DeFi](/trading-and-defi/wallet-defi)
* [Environment Variables](/reference/env-vars)
* [Architecture](/reference/architecture)
* [Noel Shell](/agents-and-workflows/noel-shell)


# Quickstart

New to Noelclaw? You'll be up and running in under 5 minutes.

***

## What is Noelclaw?

Noelclaw is an MCP skill - a plugin for AI tools like Claude, Cursor, Bankr, Aeon, and Hermes. Once installed, your AI gets 121 tools: persistent memory that carries across every session, autonomous agents that run on a schedule, live market data, DeFi execution on Base, deep research, GitHub integration, token scanning, code generation, audit trails, workflow packets, and more.

You talk to it naturally. No commands to memorize.

***

## Step 1 - Check Node.js

Noelclaw requires Node.js 18 or newer. Check if you have it:

```bash
node --version
```

If you see `v18.x.x` or higher - you're good. If not, download it free from [nodejs.org](https://nodejs.org) (choose the LTS version).

***

## Step 2 - Install the Skill

### One-command setup (recommended)

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw install
```

This detects all MCP-compatible apps on your machine (Claude Desktop, Cursor, Windsurf, VS Code, Zed) and configures each one automatically. No JSON editing. Then restart your client.

***

### Manual setup - pick your client

### Claude Desktop

**Mac** - open this file in any text editor:

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows** - open this file:

```
%APPDATA%\Claude\claude_desktop_config.json
```

Paste this (or add the `noelclaw` block if the file already exists):

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Save the file. **Fully quit and restart Claude Desktop** - not just close the window.

→ [Detailed Claude guide](/install-by-client/claude-install)

***

### Claude Code (terminal)

```bash
claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

That's it. Restart Claude Code and the tools are available.

***

### Hermes

```bash
hermes mcp add noelclaw -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Or add it to `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  noelclaw:
    command: npx
    args:
      - -y
      - -p
      - "@noelclaw/mcp@3.43.1"
      - noelclaw-mcp
    timeout: 30
```

Then type `/reload-mcp` in any Hermes session.

→ [Detailed Hermes guide](/install-by-client/hermes-openclaw)

***

### Cursor / Windsurf

Edit `~/.cursor/mcp.json` (Cursor) or `~/.windsurf/mcp_config.json` (Windsurf):

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

→ [Detailed Cursor guide](/install-by-client/cursor-install)

***

## Step 3 - Try It Out

Once installed, just talk to your AI normally. No tool names needed - Noelclaw picks the right tool automatically.

**Search the web in real time:**

> "Find the latest news about AI agents today"

**Check the market:**

> "What's ETH doing right now?"

**Ask for analysis:**

> "Give me a full bull vs bear thesis on ETH"

**Set up an autonomous monitor:**

> "Monitor AI agents and automation news every morning at 8am"

**Check your vault:**

> "Show me my recent research"

**Save something to memory:**

> "Remember that I prefer low-risk DeFi and only trade on Base"

**Test memory recall in a new chat:**

> "What do you know about my trading preferences?"

**Scan for opportunities:**

> "Are there any tokens showing dip reversals right now?"

**Run a simulation:**

> "Simulate how markets would react if the Fed cuts rates 100bps"

***

## Step 4 - Autonomous Monitors (the best part)

Noelclaw can run research automatically on a schedule - no prompting needed.

```
"Monitor AI agents and automation news every morning at 8am"
```

What happens next:

* A scheduled job is registered at `daily-8am`
* Every morning, Noelclaw searches the web for your topic
* Summarizes the findings with an urgency score (1–5)
* Saves the full report to your vault
* Sends a Telegram briefing - quiet on routine days, loud on breaking news
* Compares each run to the previous one, highlighting what changed

To manage monitors:

> "What monitors do I have running?" "Cancel my morning brief monitor"

To get Telegram delivery, run `node worker/scripts/setup-telegram.mjs` once to connect your bot.

***

## Step 5 - Semantic Memory

Noelclaw remembers things you tell it - across sessions, across chats.

Tell it once:

> "I prefer Lido for staking and Aerodrome for LP. I avoid leverage and meme coins."

Come back in a new chat tomorrow and ask:

> "What yield strategies make sense for me?"

It already knows. No need to repeat yourself every session.

→ [Full memory guide](/memory-and-knowledge/memory)

***

## Step 6 - Noel Shell (Webapp Tool Calling)

When you use Noelclaw in the webapp at [app.noelclaw.com](https://app.noelclaw.com), the chat supports **native tool calling** via Noel Shell. Instead of just answering questions, the chat can take actions:

* **Spawn agents** — "Start an agent to monitor DeFi yields"
* **Save to vault** — "Save this analysis to my vault"
* **Search memory** — "What do I already know about ETH?"
* **Create automations** — "Set up a DCA buying $50 of ETH every day"
* **Estimate swaps** — "How much USDC do I need for 0.5 ETH?"
* **List agents** — "Show me my active agents"
* **Check wallet balance** — "What's my Base balance?"

Seven agents are available in the webapp: **Noel** (crypto), **CoinGecko** (crypto data), **Sage** (analysis), **Forge** (developer), **Quill** (creative), **Spectre** (trading), and **Atlas** (general).

→ [Noel Shell docs](/agents-and-workflows/noel-shell)

***

## Troubleshooting

| Problem                             | Fix                                                                        |
| ----------------------------------- | -------------------------------------------------------------------------- |
| Tools not showing in Claude Desktop | Make sure you fully quit and restarted (not just closed the window)        |
| `npx: command not found`            | Node.js isn't installed - download from [nodejs.org](https://nodejs.org)   |
| First message is slow               | Normal - first run downloads the package (\~5 seconds). Fast after that.   |
| Tool call fails with auth error     | Make sure you're signed in at [app.noelclaw.com](https://app.noelclaw.com) |
| Vault tools return empty            | Normal on first use - start by saving something with `vault_save`          |
| `schedule_research` not working     | Add `TRIGGER_SECRET_KEY` to your MCP config env block                      |
| Monitor runs but no Telegram        | Add `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID` to your MCP config env     |


# Setup & Configuration

The `@noelclaw/mcp` package runs via `npx` - no build step, no cloning, no local files needed. One command gives you all 121 tools in any MCP-compatible AI client.

**Requirement:** Node.js >= 18. Check with `node --version`. Download from [nodejs.org](https://nodejs.org) if needed.

***

## Claude Code

```bash
claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Verify the server is registered:

```bash
claude mcp list
# noelclaw   npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Then in any Claude Code session:

```
get_market_data
```

***

## Claude Desktop

**Mac** - Edit `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows** - Edit `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Save the file, then **restart Claude Desktop**. all 121 tools appear automatically in the tool list.

***

## Cursor

### Via Settings UI

1. Open Cursor → **Settings** (Ctrl+, / Cmd+,)
2. Search **MCP** or go to **Features → MCP**
3. Add server:
   * Name: `noelclaw`
   * Command: `npx`
   * Args: `-y -p @noelclaw/mcp@3.43.1 noelclaw-mcp`

### Via Config File

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Restart Cursor. Tools appear in Composer when in **Agent** mode.

***

## Windsurf

Edit `~/.windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Restart Windsurf after saving.

***

## Hermes

### CLI Method

```bash
hermes mcp add noelclaw --command npx --args -y --args -p --args @noelclaw/mcp@3.43.1 --args noelclaw-mcp
```

Reload without restarting:

```
/reload-mcp
```

### Config File Method

Edit `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  noelclaw:
    command: npx
    args:
      - "-y"
      - "-p"
      - "@noelclaw/mcp@3.43.1"
      - "noelclaw-mcp"
    timeout: 30
    connect_timeout: 10
```

Then run `/reload-mcp` in any Hermes session.

***

## Aeon

See [Aeon integration guide](/install-by-client/aeon) for the full setup.

Quick install via Aeon skill registry:

```bash
aeon skill add noelclaw
```

Or add manually to your Aeon config - see the [Aeon page](/install-by-client/aeon).

***

## Any MCP Client

If your client accepts a generic MCP server definition:

```json
{
  "command": "npx",
  "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
}
```

***

## First Steps After Install

### 1. Confirm tools are loaded

Ask your AI client:

```
list all noelclaw tools
```

You should see 121 tools.

### 2. Pull live market data

```
get_market_data
```

### 3. Check your portfolio

```
base_mcp_balance
```

### 4. Ask Noel

```
ask_noel question: "What's your read on BTC right now?"
```

### 5. Save something to vault

```
vault_save type: "memory" title: "First Note" content: "Started using noelclaw"
```

***

## Optional: Environment Variables

Pass env vars to unlock extra tools or use your own API keys:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"],
      "env": {
        "MINIMAX_API_KEY": "your-key",
        "BANKR_API_KEY": "your-key"
      }
    }
  }
}
```

See [Environment Variables](/reference/env-vars) for the full list.

***

## Troubleshooting

| Problem                       | Fix                                                                            |
| ----------------------------- | ------------------------------------------------------------------------------ |
| Tools not showing             | Restart your MCP client after saving the config                                |
| `npx: command not found`      | Install Node.js 18+ from [nodejs.org](https://nodejs.org)                      |
| Server starts but no response | Normal - the MCP server waits for stdin (MCP protocol), it does not serve HTTP |
| Slow first start              | `npx` downloads the package on first run. Subsequent starts are instant        |
| `connect_timeout` errors      | Increase to `connect_timeout: 20` in your config - first run takes longer      |
| Coder tools fail              | Requires `BANKR_API_KEY` env var                                               |


# Claude Code / Claude Desktop

Add Noelclaw to Claude Desktop or Claude Code. No build step - runs via `npx`.

**Requirement:** Node.js >= 18. Check with `node --version`. Download from [nodejs.org](https://nodejs.org) if needed.

***

## Claude Desktop

### 1. Find your config file

**Mac:**

```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**

```
%APPDATA%\Claude\claude_desktop_config.json
```

Open it in any text editor (Notepad, VS Code, TextEdit).

### 2. Add Noelclaw

If the file is empty or doesn't exist yet, paste this:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

If the file already has other MCP servers, just add the `"noelclaw"` block inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "other-server": { ... },
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

### 3. Restart Claude Desktop

**Fully quit the app** - don't just close the window. On Mac: right-click the dock icon → Quit. On Windows: close all windows then check the system tray.

Reopen Claude Desktop. All 121 tools are now available.

### 4. Verify it works

Type this in any chat:

> "What's ETH trading at right now?"

Claude will use `get_market_data` automatically and return live prices.

***

## Claude Code

```bash
claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Verify it's registered:

```bash
claude mcp list
# noelclaw   npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

All 121 tools are now available in every Claude Code session.

***

## Test the Memory Feature

This is the standout feature - try it in two separate chats.

**Chat 1 - save your preferences:**

> "Remember that I only trade on Base mainnet, prefer low-risk DeFi like Lido and Aerodrome, and avoid leverage and meme coins"

**Open a new chat - test recall:**

> "What do you know about my DeFi strategy?"

Claude will pull from vault memory and answer accurately - even though this is a brand new conversation.

***

## Run Memory Fully Local (Optional, Free)

By default, memory is stored via the Noelclaw-hosted proxy. To run it entirely on your own machine instead - private, zero cost, no account needed - run the setup wizard from a terminal:

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw setup
```

This walks you through:

* Bringing your own LLM key (Bankr, Anthropic, OpenAI, or a custom self-hosted endpoint) instead of the shared proxy
* Enabling local memory, which auto-installs a free, open-source [supermemory](https://github.com/supermemoryai/supermemory) server on your machine

Once enabled, restart Claude Desktop (or start a new Claude Code session) - memory tools will use your local server automatically. Check status anytime with:

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw doctor
```

***

## Troubleshooting

| Problem                         | Fix                                                                                      |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| Tools don't appear              | You restarted Claude but tools aren't showing - try fully quitting from the dock/taskbar |
| First message is slow (\~5 sec) | Normal - first run downloads `@noelclaw/mcp` from npm. Fast after that.                  |
| `command not found: npx`        | Node.js not installed - get it at [nodejs.org](https://nodejs.org)                       |
| Auth error on tool calls        | Wallet auto-generates on first use - no sign-in needed. Try restarting the client.       |

***

## Optional: Pin to a Specific Version

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@2.3.1", "noelclaw-mcp"]
    }
  }
}
```

Remove the version tag to always get the latest on restart.


# Cursor / Windsurf

Install the Noelclaw MCP skill in Cursor or Windsurf. No build step - runs via `npx`.

**Requirement:** Node.js >= 18.

***

## Cursor

### Via Settings UI

1. Open Cursor → **Settings** (Ctrl+, / Cmd+,)
2. Search **MCP** or navigate to **Features → MCP**
3. Click **Add Server** and fill in:
   * Name: `noelclaw`
   * Command: `npx`
   * Args: `-y -p @noelclaw/mcp@3.43.1 noelclaw-mcp`
4. Save and restart Cursor

### Via Config File

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Restart Cursor. Tools appear in **Composer** when using Agent mode.

***

## Windsurf

Edit `~/.windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
    }
  }
}
```

Restart Windsurf after saving.

***

## Optional: With Environment Variables

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"],
      "env": {
        "MINIMAX_API_KEY": "your-minimax-key",
        "BANKR_API_KEY": "your-bankr-key"
      }
    }
  }
}
```

See [Environment Variables](/reference/env-vars) for the full list.

***

## First Steps

After install, try in Composer (Agent mode):

```
get_market_data
```

```
ask_noel question: "What's moving in crypto right now?"
```

```
base_mcp_balance
```

```
base_mcp_swap fromToken: "ETH" toToken: "USDC" amount: "0.01"
```

***

## Run Memory Fully Local (Optional, Free)

By default, memory is stored via the Noelclaw-hosted proxy. To run it entirely on your own machine instead - private, zero cost, no account needed - run the setup wizard from a terminal:

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw setup
```

This walks you through bringing your own LLM key (Bankr, Anthropic, OpenAI, or a custom self-hosted endpoint) and enabling local memory, which auto-installs a free, open-source [supermemory](https://github.com/supermemoryai/supermemory) server on your machine. Restart Cursor/Windsurf afterward - memory tools pick up the local server automatically. Check status with `npx -y -p @noelclaw/mcp@3.43.1 noelclaw doctor`.

***

## Troubleshooting

| Problem                  | Fix                                                                     |
| ------------------------ | ----------------------------------------------------------------------- |
| Tools not showing        | Restart Cursor/Windsurf after saving config                             |
| `npx: command not found` | Install Node.js 18+ from [nodejs.org](https://nodejs.org)               |
| Slow first start         | `npx` downloads the package on first run. Subsequent starts are instant |


# Codex

Install the Noelclaw MCP skill in OpenAI's Codex CLI. No build step - runs via `npx`.

**Requirement:** Node.js >= 18.

***

## Via `codex mcp add`

```bash
codex mcp add noelclaw -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

## Via Config File

Edit `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`):

```toml
[mcp_servers.noelclaw]
command = "npx"
args = ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]
```

Restart Codex, then verify with `/mcp` in the TUI - `noelclaw` should show as active with all 121 tools loaded.

***

## Optional: With Environment Variables

```toml
[mcp_servers.noelclaw]
command = "npx"
args = ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"]

[mcp_servers.noelclaw.env]
BANKR_API_KEY = "your-bankr-key"
```

See [Environment Variables](/reference/env-vars) for the full list.

***

## Test It

```
get_market_data
```

```
ask_noel question: "What's moving in crypto right now?"
```

***

## Run Memory Fully Local (Optional, Free)

By default, memory is stored via the Noelclaw-hosted proxy. To run it entirely on your own machine instead - private, zero cost, no account needed - run the setup wizard from a terminal:

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw setup
```

This walks you through bringing your own LLM key (Bankr, Anthropic, OpenAI, or a custom self-hosted endpoint) and enabling local memory, which auto-installs a free, open-source [supermemory](https://github.com/supermemoryai/supermemory) server on your machine. Restart Codex afterward - memory tools pick up the local server automatically. Check status with `npx -y -p @noelclaw/mcp@3.43.1 noelclaw doctor`.

***

## Troubleshooting

| Problem                      | Fix                                                                     |
| ---------------------------- | ----------------------------------------------------------------------- |
| Server not showing in `/mcp` | Restart Codex after editing `config.toml`                               |
| `npx: command not found`     | Install Node.js 18+ from [nodejs.org](https://nodejs.org)               |
| Slow first start             | `npx` downloads the package on first run. Subsequent starts are instant |


# Hermes

Add Noelclaw as an MCP skill in Hermes. Once connected, all 121 tools are available directly in your agent conversations.

No build step needed - runs via `npx`.

**Requirement:** Node.js >= 18. Check with `node --version`. Download from [nodejs.org](https://nodejs.org) if needed.

***

## Method 1 - CLI (Fastest)

```bash
hermes mcp add noelclaw -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Reload without restarting Hermes:

```
/reload-mcp
```

***

## Method 2 - Config File

Edit `~/.hermes/config.yaml`:

```yaml
mcp_servers:
  noelclaw:
    command: npx
    args:
      - -y
      - -p
      - "@noelclaw/mcp@3.43.1"
      - noelclaw-mcp
    timeout: 30
    connect_timeout: 15
```

Then run `/reload-mcp` in any Hermes session.

***

## Verify Tools Are Loaded

```
/list-tools
```

You should see all 121 tools listed - including `get_market_data`, `memory_search`, `base_mcp_swap`, `rh_mcp_estimate`, `miroshark_simulate`, and more.

***

## Try It Out

Just talk naturally - Hermes picks the right tool automatically.

**Live market data:**

> "What's the crypto market looking like right now?"

**Save something to memory:**

> "Remember that I prefer low-risk DeFi on Base - Lido and Aerodrome only"

**Test memory recall in a new session:**

> "What do you know about my trading preferences?"

**Ask Noel for analysis:**

> "What's your take on ETH liquid staking yields this week?"

**Swap on Base:**

> "Swap 0.01 ETH to USDC on Base"

**Scan for opportunities:**

> "Are there any tokens showing dip reversals right now?"

**Run a simulation:**

> "How would markets react if a major stablecoin depegged?"

***

## Semantic Memory

Noelclaw remembers things you tell it - across different sessions.

**Session 1:**

> "Remember: I only trade on Base, I prefer Lido for staking, I avoid leverage"

**New session later:**

> "Should I bridge to Ethereum mainnet for some yields?"

Hermes will answer based on your saved preferences - "probably not, your profile says Base-only" - without you repeating anything.

→ [Full memory guide](/memory-and-knowledge/memory)

***

## Troubleshooting

| Problem                               | Fix                                                                            |
| ------------------------------------- | ------------------------------------------------------------------------------ |
| Tools not showing after `/reload-mcp` | Check Node.js 18+ is installed: `node --version`                               |
| `connect_timeout` errors              | Increase to `connect_timeout: 20` - first run downloads the package            |
| `npx: command not found`              | Set full path: `command: /usr/local/bin/npx` - find it with `which npx`        |
| Auth error on tool calls              | Wallet auto-generates on first use - no sign-in needed. Try restarting Hermes. |
| Slow first response                   | Normal - first run downloads `@noelclaw/mcp` (\~5 seconds). Fast after.        |


# Aeon

The noelclaw skill pack is live in the Aeon ecosystem (merged PR #253). Once added, all 121 Noelclaw tools are available in Hermes and the Aeon agent runtime.

***

## What Aeon Is

Aeon is an AI agent platform with its own skill registry. Skills are MCP-compatible tool bundles that agents can call during task execution. The noelclaw skill pack brings crypto intel, DeFi execution on Base, autonomous agents, vault memory, MiroShark simulation, and the Noel Framework into Aeon.

***

## Install

### Via Aeon Skill Registry (CLI)

```bash
aeon skill add noelclaw
```

This pulls the skill from the Aeon registry and registers `@noelclaw/mcp` as the underlying MCP server.

### Manual Config

If your Aeon version requires manual config, add to your Aeon config file:

```yaml
skills:
  noelclaw:
    mcp_server:
      command: npx
      args:
        - "-y"
        - "-p"
        - "@noelclaw/mcp@3.43.1"
        - "noelclaw-mcp"
    enabled: true
```

### Via Hermes in Aeon

If you use Hermes inside Aeon, follow the [Hermes install guide](/install-by-client/hermes-openclaw). Once the skill is registered in Hermes, Aeon agents can invoke it.

***

## Verify

In Hermes or any Aeon agent session:

```
/list-tools
```

You should see all 121 Noelclaw tools listed.

***

## Tools That Work Best in Aeon

Aeon agents are well-suited to longer autonomous tasks. These tool groups see the most usage in Aeon:

### Deep Research

Aeon agents can run multi-stage research that plans, searches, scrapes, and synthesizes - saving results to vault automatically:

```
deep_research topic: "analyze BTC market structure"
research_compare fromKey: "research/btc-q1" toKey: "research/btc-q2"
```

### Noel Vault

Vault is persistent across sessions - ideal for Aeon agents that need to store intermediate findings, plans, or outputs:

```
vault_save type: "execution" title: "Agent Output 001" content: "..." key: "agent-output-001"
vault_search query: "BTC analysis"
vault_history key: "agent-output-001"
```

### Noel Framework

Use playbooks to give Aeon agents structured, Sentinel-gated execution:

```
list_playbooks
run_playbook playbookId: "..."
get_noel_ledger
```

### MiroShark

Run social simulations as part of research or strategy workflows:

```
miroshark_simulate scenario: "How would a major exchange hack affect altcoin markets?"
miroshark_status simulation_id: "..."
```

### Market & Intel

Feed live data into agent reasoning:

```
get_market_data
get_token_data question: "PEPE, WIF, DOGE"
ask_noel question: "What narratives are gaining traction on Base?"
```

***

## Example: Aeon Agent Workflow

A typical Aeon agent task using noelclaw tools:

1. `ask_noel` - pull market analysis and current context
2. `deep_research` - run multi-stage research, auto-saves to vault
3. `agent_spawn` - create a persistent agent to track the topic
4. `vault_save` - store the analysis output
5. `create_automation` - set a recurring task based on the analysis
6. `agent_schedule` - schedule the agent to run daily

***

## Notes

* All 121 tools are available - no Aeon-specific limitations
* BYOK env vars (Grok, MiniMax) work the same way as in other clients
* See [Environment Variables](/reference/env-vars) for optional keys
* See [MCP Server Reference](/reference/mcp-server) for full tool parameter docs


# Semantic Memory

Noelclaw remembers things you tell it - across sessions, across chats, across days.

This isn't just chat history. It's a vector knowledge base: your preferences, research, decisions, and strategies are indexed by **meaning**, not keywords. Ask "what's my risk tolerance?" and it finds "user avoids leverage and prefers Base-only DeFi" - even if you never used those exact words.

***

## How It Works

Every time you save something to the vault or tell Noelclaw to remember something, it gets stored in two places:

1. **Vault** - structured, versioned, searchable by keyword
2. **Semantic memory (vector index)** - indexed by meaning, searchable by intent

When you ask a question, Noelclaw searches semantic memory first. If it finds relevant entries, it uses those to answer. If not, it falls back to keyword search.

You don't need to do anything special. It just works.

***

## Basic Usage

### Save a preference

> "Remember that I prefer low-risk DeFi. Lido for staking, Aerodrome for LP on Base. No leverage, no meme coins."

### Save research

> "Remember: ETH/USDC LP on Aerodrome targets 12-18% APY. Rebalance weekly. Exit if IL exceeds 5%."

### Save your portfolio

> "Remember my allocation: 60% ETH, 25% USDC, 15% other. DCA on 15%+ dips monthly."

***

## Test Recall (Do This in a New Chat)

Close your current chat. Open a fresh one. Then ask:

> "What do you know about my DeFi strategy?"

> "Should I look at Ethereum mainnet for yields?"

> "What's my portfolio allocation?"

Noelclaw will answer correctly - pulling from memory it saved in a completely different session.

***

## Memory Tools

These tools are available directly if you want more control:

| Tool                 | What It Does                                                              |
| -------------------- | ------------------------------------------------------------------------- |
| `memory_add`         | Add content to semantic memory - text, notes, or auto-fetch a URL.        |
| `memory_search`      | Search by meaning - finds relevant entries even without exact keywords.   |
| `memory_context`     | Load the most relevant memories for a topic as ready-to-use AI context.   |
| `memory_profile`     | See your memory stats - total entries, recent activity, patterns.         |
| `memory_list`        | List recent memory entries, optionally filtered by tag.                   |
| `memory_delete`      | Remove a specific memory entry by ID.                                     |
| `memory_insight`     | AI-generated insights derived from patterns across your saved memories.   |
| `memory_extract`     | Extract discrete facts from any block of text and save each individually. |
| `memory_consolidate` | Merge overlapping memories on a topic into one clean summary.             |
| `vault_search`       | Full-text keyword search across your structured vault.                    |

***

## Connecting External Sources

### Index a URL or GitHub repo

> "Index this into my memory: <https://github.com/noelclaw/mcp>"

Or directly:

> "Connect this URL to my memory: <https://docs.noelclaw.com>"

Noelclaw fetches the page, indexes the full content, and makes it searchable in \~30 seconds.

### Full workspace sync

For Google Drive, Gmail, and full Notion workspace sync - connect via your dashboard at [noelclaw.com](https://noelclaw.com).

***

## Cross-Session Memory: The Demo

This is the best way to see it in action.

**Session 1 (save):**

> "Remember these about me: I only trade on Base mainnet. I prefer low-risk DeFi - Lido for ETH staking, Aerodrome for LP. I never touch leverage or meme coins. Portfolio is 60% ETH, 25% USDC, 15% other. I DCA monthly on 15%+ dips."

Close the chat. Open a completely new one.

**Session 2 (recall):**

> "I'm thinking of bridging to Ethereum mainnet for some yield plays. Is that smart for me?"

Expected response: Noelclaw immediately says no - referencing your Base-only preference, your low-risk profile, and the gas cost argument. All from memory. Zero context given in this session.

***

## Tips

* **Be specific when saving** - "I prefer low-risk DeFi on Base, Lido and Aerodrome specifically" is better than "I like DeFi"
* **Memory is per-user** - your memories are isolated. Other users can't see yours.
* **No setup needed** - semantic memory is on by default for all Noelclaw users. No API key required.
* **Vault and memory are linked** - `vault_save` automatically syncs to semantic memory. You don't need to use both.


# Chronicle (Audit Trail)

Chronicle is an append-only log. Every entry you add is timestamped and permanent - nothing is updated or deleted. Use it to record decisions, track what happened in a session, or keep a running journal that accumulates across all your AI interactions.

***

## Tools

### `chronicle_search`

Search the audit trail by keyword.

| Parameter | Type   | Required | Description                                       |
| --------- | ------ | -------- | ------------------------------------------------- |
| `query`   | string | yes      | Keyword to search across event titles and details |
| `limit`   | number | no       | Max results to return (default 100)               |

**Example:**

```
chronicle_search query="ETH"
chronicle_search query="Morpho" limit=20
chronicle_search query="swap"
```

Returns matching events with timestamps. Scans the most recent 100 entries.

***

### `chronicle_stats`

Runtime activity analytics over a time window.

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `days`    | number | no       | Window in days (default 30, max 90) |

**Example:**

```
chronicle_stats
chronicle_stats days=7
chronicle_stats days=90
```

Returns: event count by type, daily heatmap, busiest days, average events per day.

***

### `chronicle_add`

Add an entry to the audit trail.

| Parameter | Type      | Required | Description                                                       |
| --------- | --------- | -------- | ----------------------------------------------------------------- |
| `content` | string    | yes      | What to record - a decision, finding, note, or event              |
| `tags`    | string\[] | no       | Tags for filtering later                                          |
| `source`  | string    | no       | Where this came from - e.g. `"swarm"`, `"manual"`, `"automation"` |

**Example:**

```
chronicle_add content="Decided to pause ETH automation - volatility too high" tags=["defi","decision"]
chronicle_add content="Swarm found 3 new Base protocols worth tracking" source="swarm"
chronicle_add content="Vault knowledge graph now has 47 linked entries"
```

Every entry is timestamped on the server - you can't backdate or edit.

***

### `chronicle_list`

Read the audit trail.

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `limit`   | number | no       | Max entries to return (default 50)      |
| `tag`     | string | no       | Filter by tag                           |
| `since`   | string | no       | ISO date - only entries after this date |

**Example:**

```
chronicle_list limit=20
chronicle_list tag="decision"
chronicle_list since="2026-06-01"
```

***

## What to Use It For

**Decision log** - Record every significant choice: why you paused an automation, why you pivoted on a trade idea, why an agent was marked complete.

**Research trail** - When swarm or monitor saves findings to vault, also add a chronicle entry: "Swarm found X on topic Y - see vault key research/xyz".

**Session summary** - At the end of a working session: "Completed: linked 5 vault entries, spawned 2 agents, set up morning monitor."

**AI accountability** - Every tool call that matters leaves a trace. Over time, chronicle becomes a record of what your AI actually did.

***

## Chronicle vs Vault

|               | Chronicle                        | Vault                                   |
| ------------- | -------------------------------- | --------------------------------------- |
| **Structure** | Append-only log entries          | Versioned key-value artifacts           |
| **Editable**  | Never                            | Yes (creates new version)               |
| **Best for**  | Events, decisions, what happened | Research, plans, documents, credentials |
| **Search**    | Filter by tag or date            | Full-text + semantic search             |

Use vault to store the *content*, use chronicle to record that it happened.


# Packets (Flows)

Packets are reusable workflow units. Define a sequence of steps once, run it on demand, and share it with others. Think of a packet as a macro: you describe a workflow in plain English, Noelclaw converts it into a named runnable unit, and you or anyone else can execute it by name.

***

## Tools

### `packet_create`

Define a new workflow packet.

| Parameter     | Type      | Required | Description                                             |
| ------------- | --------- | -------- | ------------------------------------------------------- |
| `name`        | string    | yes      | Short slug name - e.g. `"morning-brief"`, `"base-scan"` |
| `description` | string    | yes      | What this packet does                                   |
| `steps`       | string\[] | yes      | Ordered list of steps in plain English                  |
| `tags`        | string\[] | no       | Tags for discovery                                      |

**Example:**

```
packet_create
  name="morning-brief"
  description="Daily market + vault summary"
  steps=[
    "Get market overview for ETH, BTC, SOL",
    "Search vault for recent research saved this week",
    "Summarize key findings in 3 bullets"
  ]
```

***

### `packet_run`

Execute a packet by name.

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| `name`    | string | yes      | Packet name from `packet_list`         |
| `context` | object | no       | Runtime variables to inject into steps |

**Example:**

```
packet_run name="morning-brief"
packet_run name="base-scan" context={"minScore": 70, "mode": "dips"}
```

***

### `packet_list`

List all available packets.

| Parameter | Type   | Required | Description   |
| --------- | ------ | -------- | ------------- |
| `tag`     | string | no       | Filter by tag |

Returns name, description, step count, and last run time.

***

### `packet_share`

Share a packet so others can use it.

| Parameter | Type    | Required | Description                                   |
| --------- | ------- | -------- | --------------------------------------------- |
| `name`    | string  | yes      | Packet name to share                          |
| `public`  | boolean | no       | Make it publicly discoverable (default false) |

Returns a share URL or ID that others can use to import the packet.

***

## Use Cases

**Morning brief** - Every morning: check market, scan dips, search vault for recent notes, send summary.

**Research pipeline** - Web search → extract facts → save to vault → add chronicle entry.

**Base DeFi scan** - Get portfolio → scan dips → list Morpho vaults → recommend action.

**Agent kickoff** - Spawn a named agent → give it a context → log the spawn in chronicle.

***

## Packets vs Automations

|               | Packets                                | Automations                          |
| ------------- | -------------------------------------- | ------------------------------------ |
| **Trigger**   | On demand (you call it)                | Scheduled (cron) or event-driven     |
| **Steps**     | Multi-step, sequential                 | Single rule (if/then)                |
| **Shareable** | Yes                                    | No                                   |
| **Best for**  | Research flows, recurring manual tasks | DCA, price alerts, recurring actions |

Use packets for work you want to run deliberately. Use automations for things that should run without you.


# Noel Shell

> Native tool calling from the webapp chat. Available at [app.noelclaw.com](https://app.noelclaw.com) since `@noelclaw/mcp@3.43.1`.

***

## Overview

Noel Shell bridges the gap between conversation and action. When you chat with an agent in the Noelclaw webapp, the chat doesn't just answer questions — it can **call tools** to spawn agents, save to your vault, search memory, create automations, estimate and execute swaps, list agents, and check wallet balances.

This means a single natural-language message can trigger real work: creating a DCA, saving research, recalling what you know, spawning a background agent, or executing a real swap on Base — without leaving the chat.

***

## Shell Tools

| Tool                 | Description                                                                                                     | Example Trigger                            |
| -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `spawn_agent`        | Spawn a persistent named agent with a goal                                                                      | "Start an agent to monitor DeFi yields"    |
| `save_to_vault`      | Save content to the vault with auto-versioning                                                                  | "Save this analysis to my vault"           |
| `search_memory`      | Semantic search across accumulated memories                                                                     | "What do I already know about ETH?"        |
| `create_automation`  | Create DCA, price alert, or conditional automation                                                              | "Set up a DCA buying $50 of ETH every day" |
| `estimate_swap`      | Preview a swap — expected output and price impact                                                               | "How much USDC do I need for 0.5 ETH?"     |
| `execute_swap`       | Execute a swap on Base mainnet after user confirms. Requires `confirmed=true`. Returns tx hash + Basescan link. | "Yes, confirm the swap"                    |
| `list_agents`        | List all available specialist agents                                                                            | "Show me my active agents"                 |
| `get_wallet_balance` | Check live wallet balance on Base with USD pricing                                                              | "What's my Base balance?"                  |

***

## 7 Agents

Each agent has its own persona, model routing, and tool access. The chat routes your message to the right agent based on context, or you can switch agents manually.

| Agent         | Specialty                    | Category  |
| ------------- | ---------------------------- | --------- |
| **Noel**      | Crypto analysis and DeFi     | crypto    |
| **CoinGecko** | Live crypto market data      | crypto    |
| **Sage**      | Research and analysis        | analysis  |
| **Forge**     | Developer and code           | developer |
| **Quill**     | Creative writing and content | creative  |
| **Spectre**   | Trading and execution        | trading   |
| **Atlas**     | General-purpose              | general   |

Crypto-category agents (Noel, CoinGecko) get live market data injected into their context and have trade-related suggestions available.

***

## Architecture

```
User types message in webapp chat
      │
      ▼
Chat.ts (app/convex/chat.ts)
  → Routes by agentId (Noel, Sage, Forge, etc.)
  → Injects context (memory, vault, market data)
      │
      ├── If the message implies an action:
      │     ▼
      │   NoelShell.ts (app/convex/noelShell.ts)
      │     → Parses intent
      │     → Dispatches to one of 7 shell tools
      │     → Returns structured result
      │
      └── Otherwise: standard LLM response
            ▼
      Multi-provider LLM cascade
        Bankr → OpenAI → Anthropic → Groq → OpenRouter → Custom → Local fallback
```

### Multi-Provider Chat

Chat requests flow through a provider cascade. If the first provider fails or has no API key configured, the next is tried automatically:

**Bankr → OpenAI → Anthropic → Groq → OpenRouter → Custom → Local fallback**

This ensures the chat is always available regardless of which providers have keys. Override with `NOELCLAW_PROVIDER=bankr|openai|anthropic|groq|openrouter`.

***

## How It Works

### Tool Calling Flow

1. **User sends a message** — e.g., "Save my ETH analysis to the vault"
2. **Chat router** identifies the active agent and injects relevant context
3. **Intent detection** — the LLM determines the message implies an action (saving)
4. **Noel Shell dispatch** — `save_to_vault` is called with the content
5. **Execution** — the vault write happens server-side on Convex
6. **Result returned** — confirmation + vault key shown in chat

### Spawn Agent Example

```
User: "Start an agent to monitor DeFi yields and report weekly"

Noel Shell:
  → spawn_agent
    name: "yield-monitor"
    goal: "Monitor DeFi yields on Base and report weekly"
    schedule: "weekly"

Response: "Agent 'yield-monitor' spawned. It will monitor DeFi yields
on Base and report every week. You can recall it anytime with
'recall yield-monitor'."
```

### Create Automation Example

```
User: "Set up a DCA buying $50 of ETH every day at 9am"

Noel Shell:
  → create_automation
    rawInput: "Buy 50 USDC of ETH every day at 9am"

Response: "Automation created: DCA buying $50 of ETH daily at 9am.
Use 'list automations' to see status or 'pause automation' to stop."
```

### Estimate Swap Example

```
User: "How much USDC do I need for 0.5 ETH?"

Noel Shell:
  → estimate_swap
    fromToken: "USDC"
    toToken: "ETH"
    amount: "0.5"

Response: "0.5 ETH ≈ 1,250 USDC at current price. Price impact: 0.2%.
Slippage capped at 1%. Would you like to execute?"
```

***

## Security

Noel Shell tools respect the same security model as all Noelclaw tools:

* **Row-level authorization** — every tool call resolves `userId` from the session token. User identity is never trusted from client args.
* **Private key safety** — `get_wallet_balance` returns balance only, never the private key. Private keys are stored encrypted (AES-256-CBC) and never leave the server.
* **Vault isolation** — `save_to_vault` and `search_memory` are scoped to the authenticated user. Cross-user access is impossible.
* **Automation limits** — `create_automation` enforces swap limits (`MAX_AMOUNT_USD = 500`, `MIN_AMOUNT_USD = 1`) and slippage/price-impact guards.

### 8 Security Boundaries

The backend enforces 8 security boundaries across wallet, vault, chronicle, API keys, notifications, activities, agent identities, and marketplace — all with row-level auth and cross-user isolation tested.

### 4 Vulnerability Fixes (v3.31.0)

1. `getDecryptedPKByUserId` → converted to `internalAction` (was publicly callable)
2. `createWallet` → converted to `internalAction` (was publicly callable)
3. `getPrivateKey` → returns address only, never the raw private key
4. Auth is Privy (web) + API key (CLI) — OTP removed Jul 2026

***

## ConnectMcpModal

The webapp includes a **ConnectMcpModal** — an onboarding flow for connecting the MCP server to your IDE directly from the webapp. When you click "Connect to IDE", the modal:

1. Detects your OS and available MCP clients (Cursor, Windsurf, Claude Desktop, VS Code, Zed)
2. Shows the exact install command: `npm install -g @noelclaw/mcp@3.43.1`
3. Provides copy-paste config snippets for each client
4. Guides you through restarting your client to activate the tools

This makes it easy to go from using the webapp to having all 121 MCP tools available in your IDE.

***

## Theme

The webapp features a **Claude-style warm palette** with:

* **Inter font** for all UI text
* **Neural-network knowledge graph** visual on the Brain/knowledge page
* Warm beige and amber tones throughout
* Smooth Framer Motion animations

***

## Related Docs

* [Getting Started](/getting-started/getting-started)
* [Architecture](/reference/architecture)
* [All 121 Tools](/reference/mcp-server)
* [Environment Variables](/reference/env-vars)


# MiroShark Simulation

MiroShark is a multi-agent social simulation engine. Describe any scenario in plain English - MiroShark spins up a network of AI agents with distinct personas and belief systems, runs them through multiple rounds of interaction and belief propagation, and returns a behavioral analysis of how the scenario plays out.

Use it for: market narrative modeling, social dynamics simulation, regulatory impact analysis, community reaction forecasting.

***

## How It Works

MiroShark runs on a dedicated high-memory backend. The pipeline has four stages:

### 1. Knowledge Graph Construction

MiroShark parses the scenario and builds a knowledge graph - a structured representation of entities, relationships, and claims. This gives all agents shared factual grounding.

### 2. Persona Generation

Agent personas are generated with:

* **Role** - trader, analyst, retail investor, whale, developer, media, skeptic
* **Initial belief state** - how strongly they hold each claim in the knowledge graph
* **Influence weight** - how much other agents are affected by their assertions
* **Information access** - which agents see which signals first

### 3. Belief Propagation

Over multiple rounds, agents exchange signals, update beliefs based on neighbor influence, and form or revise positions. This models how information spreads, narratives form, and consensus or dissent emerges - similar to real social dynamics.

### 4. Analysis Output

After rounds complete, MiroShark returns:

* Consensus narrative - what the majority converged on
* Dissent clusters - minority belief groups that held different views
* Signal strength - how quickly and strongly beliefs propagated
* Agent behavior summary - which persona types were most influential
* Round-by-round action log (Twitter and Reddit simulated activity)

***

## Infrastructure

```
@noelclaw/mcp
      │
      ▼
api.noelclaw.com
  → routes to MiroShark backend
      │
      ▼
MiroShark backend (8 GB RAM)
  Knowledge graph builder
  Persona generator
  Belief propagation engine
  Analysis formatter
```

***

## MCP Tools

### `miroshark_simulate`

Start a new simulation. Returns a `simulation_id` - the simulation runs asynchronously in the backend.

| Parameter  | Type   | Required | Description                                 |
| ---------- | ------ | -------- | ------------------------------------------- |
| `scenario` | string | yes      | What to simulate - plain English, any topic |

Agent count and number of rounds are determined automatically by MiroShark based on scenario complexity. A 24-hour scenario generates \~48 rounds; a 7-day scenario generates \~168 rounds.

**Example:**

```
run a miroshark simulation: "Bitcoin breaks $125,000 - how does the crypto community react over 24 hours?"
```

Returns a `simulation_id`. Pass it to `miroshark_status` to track progress.

***

### `miroshark_status`

Poll simulation progress and retrieve results when complete.

| Parameter       | Type   | Required | Description                  |
| --------------- | ------ | -------- | ---------------------------- |
| `simulation_id` | string | yes      | ID from `miroshark_simulate` |

**Status flow:**

```
preparing → running → complete
```

* `preparing` - building knowledge graph and generating agent personas
* `running` - belief propagation rounds in progress, actions firing
* `complete` - full results available

When `running`, the response shows current round, total rounds, and action counts:

```
Round: 18 / 48 (37.5%)
Actions: 43 Twitter · 50 Reddit
```

Poll every 30-60 seconds. Preparation typically takes 3-5 minutes before rounds start.

***

### `miroshark_stop`

Stop a simulation that is currently preparing or running.

| Parameter       | Type   | Required | Description           |
| --------------- | ------ | -------- | --------------------- |
| `simulation_id` | string | yes      | Simulation ID to stop |

***

## Example Scenarios

**BTC price milestone:**

```
run a miroshark simulation: "Bitcoin breaks $125,000 for the first time - how does the crypto community react over 24 hours?"
```

**Regulatory event:**

```
run a miroshark simulation: "The EU bans self-custody wallets - how does the crypto community respond?"
```

**Market crash:**

```
run a miroshark simulation: "ETH drops 40% in 24 hours following a major hack - what happens to DeFi protocols and community sentiment?"
```

**Narrative spread:**

```
run a miroshark simulation: "A new L2 launches with $500M in liquidity incentives - how does the DeFi community respond?"
```

**Macro impact:**

```
run a miroshark simulation: "The Federal Reserve cuts rates to 0% - how does crypto market sentiment shift over 30 days?"
```

***

## Tips

* **Specific scenarios give better results** - include timeframes, numbers, and named entities
* **Poll with patience** - agent preparation takes 3-5 minutes before `running` starts; first rounds can be slow to initialize
* **You don't need to wait for completion** - Round 10-20 is usually enough for a meaningful snapshot
* **Combine with vault** - use `vault_save` to store results for later reference or comparison
* **Combine with ask\_noel** - after getting results, ask Noel to interpret them in context of current market conditions
* **Use miroshark\_stop** if a simulation is taking too long or you want to start a new scenario


# Wallet & DeFi

Noelclaw includes a built-in crypto wallet and DeFi execution layer, tightly integrated with the agent system.

***

## Wallet Setup

Every registered user gets an embedded wallet automatically:

* **Chain:** Base mainnet
* **Key storage:** Private key encrypted and stored securely on the server
* **Wallet address:** Visible in the Wallet page and Profile

Users can also connect external wallets via Privy (WalletConnect, MetaMask, Coinbase Wallet).

***

## Wallet Page Features

### Token Holdings

* All Base mainnet tokens with USD value
* Dust filtering (hides tokens < $1 USD)
* 24h price change indicators
* NFT gallery tab

### Send

* Enter recipient address or ENS
* Select token + amount
* Confirms with wallet signature
* Transaction tracked in activity feed

### Swap

* Token-to-token swap
* Honeypot detection warning (flags tokens with no sell transactions)
* Slippage settings
* Uses on-chain DEX routing

### Receive

* QR code for wallet address
* Copy-to-clipboard

### Transaction History

* All deposits, swaps, sends
* Status: pending / success / failed
* Links to BaseScan

***

## USDC Balance & AI Model Access

AI model access is pay-per-use via USDC on Base. Your custodial wallet is created automatically on signup - no separate setup needed.

**Check balance:**

* Balance is shown in the Models page header as a live USDC amount
* Balance is read directly from Base mainnet (updates every 30 seconds)

**Deposit USDC:**

1. Go to Models → click **Deposit**
2. Copy your wallet address
3. Send USDC on the **Base network** from any exchange (Coinbase, Kraken, etc.)
4. Balance updates automatically within \~30 seconds of on-chain confirmation

> Send only on **Base (L2)**, not Ethereum mainnet. Gas fees are <$0.01 on Base.

**How billing works:**

* Each AI model call deducts a small amount of USDC based on tokens used
* If your balance runs low mid-request, the system auto-retries the payment (x402 protocol) without interrupting your workflow
* No prepaid bundles or credits - pure pay-as-you-go

***

## MCP Wallets (Agent / CLI Users)

Users accessing Noel through MCP clients (Hermes, Claude, Cursor) get a full DeFi wallet on Base mainnet, managed entirely through MCP tools.

Wallets are created with **ethers.js** and stored **locally** at `~/.noelclaw/wallet.json`. The private key never leaves your machine - Noelclaw's backend only receives routing calldata (0x), not your key. Non-custodial by design.

### Check your balance

```
base_mcp_balance
```

Returns all Base mainnet token balances.

### Swap tokens

```
base_mcp_swap fromToken: "ETH" toToken: "USDC" amount: "0.1"
```

Routes through **0x Permit2** on Base mainnet. Signed locally with slippage capped at 1% and price-impact guard at 3%. Amount is human-readable - no wei conversion needed.

### Send tokens

```
base_mcp_send token: "USDC" toAddress: "0xRecipient..." amount: "10"
```

Supports ETH, USDC, USDT, DAI, and WETH on Base. Also accepts ENS names.

### Security

* Private key lives at `~/.noelclaw/wallet.json` - local only, never transmitted
* All transactions are signed client-side before broadcast
* The Noelclaw backend provides routing (0x calldata) but never holds or sees your private key
* Non-custodial - you own your funds

***

## Telegram Trading

Users can link their Telegram account to their Noelclaw wallet and execute trades directly from Telegram messages.

**Link flow:**

1. User generates link code in Profile → Telegram Connect
2. Sends `/connect <code>` to the bot
3. Bot calls `POST /telegram/connect` with the code
4. Wallet linked to Telegram ID

**Telegram bot:**

* Reads trades from Telegram, posts to Noelclaw backend
* Stored in `trades` table with `source: "telegram"`

***

## Trade Types

All trade actions tracked in `trades` table:

| Action    | Description             |
| --------- | ----------------------- |
| `buy`     | Purchase token          |
| `sell`    | Sell token              |
| `swap`    | Token-to-token exchange |
| `send`    | Transfer to address     |
| `unknown` | Unparseable trade       |

Sources: `web` (app UI), `x` (Twitter mentions), `telegram` (Telegram bot)

***

## X/Twitter Trading

Noelclaw monitors X mentions for trade commands:

```
@noelclaw buy 0.1 ETH
@noelclaw swap 100 USDC to SOL
```

Flow:

1. `xWebhook` receives mention
2. `xWebhookActions.ts` parses trade intent
3. Confidence score calculated
4. Stored in `xMentions` table
5. If confidence > threshold, executed

Trade stored in `xMentions`:

```
tweetId, authorHandle, authorId, text
status: "pending" | "processed" | "failed" | "ignored"
tradeId → linked trade
```


# Base DeFi (base\_mcp\_\*)

The Base rail gives your AI a real wallet on **Base mainnet (chainId 8453)** — balances, transfers, swaps, and yield data. 11 tools, prefix `base_mcp_*`.

Your MCP wallet is generated locally on first use and stored in `~/.noelclaw` — the same address is used on Base and Robinhood Chain.

## Tools

| Tool                     | What it does                                                                                                                                                                        |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_mcp_status`        | Wallet address, chain info, live ETH price, gas. Start any Base session here.                                                                                                       |
| `base_mcp_network`       | Real-time network stats: ETH/USD, gas in gwei, latest block. No wallet needed.                                                                                                      |
| `base_mcp_balance`       | Every ERC-20 you hold, enumerated from the Base Blockscout indexer — not a fixed allowlist. Flags impostor tokens (symbol matches a known asset but the contract address doesn't).  |
| `base_mcp_send`          | Send ETH or any ERC-20 to an address or basename (`jesse.base.eth`). Irreversible; requires `confirm: true`.                                                                        |
| `base_mcp_estimate`      | Preview a swap's output and price impact. Always call before swapping.                                                                                                              |
| `base_mcp_swap`          | Swap via 0x Protocol Permit2 (signature-based, no separate approval tx). Supported: ETH, USDC, USDT, DAI, WETH. Refuses when price impact exceeds `maxPriceImpactPct` (default 3%). |
| `base_mcp_resolve`       | Basename ↔ address resolution via Coinbase's resolver, both directions.                                                                                                             |
| `base_mcp_yield_vaults`  | Morpho vaults on Base ranked by APY.                                                                                                                                                |
| `base_mcp_lending_rates` | Moonwell markets: supply APY, borrow APY, liquidity, utilization per asset.                                                                                                         |
| `base_mcp_lend`          | Best lending venues for a token (Morpho + Moonwell), ranked by APY × TVL safety. Returns instructions only — never broadcasts a deposit.                                            |
| `base_mcp_deposit_guide` | Step-by-step manual deposit instructions for a specific Morpho vault.                                                                                                               |

Related tools outside the prefix: `get_base_token_data` (token market data on Base), `score_token` / `check_token` / `compare_tokens` (scanner), `get_wallet_address`, `get_wallet_balance`, `wallet_sign_message`.

## Safety model

* **Estimate → confirm → execute.** `base_mcp_swap` and `base_mcp_send` require `confirm: true`. A bare estimate never moves funds.
* **Price-impact guard.** Swaps refuse when impact exceeds the cap (default 3%) unless you explicitly raise it.
* **Impostor detection.** Because balances are enumerated from the indexer, `base_mcp_balance` sees scam airdrops and symbol-spoofed tokens — and flags any "USDC"-style token whose contract is not the canonical one (`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`).
* **Lending is read-only.** Yield tools return data and instructions; deposits are always done by you in the protocol's own UI.

## Example session

```
you:  what's my balance on base?
ai:   → base_mcp_balance
      0.0042 ETH · 12.50 USDC (canonical) · ⚠ 1 flagged token (fake "USDC" at 0x3462…)

you:  swap 5 usdc to eth
ai:   → base_mcp_estimate   (shows rate + price impact)
      → asks you to confirm
      → base_mcp_swap { confirm: true }
      ✓ tx hash + Basescan link
```


# Robinhood Chain (rh\_\*)

Trade **tokenized stocks and any Robinhood Chain crypto** on-chain — chainId **4663**, gas in ETH, swaps through Uniswap. 14 tools, prefix `rh_*`.

> This is the **on-chain rail**. It is not Robinhood's brokerage — no Robinhood account is involved, and it is separate from the official Robinhood Agentic MCP (`agent.robinhood.com`). You are trading ERC-20 tokens that track stocks, not owning shares.

## What you can trade

* **22 tokenized stocks** (official "Robinhood Token" contracts): AAPL, AMD, AMZN, BE, COIN, CRWV, GME, GOOGL, INTC, META, MSFT, MU, NFLX, NVDA, ORCL, PLTR, QQQ, SNDK, SPCX, SPY, TSLA, USAR. List them with `rh_mcp_list_stocks`.
* **Any RH-chain crypto** by ticker or 0x contract address — resolved live via DexScreener with `rh_token_resolve`. Tickers can be spoofed (16 tokens share the ticker "ROBINHOOD"), so always trade by the confirmed contract address.

## Routing: V2 / V3 / V4 best fill

`rh_mcp_estimate` quotes **Uniswap V2, V3, and V4 in parallel** and routes through whichever returns the most output. This matters: many RH tokens hold their real depth in a V3 pool while their V4 pool sits nearly empty — single-version routing has produced fills as bad as 9% of spot on such tokens, and some tokens are *only* tradeable on V2. The estimate shows all routes considered ("Compared: V2 … · V3 … · V4 … → best wins") so a routing decision is never invisible.

Multi-hop via USDG is used automatically for thin direct pairs.

## Tools

### Trading

| Tool                 | What it does                                                                                                                                                          |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rh_mcp_status`      | Chain status: wallet, RPC, ETH gas balance, explorer link.                                                                                                            |
| `rh_mcp_list_stocks` | The 22 tokenized stock tickers with contract addresses.                                                                                                               |
| `rh_mcp_balance`     | ETH + every token you hold on chain 4663 (enumerated via Blockscout, so non-catalog tokens show up too).                                                              |
| `rh_token_resolve`   | Ticker or 0x address → tradeable token, candidates ranked by liquidity.                                                                                               |
| `rh_mcp_estimate`    | Preview a swap (V2/V3/V4 compared). Never executes.                                                                                                                   |
| `rh_mcp_swap`        | Execute with `confirm: true`. Reports a **receipt-backed confirmation** — mined status, block, gas, and the actual amount credited from Transfer logs, not the quote. |

### Risk pre-screens (free, no LLM, no API keys)

| Tool              | What it does                                                                                                                                                                                                                              |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rh_analyze`      | Market screen from DexScreener: price, liquidity, volume, buy/sell flow, pair age, FDV — plus implausibility flags (FDV that can't be exited vs liquidity, wash-trade symmetry, bot churn, honeypot buy/sell patterns). 0–100 risk score. |
| `rh_safety_check` | On-chain screen from Blockscout: contract verified?, holder count, launchpad vs self-deployed (an EOA self-deploy is the real red flag on this chain — launchpads are the norm), sellability. 0–100 risk score.                           |

They catch **different** failure modes — run both before buying anything unfamiliar.

### Orders (DCA / take-profit / stop-loss)

| Tool                | What it does                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `rh_dca_create`     | Buy a fixed ETH amount every N hours, up to `totalBuys`, hard-capped by `maxSpendEth`.                                    |
| `rh_bracket_create` | TP and/or SL on a token you already hold; sells `sellPct`% of the live balance when DexScreener price crosses your level. |
| `rh_orders_list`    | List orders and progress.                                                                                                 |
| `rh_order_cancel`   | Cancel an order.                                                                                                          |
| `rh_orders_tick`    | Evaluate all active orders. **Previews by default** — only broadcasts with `execute: true`.                               |

Orders are **semi-automatic by design**: they persist locally in `~/.noelclaw/rh-orders.json`, and nothing trades until you (or your agent, on your instruction) run `rh_orders_tick { execute: true }`. Kill-switch: set `RH_ORDERS_DISABLED=1` or create `~/.noelclaw/rh-orders.OFF` to block all execution instantly.

### Stock bridge

| Tool              | What it does                                                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `rh_stock_bridge` | Tokenized price vs the real US share price: gap %, **pool depth**, and whether the US market is open. Omit `ticker` to scan all 22. |

A gap without depth is a trap — a +19% "discount" on a $1,200 pool cannot be exited. The bridge always shows both, and notes that while the US market is closed a gap is *expected*, not a mispricing.

## Safety model

* Estimates never execute; swaps require `confirm: true`.
* Swap results are receipt-backed (mined status + actual credited amount), so a failed or reverted trade can't be mistaken for a fill.
* Trade tools always print the resolved contract address before executing — verify it, not the ticker.
* Tokens on this chain are largely launchpad-launched memecoins with no locked LP. Use `rh_analyze` + `rh_safety_check`, and size positions to pool liquidity.


# Stocks & SEC Data

Three tools that read **US public-company data straight from SEC EDGAR** — the primary source, as filed, not a vendor's copy. All keyless: no API key, no subscription.

| Tool                 | Source             | What it answers                                                                                                    |
| -------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `stock_fundamentals` | 10-Q / 10-K (XBRL) | The numbers: revenue, operating & net income, diluted EPS, balance sheet, margins, YoY growth — plus a live quote. |
| `stock_insider`      | Form 4             | The behaviour: what insiders actually bought and sold.                                                             |
| `stock_events`       | Form 8-K           | The events: material corporate events within four business days of happening.                                      |

Together they form an investor triad: **numbers · behaviour · events**. Add `rh_stock_bridge` if you also trade the tokenized version on Robinhood Chain, and `deep_research` for sentiment — sentiment is never a substitute for filings.

## `stock_fundamentals`

* Quarterly figures are correctly separated from year-to-date and annual ones (XBRL reports the same tag at multiple spans — naive readers show quarters \~3× too high).
* YoY growth is matched **by date**, not by counting rows back, so missing periods can't silently misalign the comparison.
* US SEC filers only — foreign private issuers and most ETFs won't appear.

## `stock_insider`

* Separates **discretionary** trades (open-market buys/sells — the ones that carry signal) from automatic ones: RSU tax withholding, grants, and option exercises are routinely misreported elsewhere as "insider selling".
* Tags sales made under pre-scheduled **10b5-1 plans** — those carry no view on price.
* Filters out cross-issuer filings (a company's feed also contains its filings *about other issuers*).

## `stock_events`

* 8-K item codes decoded into plain language — "Item 5.02" becomes executive departure/hire/pay change; 1.01 material agreement; 2.03 new debt; 3.02 dilution; 2.05 restructuring.
* `signalOnly` filters routine noise (shareholder votes, exhibit-only filings, Reg FD).
* Notes the loud ones: **4.02** means previously issued financials can no longer be relied on — treat any fundamentals you already pulled as suspect.

## Example

```
you:  is HOOD worth a look?
ai:   → stock_fundamentals HOOD   revenue $1.07B, +15.1% YoY, net margin 32.8%
      → stock_insider HOOD        CEO sold ~$43M open-market; zero insider buys
      → stock_events HOOD         recent 8-K: material agreement + new debt + dilution
      → (optional) rh_stock_bridge HOOD — tokenized vs real price
```


# Base Watchdog (Token Monitoring)

Persistent monitoring for any token on Base — treasury, holders, supply health, ecosystem news, and automated alerts, running server-side even after you close the chat. Works with any ERC-20 today, and with **B20 tokens** (Base's native compliance standard for stablecoins and RWAs, live on Base mainnet since July 8, 2026) with no changes needed.

Ships as a standalone skill: [`base-watchdog/SKILL.md`](https://github.com/noelclaw/noelapp/blob/main/base-watchdog/SKILL.md) in the Noelclaw repo.

**Requires:** [`@noelclaw/mcp`](https://www.npmjs.com/package/@noelclaw/mcp)

```bash
npx -y -p @noelclaw/mcp@3.43.1 noelclaw install
noelclaw login
```

***

## Treasury Monitor

```
get_wallet_balance address="YOUR_TREASURY_ADDRESS"
base_mcp_status

create_automation
  rawInput: "Alert me if ETH balance at YOUR_TREASURY_ADDRESS drops below 10 ETH"

agent_spawn
  name: "treasury-watch"
  goal: "Monitor treasury wallet. Track ETH balance, flag large moves, summarize weekly."
  context: "Treasury: YOUR_TREASURY_ADDRESS"
```

## Holder & Supply Health

```
get_token_data question="YOUR_TOKEN_SYMBOL"
check_token address="YOUR_TOKEN_ADDRESS"
score_token address="YOUR_TOKEN_ADDRESS"

schedule_research
  topic: "YOUR_TOKEN_SYMBOL token holder distribution, supply health, and on-chain metrics on Base"
  schedule: "weekly-monday"
```

`check_token` runs a GoPlusLabs security audit (honeypot, mint/freeze authority, LP lock %, buy/sell tax, holder count). `score_token` runs a 6-component dip-reversal score against DexScreener data.

> **Quote-currency tokens:** `score_token` resolves the highest-liquidity Base pair for the address you pass in, and only scores it when your token is the *base* side of that pair. Stablecoins and RWA tokens (the B20 use case) are often the *quote* side of their most liquid pair — if so, the tool returns an explicit error rather than silently scoring the wrong asset.

## Ecosystem Updates & Weekly Reports

```
deep_research
  query: "YOUR_TOKEN_SYMBOL Base ecosystem updates announcements this week"
  depth: "deep"
  saveToVault: true

vault_save key: "watchdog/ecosystem-digest" content: "<digest>" type: "research"
vault_history key: "watchdog/ecosystem-digest"

schedule_research
  topic: "YOUR_TOKEN_SYMBOL weekly report: treasury, holders, ecosystem news"
  schedule: "weekly-monday"
```

## Automated Alerts

```
create_automation rawInput: "Alert me when YOUR_TOKEN_SYMBOL price drops more than 15% in 24h"
create_automation rawInput: "Alert me when YOUR_TOKEN_SYMBOL 24h volume exceeds $500k"

list_automations
get_automation_runs
```

***

## Full Setup

```
memory_context topic="YOUR_TOKEN_SYMBOL"
base_mcp_status
get_wallet_balance address="YOUR_TREASURY_ADDRESS"
get_token_data question="YOUR_TOKEN_SYMBOL"
check_token address="YOUR_TOKEN_ADDRESS"

agent_spawn
  name: "token-watchdog"
  goal: "Monitor YOUR_TOKEN_SYMBOL on Base: treasury, holders, ecosystem. Save weekly reports to vault. Flag anomalies."
  context: "Treasury: YOUR_TREASURY_ADDRESS | Token: YOUR_TOKEN_ADDRESS"

deep_research query: "YOUR_TOKEN_SYMBOL Base token: current status, treasury, holder metrics, recent news" depth: "deep" saveToVault: true
schedule_research topic: "YOUR_TOKEN_SYMBOL weekly report" schedule: "weekly-monday"
create_automation rawInput: "Alert me when YOUR_TOKEN_SYMBOL price drops more than 20% in 24h"
```

## Resume a Session

```
memory_context topic="YOUR_TOKEN_SYMBOL"
agent_recall name="token-watchdog"
vault_read key="watchdog/weekly-report"
chronicle_stats days=30
```

***

## Tool Reference

| Goal                        | Tool                 | Params                       |
| --------------------------- | -------------------- | ---------------------------- |
| Treasury balance            | `get_wallet_balance` | `address="0x..."`            |
| Base connection check       | `base_mcp_status`    | —                            |
| Token price + market data   | `get_token_data`     | `question="SYMBOL"`          |
| Holder count + safety audit | `check_token`        | `address="0x..."`            |
| Buy signal score            | `score_token`        | `address="0x..."`            |
| Ecosystem research          | `deep_research`      | `query="..."`                |
| Price / balance alert       | `create_automation`  | `rawInput="..."`             |
| Weekly auto-research        | `schedule_research`  | `topic`, `schedule`, `label` |
| Persistent monitor agent    | `agent_spawn`        | `name`, `goal`, `context`    |
| Recall agent                | `agent_recall`       | `name="..."`                 |
| Save report                 | `vault_save`         | `key`, `content`, `type`     |
| Restore session context     | `memory_context`     | `topic="..."`                |

## See Also

* [Wallet & DeFi](/trading-and-defi/wallet-defi)
* [All 121 Tools](/reference/mcp-server)
* [B20 Token Standard — Base Docs](https://docs.base.org/get-started/launch-b20-token)


# x402 API Market

The NoelClaw API Market (`/api-market` in the webapp) lets anyone sell an HTTPS API per call and lets agents buy calls with USDC on Base — no account or API key required. Payments use the [x402 protocol](https://www.x402.org) pattern: HTTP `402 Payment Required` as the challenge, a payment header as the receipt.

## How a paid call works

```
Agent                          NoelClaw                        Seller
  │  1. GET /market/call/slug     │                              │
  │──────────────────────────────>│                              │
  │  2. 402 + PAYMENT-REQUIRED    │                              │
  │<──────────────────────────────│                              │
  │  3. pay USDC on Base          │                              │
  │  4. retry + PAYMENT-SIGNATURE │                              │
  │──────────────────────────────>│  5. verify tx, dedupe        │
  │                               │─────────────────────────────>│
  │  7. 200 + PAYMENT-RESPONSE    │  6. proxy response           │
  │<──────────────────────────────│<─────────────────────────────│
```

1. Call `GET`/`POST` `https://api.noelclaw.com/market/call/{slug}` with no payment.
2. The server responds `402` with a `PAYMENT-REQUIRED` header — base64-encoded JSON (x402 v2 shape with an `accepts[]` array). `X-Payment-Required` is set too for legacy clients. The challenge includes:
   * `network`: `eip155:8453` (Base mainnet)
   * `asset`: USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
   * `payTo`: the settlement wallet (read it from the challenge — never hardcode)
   * `maxAmountRequired`: price in USDC micro-units (6 decimals)
   * `requestId`: unique id for this challenge
3. Pay the amount in USDC on Base to `payTo` (scheme `exact`, settled as a plain ERC-20 transfer — the tx hash is your receipt).
4. Retry the same request with the header `PAYMENT-SIGNATURE: base64("txHash:requestId")`. `X-Payment` is accepted as a legacy alias.
5. The server verifies the transfer on-chain (recipient + amount), rejects reused tx hashes and request ids, then proxies the request to the seller's private endpoint.
6. The response carries a `PAYMENT-RESPONSE` header — base64 settlement receipt with the tx hash.

Free listings (`price = 0`) skip the challenge entirely and proxy directly.

## Example

```bash
# 1) Challenge
curl -i https://api.noelclaw.com/market/call/my-api

# 2) Pay N USDC on Base to the payTo address from the challenge, then:
SIG=$(printf '0xYOUR_TX_HASH:REQUEST_ID' | base64)
curl https://api.noelclaw.com/market/call/my-api -H "PAYMENT-SIGNATURE: $SIG"
```

## Selling an API

List any HTTPS endpoint from the **Sell** tab on `/api-market`:

* The endpoint URL is never exposed to buyers — calls proxy through NoelClaw.
* Pricing is a flat USDC amount per call (cap: 100 USDC).
* Settlement: seller keeps 95%, platform fee 5%. Payout wallet is your NoelClaw Base wallet.
* Every purchase is recorded in a ledger (`apiMarketplacePurchases`) with request id, tx hash, and fee split — the same dual-write pattern used by Surplus-style markets.

## Replay protection

Each payment is single-use, enforced at two levels:

* `requestId` — one challenge, one fulfillment.
* `txHash` — one on-chain transfer can never pay for a second call, even with a new request id.

## MCP tool payments

The same machinery backs paid MCP tools (`X-Payment` header on `api.noelclaw.com` tool routes). All MCP tools are currently free — prices in `TOOL_PRICES` are set to 0 and can be re-enabled per tool. All x402 flows attach the Base Builder Code (`builderCode`) for attribution in the Base Dashboard.

## Related

* [Environment Variables](/reference/env-vars) — `NOEL_WALLET_ADDRESS`, `BASE_RPC_URL`, `BASE_BUILDER_CODE`
* [Wallet & DeFi](/trading-and-defi/wallet-defi)


# All 121 Tools

> This page is generated from the live tool registry (`ALL_TOOLS`) of `@noelclaw/mcp` — every tool below exists exactly as named, with its real description. Nothing here is aspirational.

**121 tools.** Install once, they all load — no per-tool setup. Tools that move funds require `confirm: true` and never execute from a bare estimate.

## Semantic Memory (10)

Persistent memory with semantic search, time-decay, and dedupe. Works against Noelclaw cloud or a free self-hosted supermemory server (`noelclaw setup`).

| Tool                 | What it does                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `memory_add`         | Add content to your Noelclaw semantic memory - no setup needed, no extra API keys.                                                                                                                                       |
| `memory_search`      | Hybrid memory search - fuses semantic (embedding) + lexical (full-text BM25) retrieval via Reciprocal Rank Fusion.                                                                                                       |
| `memory_context`     | Retrieve the most semantically relevant memories for a topic, formatted as AI-ready context.                                                                                                                             |
| `memory_profile`     | Show your semantic memory stats - total memories stored, your memory space, and connected sources.                                                                                                                       |
| `memory_list`        | List your most recent Noelclaw memories without a search query.                                                                                                                                                          |
| `memory_delete`      | PERMANENT. Delete a specific memory by its ID — it cannot be recovered. Get IDs from memory\_search or memory\_list. Requires confirm: true. Show the user which memory you are about to delete (title/content) and get… |
| `memory_insight`     | Get a full intelligence report on any topic - combines semantic memory AND vault entries, then identifies knowledge gaps and suggests next actions.                                                                      |
| `memory_extract`     | Save discrete facts, preferences and decisions to semantic memory as individually searchable atoms instead of one wall of text.                                                                                          |
| `memory_publish`     | IRREVERSIBLE, PUBLIC. Publish a memory snippet to the Memory Marketplace — visible to ALL Noelclaw users at /memory-marketplace. Reversible with vault\_unpublish, but only for future discovery — anyone who already…   |
| `memory_consolidate` | Clean up fragmented knowledge after heavy research sessions.                                                                                                                                                             |

## Vault (15)

Git-style versioned notes with knowledge-graph links, tags, credentials, and export. Credentials are excluded from list/search/export and only readable by exact name.

| Tool                     | What it does                                                                                                                                                                                                              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `vault_save`             | Save or update a versioned artifact in Noel-Vault.                                                                                                                                                                        |
| `vault_read`             | Read a Noel-Vault entry by its key. Returns full content, version, tags, and any linked entries.                                                                                                                          |
| `vault_list`             | List Noel-Vault entries. Filter by type, agent, or pinned status. Returns previews, not full content.                                                                                                                     |
| `vault_search`           | Search Noel-Vault using semantic AI search (powered by Supermemory) when available, with automatic fallback to full-text search.                                                                                          |
| `vault_history`          | Get the full version history of a Noel-Vault entry - like git log.                                                                                                                                                        |
| `vault_diff`             | Compare two versions of a Noel-Vault entry - like git diff.                                                                                                                                                               |
| `vault_export`           | Export your entire Noel-Vault or a specific type as a structured bundle.                                                                                                                                                  |
| `vault_store_credential` | Securely store an API key, token, or secret in your vault.                                                                                                                                                                |
| `vault_get_credential`   | Retrieve a stored credential from the vault by name.                                                                                                                                                                      |
| `vault_pin`              | Pin or unpin a Noel-Vault entry. Pinned entries always appear first in vault\_list and are prioritized in memory\_context and search results. Use for your most important research, key prompts, or canonical references. |
| `vault_unpublish`        | Make a previously shared Noel-Vault entry private again, removing it from the public community listing.                                                                                                                   |
| `vault_delete`           | PERMANENT. Delete a Noel-Vault entry and ALL of its version history — this cannot be undone. Requires confirm: true. Use vault\_list to browse first, and show the user the exact entry (key + title) you are about to…   |
| `vault_tag`              | Add or replace tags on an existing Noel-Vault entry without modifying its content.                                                                                                                                        |
| `vault_link`             | Create a semantic relationship between two Noel-Vault entries - building a knowledge graph.                                                                                                                               |
| `vault_related`          | Traverse the Noel-Vault knowledge graph - get all entries linked to a given entry.                                                                                                                                        |

## Chronicle (Audit Trail) (4)

Append-only log of everything the runtime does, searchable by keyword with activity stats.

| Tool               | What it does                                                                                                                                                                                             |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chronicle_add`    | Log an event to Noel Chronicle - the system-wide audit log for your AI runtime.                                                                                                                          |
| `chronicle_list`   | Read the Noel Chronicle event log - your AI runtime timeline.                                                                                                                                            |
| `chronicle_search` | Search the Noel Chronicle by keyword. Matches against event titles and details. Useful for finding when something specific happened: 'when did I last research ETH?' or 'find all vault saves for Base'. |
| `chronicle_stats`  | Activity stats for your AI runtime - breakdown by event type, daily activity heatmap, busiest days, and most active categories.                                                                          |

## Agents (12)

Named persistent agents that survive across sessions, accumulate learnings, and can run on a schedule.

| Tool               | What it does                                                                                                                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_agents`      | List all available specialist agents you can hire - built-in experts (analyst, risk-manager, researcher, executor, scout) plus any community-published agents.                                                 |
| `hire_agent`       | Load a specialist agent's expertise and apply it to a task YOURSELF — the tool returns the agent's full persona (its framework, thresholds and house rules) scoped to your task, and you answer in that voice. |
| `agent_spawn`      | Create a persistent NAMED agent with a goal - survives across sessions, state saved to vault under `agent/<name>` key.                                                                                         |
| `agent_recall`     | Recall a persistent agent by name - loads its goal, current progress, findings, full history, and accumulated learnings (patterns the agent extracted from past runs).                                         |
| `agent_update`     | Update a persistent agent's progress and findings.                                                                                                                                                             |
| `agent_identity`   | Get or create a persistent on-chain identity (wallet address) for a named agent.                                                                                                                               |
| `agent_ledger`     | View the full activity ledger for a persistent agent - every update, status change, and finding logged in order.                                                                                               |
| `agent_schedule`   | Attach an autonomous schedule to an existing agent.                                                                                                                                                            |
| `agent_unschedule` | Remove the autonomous schedule from an agent.                                                                                                                                                                  |
| `agent_pause`      | Pause an agent's autonomous schedule without deleting it.                                                                                                                                                      |
| `agent_resume`     | Re-enable a paused agent's schedule. Resets the consecutive-failure counter.                                                                                                                                   |
| `agent_runs`       | View recent autonomous run history for a scheduled agent - when it ran, success/failure status, vault key where the output was saved, and duration.                                                            |

## Playbooks (3)

Curated multi-step playbooks executed through the Noel Framework with a full audit ledger.

| Tool              | What it does                                                                                                                                                                                                             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_playbooks`  | List available Noel Framework playbooks - predefined multi-step workflows.                                                                                                                                               |
| `run_playbook`    | Execute a Noel Framework playbook. Each step runs through Sentinel before the matching tool executes it. Steps map directly to noelclaw tools (market, vault, agent, memory, automation). Playbook halts immediately if… |
| `get_noel_ledger` | Get the Noel Framework audit trail - every Sentinel gate decision (approved / blocked / warned), which checks ran, duration, and reason.                                                                                 |

## Automations (6)

Scheduled and conditional workflows: DCA, price alerts, conditional buy/sell. Dry-run supported.

| Tool                  | What it does                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `create_automation`   | Create an automation in plain English. Supports DCA, price alerts, conditional buys/sells, and recurring market updates.                                                                                           |
| `list_automations`    | List all your automations - active, paused, and completed - with status, run counts, and next scheduled run.                                                                                                       |
| `pause_automation`    | Pause or resume an automation by ID.                                                                                                                                                                               |
| `delete_automation`   | PERMANENT. Delete an automation — this cannot be undone. Requires confirm: true. Run list\_automations first and show the user which automation (id + name) you are about to remove. If they only want it to stop… |
| `get_automation_runs` | Get the execution history for an automation - each run's status (success/failed/skipped), amount spent, tx hash, and error message if any.                                                                         |
| `run_automation`      | Trigger an automation immediately - regardless of its schedule or trigger condition.                                                                                                                               |

## Monitors (3)

Recurring research monitors that run after you close the chat.

| Tool                | What it does                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `schedule_research` | Schedule recurring autonomous research on any topic - runs on a cron schedule, saves findings to vault, and sends a Telegram notification.                                                                               |
| `list_monitors`     | List all active scheduled research monitors - shows topic, schedule, next run, and monitor ID.                                                                                                                           |
| `cancel_monitor`    | PERMANENT. Cancel and delete a scheduled research monitor — the schedule is removed and cannot be restored. Requires confirm: true. Run list\_monitors first and show the user which monitor (id + topic) you are about… |

## Packets (Flows) (4)

Reusable multi-step workflow packets: create, run, list, share.

| Tool            | What it does                                                                                                                                                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `packet_create` | Create or update a Packet - a named, reusable AI workflow stored in your vault.                                                                                                                                         |
| `packet_run`    | Load and execute a Packet by name. Returns all steps formatted for sequential execution. After calling this, execute each step in order - tool steps are called directly, prompt steps are interpreted as instructions. |
| `packet_list`   | List all your Packets - reusable workflows stored in vault.                                                                                                                                                             |
| `packet_share`  | Publish a Packet to the community so others can discover and use it.                                                                                                                                                    |

## Deep Research (1)

Multi-angle web research. Default `mode: "sources"` returns a cited evidence pack with zero API keys; `mode: "report"` adds server-side synthesis (needs an LLM key).

| Tool            | What it does                                                                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deep_research` | Web research engine: searches, scrapes, ranks and de-duplicates sources, then returns them as a numbered, citable evidence pack for YOU to synthesise. |

## Research Compare (1)

Compare two saved research reports.

| Tool               | What it does                                                                                                                                                                                                              |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `research_compare` | Diff two vault research reports. Two-pass, no API key needed. PASS 1 — call with keyA + keyB: loads both reports, extracts their section structure, and returns both bodies plus the comparison rubric for YOU to write.… |

## Research Chain (1)

Walk a topic's research history across time.

| Tool             | What it does                                                                                                                                                                                                         |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `research_chain` | Walk a research topic's timeline. Follows `continues` relations both backward and forward from a starting report and returns the chronological list with each report's date/title/TL;DR, plus the rubric for YOU to… |

## Web Research (2)

Live web search and page scraping (proxied — no Firecrawl key needed).

| Tool         | What it does                                                              |
| ------------ | ------------------------------------------------------------------------- |
| `web_scrape` | Fetch and extract clean readable content from any URL - returns markdown. |
| `web_search` | Search the web and return raw results: titles, URLs, and snippets.        |

## Market Data (6)

Live crypto market data and structured market-thesis rubrics from verified price sources (CoinGecko, DexScreener, Pyth cross-checked).

| Tool                  | What it does                                                                                                                                                                                   |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `get_market_data`     | Get live crypto market data: top 20 coins by market cap, trending coins, and key prices for BTC/ETH/SOL.                                                                                       |
| `get_token_data`      | Get live market data for a specific token.                                                                                                                                                     |
| `compare_tokens`      | Compare 2–5 tokens side by side - price, 24h/7d change, market cap, volume, and ATH drawdown.                                                                                                  |
| `market_overview`     | Global crypto market snapshot: Fear & Greed Index, BTC dominance, total market cap, DeFi TVL, ETH gas, trending tokens, and top sector leaders.                                                |
| `token_history`       | Get historical price data for a token. Returns OHLC candles for the requested timeframe. Use to understand price trends, identify support/resistance levels, or calculate % changes over time. |
| `get_base_token_data` | Get live market data for any Base-chain token by contract address, sourced from DexScreener: price, 1h/6h/24h change, volume, liquidity, market cap, FDV, pair age, and website/social links.  |

## Token Scanner (3)

Token due-diligence on Base: score, compare, history, market scans.

| Tool          | What it does                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `score_token` | Run the 6-component dip-reversal score on any Base token.                                                                       |
| `check_token` | Security audit a Base token: honeypot, rug risk score, mint authority, freeze authority, LP lock %, buy/sell tax, holder count. |
| `scan_market` | Scan all trending + new Base pools for trading opportunities.                                                                   |

## Wallet & DeFi (Base) (1)

Custodial-style local MCP wallet (key stored in `~/.noelclaw`), balances, DeFi yields, trade planning.

| Tool              | What it does                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------- |
| `get_defi_yields` | Fetch top DeFi yield opportunities on Base - Morpho, Moonwell, Aerodrome, Uniswap, and more. |

## Base MCP (base\_mcp\_\*) (7)

Full Base mainnet (8453) rail: balances via Blockscout enumeration with impostor-token detection, sends, 0x Permit2 swaps, Morpho/Moonwell yield data, basename resolution. See [Base](/trading-and-defi/base).

| Tool                | What it does                                                                                                                                                                                                            |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `base_mcp_status`   | Base MCP - get live status of your Base wallet: address, chain info, current ETH price, gas.                                                                                                                            |
| `base_mcp_balance`  | Base MCP - get your current token balances on Base mainnet (ETH, USDC, USDT, DAI, WETH).                                                                                                                                |
| `base_mcp_send`     | IRREVERSIBLE. Send ETH or ERC-20 tokens to any address (or basename like `jesse.base.eth`) on Base mainnet. Signed and broadcast locally from your wallet — an on-chain transfer cannot be recalled. Requires confirm:… |
| `base_mcp_swap`     | Base MCP - swap tokens on Base (chainId 8453) via 0x Protocol Permit2 (signature-based, no separate approval tx).                                                                                                       |
| `base_mcp_estimate` | Base MCP - preview a swap's expected output and price impact without executing.                                                                                                                                         |
| `base_mcp_lend`     | Base MCP - find the best lending venues for a token on Base (Morpho vaults + Moonwell markets), ranked by APY × TVL safety score.                                                                                       |
| `base_mcp_resolve`  | Base MCP - resolve a Base basename (like `jesse.base.eth`) to its 0x address.                                                                                                                                           |

## Base Network Data (4)

Read-only Base network stats and yield/lending data.

| Tool                     | What it does                                                                                                                |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `base_mcp_yield_vaults`  | Find the best yield/earning opportunities on Base chain using Morpho vaults.                                                |
| `base_mcp_lending_rates` | Get lending and borrowing rates across all Moonwell markets on Base.                                                        |
| `base_mcp_deposit_guide` | Get step-by-step deposit instructions for a Morpho vault — shows the vault address, expected APY, and manual deposit steps. |
| `base_mcp_network`       | Get real-time Base network stats: ETH price in USD, gas price in gwei, and latest block number.                             |

## Robinhood Chain (rh\_\*) (8)

Tokenized stocks + arbitrary crypto on Robinhood Chain (4663) with V2/V3/V4 best-fill routing, market and safety pre-screens. See [Robinhood Chain](/trading-and-defi/robinhood).

| Tool                 | What it does                                                                                                                                         |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rh_mcp_status`      | Robinhood Chain MCP - status of RH rail (chainId 4663): wallet address, RPC, ETH gas balance on RH, explorer.                                        |
| `rh_mcp_list_stocks` | Robinhood Chain MCP - list the 22 NoelClaw/ClawHood tokenized stock tickers (symbol, name, contract address) tradeable via Uniswap V4 on chain 4663. |
| `rh_mcp_balance`     | Robinhood Chain MCP - ETH + tokenized stock balances on RH (chain 4663) for your NoelClaw MCP wallet (same address as Base).                         |
| `rh_mcp_estimate`    | Robinhood Chain MCP - preview ETH↔token swap quote via Uniswap V4 (direct or multi-hop via USDG).                                                    |
| `rh_mcp_swap`        | Robinhood Chain MCP - execute ETH↔token swap on chain 4663.                                                                                          |
| `rh_token_resolve`   | Robinhood Chain MCP - resolve a crypto ticker OR 0x contract address to a tradeable token on chain 4663 via DexScreener.                             |
| `rh_analyze`         | Robinhood Chain MCP - market + risk pre-screen for any RH-chain token (ticker or 0x address).                                                        |
| `rh_safety_check`    | Robinhood Chain MCP - free onchain safety scan for a token (ticker or 0x address).                                                                   |

## Robinhood Chain Orders (5)

Local DCA / take-profit / stop-loss order engine. Orders persist to `~/.noelclaw/rh-orders.json`; `rh_orders_tick` previews by default and only trades with `execute: true`.

| Tool                | What it does                                                                                                                               |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `rh_dca_create`     | Robinhood Chain — create a DCA plan: buy a fixed ETH amount of a token every N hours, up to a total number of buys, capped by maxSpendEth. |
| `rh_bracket_create` | Robinhood Chain — set take-profit and/or stop-loss on a token you HOLD.                                                                    |
| `rh_orders_list`    | Robinhood Chain — list saved DCA / TP / SL orders and their progress.                                                                      |
| `rh_order_cancel`   | Robinhood Chain — cancel a saved order by id (stops future DCA buys / TP-SL fills).                                                        |
| `rh_orders_tick`    | Robinhood Chain — evaluate all active orders and act on any that are due (DCA interval reached) or triggered (TP/SL price crossed).        |

## Stock Bridge (1)

Tokenized stock vs real US equity: price gap, pool depth, market open/closed.

| Tool              | What it does                                                                                                                                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rh_stock_bridge` | Compare a tokenized stock on Robinhood Chain (4663) against the real US equity: on-chain price vs live share price, the premium/discount between them, pool depth, and whether the US market is currently open. |

## Stock Fundamentals (SEC) (1)

Company financials straight from SEC EDGAR XBRL — as filed, not vendor copies. See [Stocks & SEC Data](/trading-and-defi/stocks-sec).

| Tool                 | What it does                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------------- |
| `stock_fundamentals` | Fetch a public company's financials straight from SEC EDGAR XBRL (as filed in 10-Q/10-K) plus a live quote. |

## Insider Activity (SEC) (1)

Form 4 insider transactions with discretionary trades separated from automatic ones.

| Tool            | What it does                                                                               |
| --------------- | ------------------------------------------------------------------------------------------ |
| `stock_insider` | Parse recent SEC Form 4 insider transactions for a US-listed company, straight from EDGAR. |

## Material Events (SEC) (1)

Form 8-K timeline with item codes decoded into plain language.

| Tool           | What it does                                                                                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stock_events` | Timeline of a US company's material events from SEC Form 8-K, with the item codes decoded into plain language — earnings releases, executive departures, debt raises, dilution, restatements, impairments, layoffs. |

## GitHub (8)

Read-only GitHub integration: repos, PRs, issues, files, commits, code search.

| Tool                 | What it does                                                                                                                                                      |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `github_list_repos`  | List GitHub repositories for a user or org.                                                                                                                       |
| `github_list_prs`    | List pull requests for a GitHub repository.                                                                                                                       |
| `github_get_pr`      | Get full details of a pull request - title, body, diff summary, changed files, reviews, and comments.                                                             |
| `github_list_issues` | List issues for a GitHub repository. Returns issue number, title, author, labels, comment count.                                                                  |
| `github_get_issue`   | Get a GitHub issue with full body and all comments.                                                                                                               |
| `github_get_file`    | Read a file from a GitHub repository. Returns decoded content (up to 10k chars). Use for reading code, configs, READMEs.                                          |
| `github_get_commits` | Get recent commits for a repo, branch, or specific file.                                                                                                          |
| `github_search_code` | Search code on GitHub. Supports qualifiers: repo:owner/repo, language:typescript, path:src/, filename:package.json, etc. Requires GITHUB\_TOKEN for best results. |

## Code Audit (1)

Static Solidity security scan with a structured review rubric (no LLM).

| Tool             | What it does                                                                                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audit_contract` | Run a deterministic static scan over Solidity source for common antipatterns (tx.origin auth, reentrancy ordering, unchecked low-level calls, delegatecall hijack, floating pragma, etc). |

## Noel Insight (3)

Ask the hosted Noel agent (used by playbooks; needs backend LLM).

| Tool            | What it does                                                                                                                                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ask_noel`      | Ask Noel anything - analysis, opinions, explanations, strategy, or ideas.                                                                                                                                             |
| `market_thesis` | Fetch a cross-checked live price for any token (CoinGecko + DexScreener + Pyth, with a source-spread warning when they disagree) and return it with the bull/bear/verdict structure for YOU to write.                 |
| `trade_plan`    | Return the verified inputs for a trade plan on any token: cross-checked live price, a table of stop-loss and take-profit price levels computed off spot (signed for long or short), and position sizing math for the… |

## MiroShark Simulation (3)

Agent-market simulation runs.

| Tool                 | What it does                                          |
| -------------------- | ----------------------------------------------------- |
| `miroshark_simulate` | Simulate any scenario using MiroShark multi-agent AI. |
| `miroshark_status`   | Poll the status of a MiroShark simulation.            |
| `miroshark_stop`     | Stop a running MiroShark simulation.                  |

## Runtime / OS (3)

Status, diagnostics, and Noel Shell chat bridge.

| Tool               | What it does                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `noel_status`      | Full runtime dashboard - memory size, persistent agents, active automations, recent vault research, execution scores, and your tier. |
| `noel_diagnostics` | Health check for all Noelclaw services - Convex backend, Firecrawl, Supermemory, and configured API keys.                            |
| `noel_shell_chat`  | Chat with Noel Shell — AI terminal with tool calling.                                                                                |

## Wallet Signing (3)

Prove wallet ownership off-chain.

| Tool                  | What it does                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_wallet_address`  | Get your Noelclaw wallet address. This is the local MCP wallet used to sign requests and receive on-chain assets. Keys never leave your machine. |
| `get_wallet_balance`  | Check ETH and USDC balance of your Noelclaw wallet on Base mainnet.                                                                              |
| `wallet_sign_message` | CAUTION: Sign an arbitrary message with the user's wallet (EIP-191 personal\_sign).                                                              |

***

## Related

* [Base DeFi](/trading-and-defi/base) — the `base_mcp_*` rail in depth
* [Robinhood Chain](/trading-and-defi/robinhood) — the `rh_*` rail in depth
* [Stocks & SEC Data](/trading-and-defi/stocks-sec) — `stock_fundamentals` / `stock_insider` / `stock_events`
* [Environment Variables](/reference/env-vars)


# Environment Variables

The MCP server reads these from your local environment - set them in your MCP client config under the `env` block. All are optional unless noted.

***

## MCP Server Variables

| Variable             | Required                          | Purpose                                                                                                            |
| -------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `ANTHROPIC_API_KEY`  | no                                | Use your own Anthropic key for the CLI agent. Without it, calls proxy through the Noelclaw platform automatically  |
| `BANKR_API_KEY`      | no                                | Use Bankr LLM gateway (Claude + Grok via single API) for the CLI agent instead of Anthropic direct                 |
| `ANTHROPIC_MODEL`    | no                                | Override model for the CLI agent (default: `claude-haiku-4-5-20251001`)                                            |
| `FIRECRAWL_API_KEY`  | for `deep_research`, `web_search` | Required for `deep_research` and `web_search`; optional for `web_scrape` (falls back to basic fetch)               |
| `TRIGGER_SECRET_KEY` | for `schedule_research`           | Required for autonomous scheduled monitors                                                                         |
| `ALCHEMY_API_KEY`    | no                                | Faster swap quotes and Base mainnet balance lookups                                                                |
| `TELEGRAM_BOT_TOKEN` | no                                | Your Telegram bot token - for monitor and automation notifications                                                 |
| `TELEGRAM_CHAT_ID`   | no                                | Your Telegram chat ID for delivery                                                                                 |
| `GITHUB_TOKEN`       | no                                | GitHub personal access token - required for private repos and higher API rate limits. Public repos work without it |

> **Telegram** is only needed if you want push notifications outside your AI client. If you use Noelclaw through Claude, Cursor, Hermes, or Aeon, you already get all results inline.

***

## How to Set Them

### Claude Code

```bash
claude mcp add noelclaw -s user -- npx -y -p @noelclaw/mcp@3.43.1 noelclaw-mcp
```

Then edit `~/.claude.json` to add env vars under the server entry:

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MINIMAX_API_KEY": "your-key"
      }
    }
  }
}
```

### Claude Desktop

Mac: `~/Library/Application Support/Claude/claude_desktop_config.json` Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "noelclaw": {
      "command": "npx",
      "args": ["-y", "-p", "@noelclaw/mcp@3.43.1", "noelclaw-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MINIMAX_API_KEY": "your-key"
      }
    }
  }
}
```

### Hermes

```yaml
mcp_servers:
  noelclaw:
    command: npx
    args:
      - "-y"
      - "-p"
      - "@noelclaw/mcp@3.43.1"
      - "noelclaw-mcp"
    env:
      MINIMAX_API_KEY: your-key
    timeout: 30
    connect_timeout: 10
```

***

## Which Variables Do You Actually Need?

For most users, **no variables are required** - all 121 tools work out of the box:

* A local wallet auto-generates at `~/.noelclaw/wallet.json` on first use
* Market data, vault, memory, swarm, MiroShark - no keys needed
* `base_mcp_swap`, `base_mcp_send`, `rh_mcp_swap` - just need a funded local wallet

Add keys only if you want:

* Your own Anthropic account for the CLI agent → `ANTHROPIC_API_KEY`
* Bankr/Grok-3 for the CLI agent → `BANKR_API_KEY`
* Telegram notifications → `TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID`
* GitHub private repos + higher rate limits → `GITHUB_TOKEN`


# Architecture

## How It Works

Noelclaw is a local MCP server (`@noelclaw/mcp`) that runs as a Node.js process on your machine. When you ask your AI a question, the MCP server handles it - some requests are answered directly from local data, others call the Noelclaw API.

```
  AI Clients
  ┌──────────────────────────────────────────────┐
  │  Claude Desktop / Claude Code / Cursor       │
  │  Windsurf / Hermes / Aeon / Bankr            │
  └─────────────────┬────────────────────────────┘
                    │ MCP protocol (stdio)
                    ▼
         ┌─────────────────────┐
         │   @noelclaw/mcp     │
         │   Node.js, local    │
         │   121 tools         │
         └──────────┬──────────┘
                    │
       ┌────────────┼────────────────┐
       │            │                │
       ▼            ▼                ▼
  CoinGecko   DeFiLlama       api.noelclaw.com
  (prices)    (yields)        (vault, memory,
  free, no    free, no         automations,
  key needed  key needed       swarm, AI, etc.)
```

***

## What Runs Where

| Category                                    | Where                | Details                   |
| ------------------------------------------- | -------------------- | ------------------------- |
| Market prices                               | CoinGecko (direct)   | Free, no API key needed   |
| DeFi yields                                 | DeFiLlama (direct)   | Free, no API key needed   |
| Token swap quotes                           | 0x Protocol (direct) | Free routing API          |
| Vault, memory, automations                  | `api.noelclaw.com`   | Persisted to your account |
| AI analysis (ask\_noel, thesis, trade plan) | `api.noelclaw.com`   | Proxied to Claude or Grok |
| Swarm, monitors, OS tools                   | `api.noelclaw.com`   | Noelclaw backend          |
| Wallet signing                              | Local only           | Never leaves your machine |

***

## API - api.noelclaw\.com

All cloud tools go through `api.noelclaw.com`. This endpoint handles:

* **Auth** - every request is authenticated by a wallet signature (generated automatically) or a session token
* **Rate limiting** - 100 requests/min per IP
* **BYOK header forwarding** - your own API keys (`X-User-*` headers) are forwarded to the right backend
* **Retry handling** - auto-retry on 429 and 5xx responses

***

## Authentication

Noelclaw uses wallet-based auth by default - no account or login required.

```
First run:
  ~/.noelclaw/wallet.json is created
  → contains a local Ethereum keypair (Base mainnet)
  → address is derived from the private key

Per request:
  MCP server signs: "noelclaw:{toolName}:{timestamp}"
  → sends X-Wallet-Address + X-Wallet-Signature + X-Wallet-Timestamp
  → API verifies the signature
  → request is authorized
```

Your private key never leaves your machine. The API only sees the wallet address and the signature - never the key itself.

If you have a session token (`NOELCLAW_SESSION_TOKEN`), it's used instead of wallet signing - simpler, and unlocks full tool access without a funded wallet.

***

## Data Flow: Tool Call

```
User prompts AI
      │
      ▼  MCP protocol (stdio)
@noelclaw/mcp - validates input with Zod
      │
      ├── Market/yield tools → direct to CoinGecko / DeFiLlama
      │
      └── Everything else → HTTPS POST to api.noelclaw.com
            → auth header (wallet sig or session token)
            → BYOK headers forwarded if set
            → response returned to MCP server
                  │
                  ▼  MCP protocol
            AI client renders result
```

***

## Data Flow: Autonomous Monitor

```
schedule_research called
      │
      ▼
1. Schedule registered on Trigger.dev (via api.noelclaw.com)
2. Monitor config (topic, label, cron) saved to vault
      │
At scheduled time (e.g. 8am daily):
      ▼
3. Trigger.dev fires the worker
4. Worker calls Firecrawl to search the web for the topic
5. LLM summarizes findings, assigns urgency 1–5
6. Summary saved to vault (versioned history)
7. Telegram notification sent (if configured)
      │
      ▼
Next run: compares new findings to previous briefing
→ highlights what changed since last time
```

***

## Data Flow: Wallet Transactions

```
base_mcp_swap / base_mcp_send called
      │
      ▼
@noelclaw/mcp:
  → fetches quote / tx params from api.noelclaw.com
  → MCP server signs the transaction locally (ethers.js)
  → MCP server broadcasts signed tx to Base mainnet directly
```

The private key is at `~/.noelclaw/wallet.json` and never leaves the local machine. The API helps build the transaction but never holds or sees your key.

***

## Data Flow: Swarm Research

```
swarm_research called
      │
      ▼
POST api.noelclaw.com/swarm/research
  → 5 agents run in parallel:
      market-monitor, sentiment-tracker,
      workflow-executor, memory-manager, risk-verifier
  → agents share findings via common memory
  → results merged into one summary
  → auto-saved to vault
```

***

## Security Model

| Concern                 | How It's Handled                                                                  |
| ----------------------- | --------------------------------------------------------------------------------- |
| Private key             | Stored at `~/.noelclaw/wallet.json`, never sent anywhere                          |
| API keys                | Set as env vars in your MCP config, forwarded as `X-User-*` headers, never logged |
| Auth                    | Wallet signature per request - or session token from app.noelclaw\.com            |
| Rate limiting           | 100 req/min per IP at the API layer                                               |
| Agent safety            | Sentinel gates all Framework actions before execution                             |
| Private key decryption  | `getDecryptedPKByUserId` is internalAction only — never callable from client      |
| Wallet creation         | `createWallet` is internalAction only — prevents arbitrary wallet creation        |
| Private key retrieval   | `getPrivateKey` returns address only, never the raw key                           |
| Session / API key abuse | Rate-limited auth + short-lived session tokens                                    |

**8 security boundaries** enforced across the backend + **5 vulnerability fixes** in v3.32.7.

***

## Environment Variables

All optional. Set in the `env` block of your MCP config.

| Variable                 | What It Does                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| `NOELCLAW_SESSION_TOKEN` | Session token from app.noelclaw\.com - simplest auth, recommended                                    |
| `ANTHROPIC_API_KEY`      | Use your own Claude quota instead of the platform                                                    |
| `BANKR_API_KEY`          | Use Bankr/Grok instead of Anthropic                                                                  |
| `FIRECRAWL_API_KEY`      | Required for `deep_research` and `web_search`; optional for `web_scrape` (falls back to basic fetch) |
| `TRIGGER_SECRET_KEY`     | Required for schedule\_research (Trigger.dev)                                                        |
| `TELEGRAM_BOT_TOKEN`     | Your Telegram bot token - for monitor notifications                                                  |
| `TELEGRAM_CHAT_ID`       | Your Telegram chat ID - for monitor delivery                                                         |
| `ALCHEMY_API_KEY`        | Faster swap quotes and Base balance lookups                                                          |