wickedapi-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,67 +1,109 @@
-# WickedAPI MCP Server
-
-MCP server for [WickedAPI](https://api.wickedapi.com) — an agent-ready trading & market-data API covering crypto/stock prices, OHLCV, technical indicators (ATR, Fair Value Gaps, ICT liquidity levels), perp funding/OI, order books, Kalshi prediction markets, DeFi TVL, volatility, a verified macro calendar, an earnings calendar, and an AI momentum score.
-
-Tools are generated automatically from the live [`openapi.json`](https://api.wickedapi.com/openapi.json), so the tool list always matches what's actually deployed.
-
-## No signup required
-
-Every tool call hits a real `/v1/*` endpoint that's gated by [x402](https://x402.org) (HTTP-native pay-per-call, USDC on Base) with an API-key fallback:
-
-- **Zero config** — calls without credentials still work; you'll get back the real `402` payment challenge (price, network, `payTo`) as the tool result.
-- **Autonomous pay-per-call** — set `WICKEDAPI_PAYER_PRIVATE_KEY` to a funded Base-mainnet wallet's private key, and every call auto-pays ~$0.001 in USDC and returns real data. No account, no subscription.
-- **Partner API key** — set `WICKEDAPI_API_KEY` for free, rate-limited access if you have one.
-
-## Install
-
-```json
-{
-  "mcpServers": {
-    "wickedapi": {
-      "command": "npx",
-      "args": ["-y", "wickedapi-mcp"],
-      "env": {
-        "WICKEDAPI_API_KEY": "your-key-here"
-      }
-    }
-  }
-}
-```
-
-Or for autonomous pay-per-call instead of a key:
-
-```json
-{
-  "mcpServers": {
-    "wickedapi": {
-      "command": "npx",
-      "args": ["-y", "wickedapi-mcp"],
-      "env": {
-        "WICKEDAPI_PAYER_PRIVATE_KEY": "0xyour-base-wallet-private-key"
-      }
-    }
-  }
-}
-```
-
-## Environment variables
-
-| Var | Required | Notes |
-| --- | --- | --- |
-| `WICKEDAPI_API_KEY` | no | Free, rate-limited access if you have a partner key. |
-| `WICKEDAPI_PAYER_PRIVATE_KEY` | no | Base-mainnet wallet private key. If set, every call auto-pays the x402 challenge in USDC — no key needed. |
-| `WICKEDAPI_BASE_URL` | no | Override the API base (default `https://api.wickedapi.com`). |
-
-If neither `WICKEDAPI_API_KEY` nor `WICKEDAPI_PAYER_PRIVATE_KEY` is set, calls still succeed at the protocol level — you'll get the real `402` challenge back as the tool result instead of data.
-
-## Local development
-
-```bash
-npm install
-npm run build
-node dist/index.js
-```
-
-## What this is not
-
-This server doesn't reimplement any data logic — it's a thin, auto-generated bridge from MCP tool calls to the live WickedAPI HTTP endpoints. All the actual market data, indicators, and scoring live in the API itself.
+# WickedAPI MCP Server
+
+MCP server for the whole [Wicked](https://wickedapi.com) suite — trading data, DeFi protocol health, token safety, brokerage sync, agent identity, reputation, a tool-reliability registry, hallucination checks, persistent agent memory, and x402 paywalls, in one server.
+
+**70 tools** across 10 live services. The first four are generated automatically from each service's own live `openapi.json`, so the list always matches what's deployed; the rest are hand-written because they use wallet signatures and non-`/v1` routes:
+
+| Service | Tools | Auth |
+| --- | --- | --- |
+| [Trading Data API](https://api.wickedapi.com) | 22 (unprefixed: `price`, `ohlcv`, `fvg`, `momentum_score`, `sentiment`, `macro_calendar`, …) | API key or x402, 5 free |
+| [Protocol Health Oracle](https://protocol-health-oracle.wickedapi.com) | 6 (`protocol_health_*`) | API key or x402, scoreboard free |
+| [Token Risk Oracle](https://token-risk-oracle.wickedapi.com) | 1 (`token_risk`) | 100% free, no key |
+| [Broker Sync API](https://broker-sync-api.wickedapi.com) | 6 (`broker_sync_*`) | API key or x402 |
+| [Wicked Reputation](https://stake.wickedapi.com) | 5 (`reputation_*`) | free, no key |
+| [Wicked Registry](https://registry.wickedapi.com) | 6 (`registry_*`) | search/detail: key or x402; featured/badge/report free; register needs your signature |
+| [Wicked Identity](https://verify.wickedapi.com) | 6 (`identity_*`) | status: key or x402; the rest need your wallet signature over a nonce |
+| [Wicked Sanity](https://sanity.wickedapi.com) | 2 (`sanity_check`, `sanity_check_batch`) | key or x402 |
+| [Wicked Memory](https://memory.wickedapi.com) | 8 (`memory_prepare`, `memory_store`, `memory_search`, …) | wallet signature on every call; only search is metered |
+| [x402 Paywall](https://paywall.wickedapi.com) | 8 (`paywall_*`) | `paywall_signup` is open; the rest need the tenant key |
+
+Plus **6 resources** (the platform directory, `llms.txt`, and each service's live endpoint catalog) and **3 prompts** (`rug_check`, `vet_dependency`, `morning_briefing`) that chain tools together the way the [cookbook](../cookbooks/wickedapi-cookbook.md) does.
+
+These tools never sign anything or hold a key. Identity, Registry registration and Memory take a signature you produce with your own wallet (`identity_get_nonce` / `memory_prepare` return the exact message to sign). Calls that need x402 payment return the real `402` challenge (decoded under `payment_required` for x402 v2) rather than auto-paying — `WICKEDAPI_PAYER_PRIVATE_KEY` auto-pay applies to the Trading, Protocol Health, Token Risk and Broker Sync tools.
+
+## No signup required
+
+Every tool hits a real endpoint gated by [x402](https://x402.org) (HTTP-native pay-per-call, USDC on Base) with an API-key fallback — and the Token Risk Oracle tool is free no matter what:
+
+- **Zero config** — calls without credentials still work; paid endpoints return the real `402` payment challenge (price, network, `payTo`) as the tool result.
+- **Autonomous pay-per-call** — set `WICKEDAPI_PAYER_PRIVATE_KEY` to a funded Base-mainnet wallet's private key, and every call auto-pays ~$0.001 in USDC and returns real data. No account, no subscription.
+- **Partner API key** — set `WICKEDAPI_API_KEY` for free, rate-limited access across all four services (same key works everywhere).
+
+## Install
+
+```json
+{
+  "mcpServers": {
+    "wickedapi": {
+      "command": "npx",
+      "args": ["-y", "wickedapi-mcp"],
+      "env": {
+        "WICKEDAPI_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+Or for autonomous pay-per-call instead of a key:
+
+```json
+{
+  "mcpServers": {
+    "wickedapi": {
+      "command": "npx",
+      "args": ["-y", "wickedapi-mcp"],
+      "env": {
+        "WICKEDAPI_PAYER_PRIVATE_KEY": "0xyour-base-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+Nothing configured? The Token Risk Oracle tool and the 5 free Trading Data API endpoints (`sentiment`, `macro_calendar`, `market_overview`, `gas`, `kalshi_probability`) still work with zero setup.
+
+## Resources
+
+Read without calling a tool — useful for a client that surfaces resources in its UI:
+
+- `wickedapi://platform/services` — the full service directory (JSON)
+- `wickedapi://platform/llms` — the platform's `llms.txt`
+- `wickedapi://trading/status`, `wickedapi://protocol_health/status`, `wickedapi://token_risk/status`, `wickedapi://broker_sync/status` — each service's live endpoint catalog
+
+## Prompts
+
+One-click workflows that chain real tool calls (Claude Desktop and other prompt-aware clients surface these directly):
+
+- **`rug_check`** (`address`, `chain`, optional `symbol`) — token risk check + market sentiment + optional momentum read, before buying.
+- **`vet_dependency`** (`slug`, optional `token_address`, `chain`) — protocol health + optional contract-level risk check, before building on a DeFi protocol.
+- **`morning_briefing`** (optional `symbol`) — macro calendar + earnings calendar + sentiment + momentum verdict, as one digest.
+
+## Environment variables
+
+| Var | Required | Notes |
+| --- | --- | --- |
+| `WICKEDAPI_API_KEY` | no | Free, rate-limited access across all four services (same key works everywhere). |
+| `WICKEDAPI_PAYER_PRIVATE_KEY` | no | Base-mainnet wallet private key. If set, every call auto-pays the x402 challenge in USDC — no key needed. |
+| `WICKEDAPI_BASE_URL` | no | Override the Trading Data API base (default `https://api.wickedapi.com`). |
+| `WICKEDAPI_PROTOCOL_HEALTH_URL` | no | Override the Protocol Health Oracle base (default `https://protocol-health-oracle.wickedapi.com`). |
+| `WICKEDAPI_TOKEN_RISK_URL` | no | Override the Token Risk Oracle base (default `https://token-risk-oracle.wickedapi.com`). |
+| `WICKEDAPI_BROKER_SYNC_URL` | no | Override the Broker Sync API base (default `https://broker-sync-api.wickedapi.com`). |
+| `REGISTRY_API_KEY` / `IDENTITY_API_KEY` / `SANITY_API_KEY` / `MEMORY_API_KEY` | no | Free-tier keys for the paid calls of Registry, Identity, Sanity and Memory search. Omit to get the x402 challenge instead. |
+| `PAYWALL_API_KEY` | for `paywall_*` | Tenant Bearer key returned once by `paywall_signup`. |
+| `REPUTATION_BASE_URL` / `REGISTRY_BASE_URL` / `IDENTITY_BASE_URL` / `SANITY_BASE_URL` / `MEMORY_BASE_URL` / `PAYWALL_BASE_URL` | no | Override the matching service base (defaults are the `*.wickedapi.com` hosts). |
+| `WICKEDAPI_SHOWCASE_URL` | no | Override the platform directory base used by resources (default `https://wickedapi.com`). |
+
+If neither `WICKEDAPI_API_KEY` nor `WICKEDAPI_PAYER_PRIVATE_KEY` is set, paid calls still succeed at the protocol level — you'll get the real `402` challenge back as the tool result instead of data. If one service's spec fails to load (network hiccup, that service is down), its tools are simply skipped for the session — the rest still register normally.
+
+## Local development
+
+```bash
+npm install
+npm run build
+node dist/index.js
+```
+
+## What this is not
+
+This server doesn't reimplement any data logic — it's a thin bridge from MCP tool calls to the live Wicked HTTP endpoints across all ten services. All the actual market data, indicators, scoring, and risk signals live in the APIs themselves.

package/dist/index.js

@@ -2,21 +2,52 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-const BASE_URL = (process.env.WICKEDAPI_BASE_URL || "https://api.wickedapi.com").replace(/\/$/, "");
+import { registerSuiteTools } from "./suite.js";
+function envUrl(name, fallback) {
+    return (process.env[name] || fallback).replace(/\/$/, "");
+}
+const SERVICES = [
+    { id: "trading", name: "Trading Data API", baseUrl: envUrl("WICKEDAPI_BASE_URL", "https://api.wickedapi.com") },
+    { id: "protocol_health", name: "Protocol Health Oracle", baseUrl: envUrl("WICKEDAPI_PROTOCOL_HEALTH_URL", "https://protocol-health-oracle.wickedapi.com") },
+    { id: "token_risk", name: "Token Risk Oracle", baseUrl: envUrl("WICKEDAPI_TOKEN_RISK_URL", "https://token-risk-oracle.wickedapi.com") },
+    { id: "broker_sync", name: "Broker Sync API", baseUrl: envUrl("WICKEDAPI_BROKER_SYNC_URL", "https://broker-sync-api.wickedapi.com") },
+];
+const SHOWCASE_URL = envUrl("WICKEDAPI_SHOWCASE_URL", "https://wickedapi.com");
 const API_KEY = process.env.WICKEDAPI_API_KEY;
 const PAYER_KEY = process.env.WICKEDAPI_PAYER_PRIVATE_KEY;
+// A few auto-generated tool names collide or read badly (e.g. GET and POST
+// both hitting /v1/protocols) — override just those, keyed by
+// "METHOD /openapi/path/{param}".
+const TOOL_NAME_OVERRIDES = {
+    protocol_health: {
+        "GET /v1/protocols": "protocol_health_list_protocols",
+        "POST /v1/protocols": "protocol_health_track_protocol",
+        "GET /v1/health/{slug}": "protocol_health_score",
+        "POST /v1/refresh": "protocol_health_refresh_all",
+        "POST /v1/ingest": "protocol_health_sync_universe",
+    },
+    broker_sync: {
+        "POST /v1/users": "broker_sync_register_user",
+    },
+};
 // If a funded Base-mainnet wallet key is provided, every call auto-pays the
 // x402 402 challenge in USDC — no API key or signup needed at all. Loaded
 // lazily so a plain API-key setup never has to pull in viem/x402-fetch.
 async function buildFetcher() {
     if (!PAYER_KEY)
         return fetch;
-    const [{ createWalletClient, http }, { privateKeyToAccount }, { base }, { wrapFetchWithPayment }] = await Promise.all([
-        import("viem"),
-        import("viem/accounts"),
-        import("viem/chains"),
-        import("x402-fetch"),
-    ]);
+    let deps;
+    try {
+        deps = await Promise.all([import("viem"), import("viem/accounts"), import("viem/chains"), import("x402-fetch")]);
+    }
+    catch {
+        console.error("[wickedapi-mcp] WICKEDAPI_PAYER_PRIVATE_KEY is set, but the wallet-payment dependencies " +
+            "(viem, x402-fetch) aren't installed in this distribution. Falling back to plain fetch — " +
+            "calls without an API key will surface the 402 challenge instead of auto-paying. " +
+            "Use `npx wickedapi-mcp` for full auto-pay support.");
+        return fetch;
+    }
+    const [{ createWalletClient, http }, { privateKeyToAccount }, { base }, { wrapFetchWithPayment }] = deps;
     const account = privateKeyToAccount(PAYER_KEY);
     const wallet = createWalletClient({ account, chain: base, transport: http() });
     console.error(`[wickedapi-mcp] x402 auto-pay enabled — wallet ${account.address}`);
@@ -25,65 +56,275 @@ async function buildFetcher() {
     // wallet client the same way — cast rather than pull in publicActions.
     return wrapFetchWithPayment(fetch, wallet);
 }
-function toolNameFromPath(path) {
-    return path.replace(/^\/v1\//, "").replace(/-/g, "_");
+function pathSlug(openapiPath) {
+    return openapiPath
+        .replace(/^\/v1\//, "")
+        .replace(/[{}]/g, "")
+        .replace(/[\/\-]+/g, "_");
+}
+function toolNameFor(service, method, openapiPath) {
+    const override = TOOL_NAME_OVERRIDES[service.id]?.[`${method.toUpperCase()} ${openapiPath}`];
+    if (override)
+        return override;
+    const slug = pathSlug(openapiPath);
+    if (service.id === "trading")
+        return slug; // legacy naming, already published
+    return slug === service.id ? service.id : `${service.id}_${slug}`;
 }
-function zodForParam(p) {
-    const type = p.schema?.type;
-    const base = type === "number" ? z.coerce.number() : type === "boolean" ? z.coerce.boolean() : z.string();
+function zodFor(p) {
+    const base = p.type === "number" || p.type === "integer"
+        ? z.coerce.number()
+        : p.type === "boolean"
+            ? z.coerce.boolean()
+            : z.string();
     const described = p.description ? base.describe(p.description) : base;
     return p.required ? described : described.optional();
 }
-async function main() {
-    const specRes = await fetch(`${BASE_URL}/openapi.json`);
-    if (!specRes.ok) {
-        throw new Error(`Failed to load ${BASE_URL}/openapi.json: HTTP ${specRes.status}`);
+async function loadServiceSpec(service) {
+    try {
+        const res = await fetch(`${service.baseUrl}/openapi.json`);
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        return (await res.json());
     }
-    const doc = (await specRes.json());
-    const doFetch = await buildFetcher();
-    const server = new McpServer({ name: "wickedapi", version: "0.1.0" });
+    catch (err) {
+        console.error(`[wickedapi-mcp] WARNING: couldn't load ${service.name} spec (${service.baseUrl}/openapi.json): ` +
+            `${err.message} — its tools are unavailable this session, the rest load normally.`);
+        return null;
+    }
+}
+function registerServiceTools(server, service, doc, doFetch) {
     let registered = 0;
-    for (const [path, methods] of Object.entries(doc.paths)) {
-        const op = methods.get;
-        if (!op || !path.startsWith("/v1/") || path === "/v1/status")
-            continue;
-        const shape = {};
-        for (const p of op.parameters ?? []) {
-            if (p.in !== "query")
-                continue;
-            shape[p.name] = zodForParam(p);
-        }
-        server.registerTool(toolNameFromPath(path), {
-            description: [op.summary, op.description].filter(Boolean).join(" — ").slice(0, 1000),
-            inputSchema: shape,
-        }, async (args) => {
-            const url = new URL(BASE_URL + path);
-            for (const [k, v] of Object.entries(args ?? {})) {
-                if (v !== undefined && v !== null)
-                    url.searchParams.set(k, String(v));
+    for (const [openapiPath, methods] of Object.entries(doc.paths)) {
+        if (!openapiPath.startsWith("/v1/") || openapiPath === "/v1/status")
+            continue; // /v1/status is a resource instead
+        if (openapiPath.includes("webhook"))
+            continue; // called by a third party, never by an agent
+        for (const [method, op] of Object.entries(methods)) {
+            const pathParamNames = [];
+            const queryParamNames = [];
+            const bodyPropNames = [];
+            const shape = {};
+            for (const p of op.parameters ?? []) {
+                if (p.in === "path") {
+                    pathParamNames.push(p.name);
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: true, description: p.description });
+                }
+                else if (p.in === "query") {
+                    queryParamNames.push(p.name);
+                    shape[p.name] = zodFor({ type: p.schema?.type, required: p.required, description: p.description });
+                }
             }
-            const headers = {};
-            if (API_KEY)
-                headers["x-api-key"] = API_KEY;
-            const r = await doFetch(url.toString(), { headers });
-            const text = await r.text();
-            let body;
-            try {
-                body = JSON.parse(text);
+            const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+            if (bodySchema) {
+                const required = new Set(bodySchema.required ?? []);
+                for (const [name, prop] of Object.entries(bodySchema.properties ?? {})) {
+                    bodyPropNames.push(name);
+                    shape[name] = zodFor({ type: prop.type, required: required.has(name), description: prop.description });
+                }
             }
-            catch {
-                body = text;
-            }
-            return {
-                isError: !r.ok,
-                content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
-            };
+            const name = toolNameFor(service, method, openapiPath);
+            server.registerTool(name, {
+                description: `[${service.name}] ${[op.summary, op.description].filter(Boolean).join(" — ")}`.slice(0, 1000),
+                inputSchema: shape,
+            }, async (args) => {
+                let urlPath = openapiPath;
+                for (const p of pathParamNames)
+                    urlPath = urlPath.replace(`{${p}}`, encodeURIComponent(String(args[p])));
+                const url = new URL(service.baseUrl + urlPath);
+                for (const p of queryParamNames) {
+                    const v = args[p];
+                    if (v !== undefined && v !== null)
+                        url.searchParams.set(p, String(v));
+                }
+                const headers = {};
+                if (API_KEY)
+                    headers["x-api-key"] = API_KEY;
+                const init = { method: method.toUpperCase(), headers };
+                if (bodyPropNames.length) {
+                    const bodyObj = {};
+                    for (const p of bodyPropNames)
+                        if (args[p] !== undefined)
+                            bodyObj[p] = args[p];
+                    headers["content-type"] = "application/json";
+                    init.body = JSON.stringify(bodyObj);
+                }
+                const r = await doFetch(url.toString(), init);
+                const text = await r.text();
+                let body;
+                try {
+                    body = JSON.parse(text);
+                }
+                catch {
+                    body = text;
+                }
+                return {
+                    isError: !r.ok,
+                    content: [{ type: "text", text: JSON.stringify(body, null, 2) }],
+                };
+            });
+            registered++;
+        }
+    }
+    return registered;
+}
+// --- Resources -----------------------------------------------------------
+// Reference material an agent can read without invoking a tool: the
+// platform-wide directory/llms.txt, and each service's live endpoint
+// catalog (the /v1/status we deliberately excluded from becoming a tool).
+function registerResources(server) {
+    server.registerResource("platform-services", "wickedapi://platform/services", {
+        title: "WickedAPI service directory",
+        description: "Every live WickedAPI service — URL, category, one-line description, auth modes, and links to each one's own OpenAPI spec/docs/llms.txt.",
+        mimeType: "application/json",
+    }, async (uri) => {
+        const r = await fetch(`${SHOWCASE_URL}/services.json`);
+        if (!r.ok)
+            throw new Error(`Failed to load service directory: HTTP ${r.status}`);
+        return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
+    });
+    server.registerResource("platform-llms-txt", "wickedapi://platform/llms", {
+        title: "WickedAPI llms.txt",
+        description: "Terse, platform-wide summary for agents deciding what to call — auth modes, free vs. paid endpoints.",
+        mimeType: "text/plain",
+    }, async (uri) => {
+        const r = await fetch(`${SHOWCASE_URL}/llms.txt`);
+        if (!r.ok)
+            throw new Error(`Failed to load llms.txt: HTTP ${r.status}`);
+        return { contents: [{ uri: uri.toString(), mimeType: "text/plain", text: await r.text() }] };
+    });
+    for (const service of SERVICES) {
+        server.registerResource(`${service.id}-status`, `wickedapi://${service.id}/status`, {
+            title: `${service.name} — live catalog`,
+            description: `Live endpoint catalog for ${service.name} (${service.baseUrl}), fetched fresh on every read.`,
+            mimeType: "application/json",
+        }, async (uri) => {
+            const r = await fetch(`${service.baseUrl}/v1/status`);
+            if (!r.ok)
+                throw new Error(`Failed to load ${service.name} status: HTTP ${r.status}`);
+            return { contents: [{ uri: uri.toString(), mimeType: "application/json", text: await r.text() }] };
         });
-        registered++;
     }
+}
+// --- Prompts ---------------------------------------------------------------
+// The "compound recipes" from the WickedAPI cookbook, turned into one-click
+// prompts: each just tells the assistant which real tools to call and how
+// to read the results — no fabricated synthesis, every number cited comes
+// from an actual tool call made during the conversation.
+function registerPrompts(server) {
+    server.registerPrompt("rug_check", {
+        title: "Rug-check before buying",
+        description: "Real on-chain risk signals for a token contract, plus market sentiment (and momentum, if it's a covered asset) before you decide whether to buy.",
+        argsSchema: {
+            address: z.string().describe("The token contract address (EVM) or mint address (Solana)."),
+            chain: z.string().describe("ethereum, bsc, base, polygon, arbitrum, optimism, avalanche, fantom, zksync, linea, scroll, or solana."),
+            symbol: z.string().optional().describe("If this token maps to a covered momentum-score asset (BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA), pass it to also pull a real momentum verdict."),
+        },
+    }, ({ address, chain, symbol }) => ({
+        description: "Rug-check workflow",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Before I consider buying this token, run a real risk check — don't guess or assume anything:\n\n` +
+                        `1. Call the \`token_risk\` tool with address="${address}" and chain="${chain}". Report the exact ` +
+                        `risk_score, risk_tier, and every real flag it returns (honeypot, mint/ownership authority, holder ` +
+                        `and LP concentration, buy/sell tax, trust-list status) — cite the actual values, don't summarize ` +
+                        `away the specifics or invent ones that weren't returned.\n` +
+                        `2. Call the \`sentiment\` tool for the current overall crypto market mood.\n` +
+                        (symbol
+                            ? `3. Call the \`momentum_score\` tool with symbol="${symbol}" and timeframe="1h" for a real technical read.\n`
+                            : "") +
+                        `\nThen give a plain verdict: the real risk signals found (listed, not paraphrased), current market ` +
+                        `mood, and — only if applicable — the momentum read. State clearly this is aggregated real signals, ` +
+                        `never a safety guarantee.`,
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("vet_dependency", {
+        title: "Vet a DeFi dependency",
+        description: "Protocol activity/treasury health plus an optional contract-level risk check, before you build on a DeFi protocol.",
+        argsSchema: {
+            slug: z.string().describe('The protocol\'s DefiLlama slug, e.g. "lido".'),
+            token_address: z.string().optional().describe("The protocol's token contract address, if you also want a contract-level risk check."),
+            chain: z.string().optional().describe("Chain for token_address (default ethereum)."),
+        },
+    }, ({ slug, token_address, chain }) => ({
+        description: "Dependency-vetting workflow",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Before I integrate this protocol as a dependency, check its real health — don't guess:\n\n` +
+                        `1. Call the \`protocol_health_score\` tool with slug="${slug}". Report the components (GitHub ` +
+                        `activity, TVL trend, treasury) exactly as returned, including any that came back null (never ` +
+                        `filled in).\n` +
+                        (token_address
+                            ? `2. Call the \`token_risk\` tool with address="${token_address}" and chain="${chain || "ethereum"}" ` +
+                                `for a contract-level check on its token.\n`
+                            : "") +
+                        `\nSummarize: is this protocol actively maintained, is its TVL trend healthy, and (if checked) does ` +
+                        `its token carry any real contract-level risk flags. Cite the real numbers.`,
+                },
+            },
+        ],
+    }));
+    server.registerPrompt("morning_briefing", {
+        title: "Morning briefing",
+        description: "One daily digest from macro calendar, earnings calendar, sentiment, and a momentum verdict — all free or a fraction of a cent.",
+        argsSchema: {
+            symbol: z.string().optional().describe("Asset for the momentum verdict (default BTC). One of BTC, ETH, SOL, SUI, NVDA, IBIT, COIN, QQQ, TQQQ, DIA."),
+        },
+    }, ({ symbol }) => {
+        const sym = symbol || "BTC";
+        return {
+            description: "Morning briefing workflow",
+            messages: [
+                {
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Compile my morning briefing from real, current data — call each tool, don't estimate:\n\n` +
+                            `1. \`macro_calendar\` with days=7 — upcoming FOMC/CPI/jobs events.\n` +
+                            `2. \`earnings_calendar\` with days=3 — upcoming earnings reports.\n` +
+                            `3. \`sentiment\` — current crypto Fear & Greed reading.\n` +
+                            `4. \`momentum_score\` with symbol="${sym}" and timeframe="1D" — today's technical verdict.\n\n` +
+                            `Then write one concise digest combining all four, citing the real values from each call.`,
+                    },
+                },
+            ],
+        };
+    });
+}
+async function main() {
+    const server = new McpServer({ name: "wickedapi", version: "0.3.0" });
+    const doFetch = await buildFetcher();
+    let totalTools = 0;
+    const loaded = [];
+    for (const service of SERVICES) {
+        const doc = await loadServiceSpec(service);
+        if (!doc)
+            continue;
+        totalTools += registerServiceTools(server, service, doc, doFetch);
+        loaded.push(service.name);
+    }
+    if (totalTools === 0) {
+        throw new Error("No service specs loaded — check network access and WICKEDAPI_*_URL overrides.");
+    }
+    // Reputation, Registry, Identity, Sanity, Memory and Paywall use hand-written
+    // tools (non-/v1 paths, wallet-signature auth) — registered unconditionally.
+    const suiteTools = registerSuiteTools(server);
+    totalTools += suiteTools;
+    loaded.push("Reputation, Registry, Identity, Sanity, Memory, Paywall");
+    registerResources(server);
+    registerPrompts(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`[wickedapi-mcp] ready — ${registered} tools loaded from ${BASE_URL}/openapi.json`);
+    console.error(`[wickedapi-mcp] ready — ${totalTools} tools across ${loaded.length} service(s) (${loaded.join(", ")}), ` +
+        `${2 + SERVICES.length} resources, 3 prompts.`);
 }
 main().catch((err) => {
     console.error("[wickedapi-mcp] fatal:", err);

package/dist/suite.js

@@ -0,0 +1,395 @@
+// Hand-written tools for the Wicked trust/memory/payments services whose HTTP
+// surface isn't the `/v1/*` OpenAPI shape the generic loader in index.ts
+// understands: Reputation, Registry, Identity, Sanity, Memory and the x402
+// Paywall. Behaviour mirrors the Python wicked-mcp server (tool names, args,
+// and the `http_status` / `payment_required` envelope) so agents see the same
+// surface whether they use the remote server or this npm package.
+//
+// Nothing here signs anything or holds a wallet key: Identity, Registry
+// registration and Memory take a signature the caller produced themselves.
+import { createHash, randomBytes } from "node:crypto";
+import { z } from "zod";
+function envUrl(name, fallback) {
+    return (process.env[name] || fallback).replace(/\/$/, "");
+}
+const REPUTATION_URL = envUrl("REPUTATION_BASE_URL", "https://stake.wickedapi.com");
+const REGISTRY_URL = envUrl("REGISTRY_BASE_URL", "https://registry.wickedapi.com");
+const IDENTITY_URL = envUrl("IDENTITY_BASE_URL", "https://verify.wickedapi.com");
+const SANITY_URL = envUrl("SANITY_BASE_URL", "https://sanity.wickedapi.com");
+const MEMORY_URL = envUrl("MEMORY_BASE_URL", "https://memory.wickedapi.com");
+const PAYWALL_URL = envUrl("PAYWALL_BASE_URL", "https://paywall.wickedapi.com");
+const REGISTRY_API_KEY = process.env.REGISTRY_API_KEY || "";
+const IDENTITY_API_KEY = process.env.IDENTITY_API_KEY || "";
+const SANITY_API_KEY = process.env.SANITY_API_KEY || "";
+const MEMORY_API_KEY = process.env.MEMORY_API_KEY || "";
+const PAYWALL_API_KEY = process.env.PAYWALL_API_KEY || "";
+const DEFAULT_TIMEOUT_MS = 20_000;
+const SANITY_TIMEOUT_MS = 90_000; // open mode runs a live web search per claim
+// x402 v2 services put the payment instructions in a base64 PAYMENT-REQUIRED
+// header instead of the JSON body; decode it so a 402 is useful either way.
+function extractPaymentRequired(res) {
+    const header = res.headers.get("payment-required");
+    if (!header)
+        return undefined;
+    try {
+        return JSON.parse(Buffer.from(header, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function finalize(res) {
+    const text = await res.text();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = { raw_body: text };
+    }
+    const body = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { data: parsed };
+    body.http_status = res.status;
+    const pr = extractPaymentRequired(res);
+    if (pr !== undefined)
+        body.payment_required = pr;
+    const retryAfter = res.headers.get("retry-after");
+    if (res.status === 429 && retryAfter)
+        body.retry_after = retryAfter;
+    return body;
+}
+function asResult(body) {
+    const status = Number(body.http_status ?? 200);
+    // 4xx/5xx are returned (not thrown) because 402/404/429 bodies are data the
+    // calling agent needs; flag them as errors without hiding the payload.
+    return { isError: status >= 500, content: [{ type: "text", text: JSON.stringify(body, null, 2) }] };
+}
+function clean(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined && v !== null));
+}
+async function call(method, base, path, opts = {}) {
+    const url = new URL(base + path);
+    for (const [k, v] of Object.entries(clean(opts.query ?? {})))
+        url.searchParams.set(k, String(v));
+    const headers = { ...(opts.headers ?? {}) };
+    const init = { method, headers, signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) };
+    if (opts.json) {
+        headers["content-type"] = "application/json";
+        init.body = JSON.stringify(clean(opts.json));
+    }
+    try {
+        return await finalize(await fetch(url.toString(), init));
+    }
+    catch (err) {
+        return { error: err.message, source: "mcp", http_status: 502 };
+    }
+}
+const keyHeader = (key) => (key ? { "x-api-key": key } : {});
+const bearer = (key) => (key ? { authorization: `Bearer ${key}` } : {});
+const addr = (wallet) => encodeURIComponent(wallet.toLowerCase());
+// --- Wicked Memory request signing --------------------------------------
+// Every /memories* call carries an EIP-191 signature over a message binding
+// the wallet to the exact method, path, body, timestamp and nonce. The path
+// and body bytes built here are identical for memory_prepare and the call
+// itself, so pass the same arguments to both.
+const MEMORY_OPS = ["store", "search", "get", "update", "history", "delete", "deletions"];
+const EMPTY_SHA256 = createHash("sha256").update("").digest("hex");
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function memoryId(p) {
+    const id = String(p.memory_id ?? "");
+    if (!UUID_RE.test(id))
+        throw new Error("memory_id must be a UUID");
+    return id.toLowerCase();
+}
+// Matches Python's urlencode(quote_via=quote): the signed path must be
+// byte-identical to the one the Python server signs, and encodeURIComponent
+// differs on ! ' ( ) *.
+function pyQuote(s) {
+    return encodeURIComponent(s).replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+}
+function queryString(q) {
+    return Object.entries(q)
+        .map(([k, v]) => `${pyQuote(k)}=${pyQuote(v)}`)
+        .join("&");
+}
+function memoryBuild(operation, params) {
+    const p = clean(params ?? {});
+    if (!MEMORY_OPS.includes(operation)) {
+        throw new Error(`unknown operation '${operation}'; expected one of ${[...MEMORY_OPS].sort().join(", ")}`);
+    }
+    const body = (keys) => JSON.stringify(Object.fromEntries(keys.filter((k) => k in p).map((k) => [k, p[k]])));
+    switch (operation) {
+        case "store":
+            if (!("content" in p))
+                throw new Error("store requires content");
+            return { method: "POST", path: "/memories", body: body(["content", "tags", "metadata", "source"]) };
+        case "search": {
+            if (!("q" in p))
+                throw new Error("search requires q");
+            const q = { q: String(p.q) };
+            for (const k of ["limit", "created_after", "created_before", "as_of"])
+                if (k in p)
+                    q[k] = String(p[k]);
+            if ("tags" in p)
+                q.tags = Array.isArray(p.tags) ? p.tags.join(",") : String(p.tags);
+            if ("include_superseded" in p)
+                q.include_superseded = p.include_superseded ? "true" : "false";
+            return { method: "GET", path: `/memories/search?${queryString(q)}` };
+        }
+        case "get":
+            return { method: "GET", path: `/memories/${memoryId(p)}` };
+        case "update":
+            return { method: "PATCH", path: `/memories/${memoryId(p)}`, body: body(["content", "tags", "metadata", "source"]) };
+        case "history":
+            return { method: "GET", path: `/memories/${memoryId(p)}/history` };
+        case "delete": {
+            // scope is always explicit so prepare (may omit it) and delete (default "chain") sign the same path.
+            const q = { scope: String(p.scope ?? "chain") };
+            if ("reason" in p)
+                q.reason = String(p.reason);
+            return { method: "DELETE", path: `/memories/${memoryId(p)}?${queryString(q)}` };
+        }
+        case "deletions":
+            return { method: "GET", path: "/memory-deletions" };
+    }
+}
+function memoryMessage(wallet, method, path, timestamp, nonce, body) {
+    const sha = body ? createHash("sha256").update(body, "utf8").digest("hex") : EMPTY_SHA256;
+    return [
+        "Wicked Memory auth",
+        `wallet: ${wallet.toLowerCase()}`,
+        `method: ${method.toUpperCase()}`,
+        `path: ${path}`,
+        `timestamp: ${timestamp}`,
+        `nonce: ${nonce}`,
+        `body-sha256: ${sha}`,
+    ].join("\n");
+}
+async function memoryCall(operation, wallet, params, sig, paymentSignature) {
+    let built;
+    try {
+        built = memoryBuild(operation, params);
+    }
+    catch (err) {
+        return { error: err.message, source: "mcp", http_status: 400 };
+    }
+    const headers = {
+        "x-wallet-address": wallet,
+        "x-wallet-timestamp": sig.timestamp,
+        "x-wallet-nonce": sig.nonce,
+        "x-wallet-signature": sig.signature,
+    };
+    if (built.body !== undefined)
+        headers["content-type"] = "application/json";
+    if (operation === "search") {
+        if (MEMORY_API_KEY)
+            headers["x-api-key"] = MEMORY_API_KEY;
+        if (paymentSignature)
+            headers["PAYMENT-SIGNATURE"] = paymentSignature;
+    }
+    try {
+        const res = await fetch(MEMORY_URL + built.path, {
+            method: built.method,
+            headers,
+            body: built.body,
+            signal: AbortSignal.timeout(30_000),
+        });
+        return await finalize(res);
+    }
+    catch (err) {
+        return { error: err.message, source: "mcp", http_status: 502 };
+    }
+}
+// --- Registration ---------------------------------------------------------
+const sigShape = {
+    timestamp: z.string().describe("From memory_prepare."),
+    nonce: z.string().describe("From memory_prepare (single use)."),
+    signature: z.string().describe("Your wallet's signature over memory_prepare's message_to_sign."),
+};
+export function registerSuiteTools(server) {
+    let n = 0;
+    const tool = (name, description, shape, run) => {
+        server.registerTool(name, { description, inputSchema: shape }, async (args) => asResult(await run(args)));
+        n++;
+    };
+    const wallet = z.string().describe("The 0x wallet address.");
+    // ---- Wicked Reputation (all public, free) ----
+    tool("reputation_status", "[Wicked Reputation] An agent's current reputation: tier, active/unbonding stake, score, slash count, founding-member badge. http_status 404 means the wallet never registered — treat as tier 'unranked'.", { wallet }, ({ wallet }) => call("GET", REPUTATION_URL, `/agents/${addr(wallet)}/status`));
+    tool("reputation_statement", "[Wicked Reputation] An agent's full position plus real event ledger (stakes, unstakes, withdrawals, slashes). Does not include WickedAPI call volume or fees — see the `note` field.", { wallet }, ({ wallet }) => call("GET", REPUTATION_URL, `/agents/${addr(wallet)}/statement`));
+    tool("reputation_query", "[Wicked Reputation] Search/rank registered agents by tier, stake, reputation or slash history. Every filter is a typed query param.", {
+        tier: z.string().optional().describe('Exact tier name, e.g. "gold".'),
+        min_stake: z.coerce.number().optional().describe("Minimum active stake (USDC)."),
+        max_stake: z.coerce.number().optional().describe("Maximum active stake (USDC)."),
+        min_reputation: z.coerce.number().optional().describe("Minimum reputation score."),
+        founding_member: z.coerce.boolean().optional().describe("True to only show founding members."),
+        min_slash_count: z.coerce.number().optional().describe("Minimum slash events (1 finds agents ever slashed)."),
+        sort: z.string().optional().describe('stake_amount | reputation_score | slash_count | registered_at, prefixed "-" (desc, default) or "+" (asc).'),
+        limit: z.coerce.number().optional().describe("1-200, default 20."),
+    }, (a) => call("GET", REPUTATION_URL, "/agents/query", { query: { sort: "-stake_amount", limit: 20, ...clean(a) } }));
+    tool("reputation_tiers", "[Wicked Reputation] Live tier thresholds and benefits (min stake, rate-limit multiplier, fee discount). Read at call time — thresholds are admin-configurable.", {}, () => call("GET", REPUTATION_URL, "/tiers"));
+    tool("reputation_transparency", "[Wicked Reputation] Live transparency numbers: treasury address, custody model, unbonding cooldown, total stake, agents, slash events, founding-slot counts.", {}, () => call("GET", REPUTATION_URL, "/transparency"));
+    // ---- Wicked Registry ----
+    tool("registry_search_tools", "[Wicked Registry] Search x402/MCP tools by real reliability data (uptime, latency, schema conformance). Works via x402 (402 carries payment instructions) or a free-tier REGISTRY_API_KEY.", {
+        category: z.string().optional().describe('e.g. "data", "crypto".'),
+        protocol: z.string().optional().describe('"x402", "mcp" or "rest".'),
+        min_score: z.coerce.number().optional().describe("Minimum composite score 0-100; unchecked tools are excluded once set."),
+        sort: z.string().optional().describe('"score" (default), "latency" or "recency".'),
+        limit: z.coerce.number().optional().describe("1-200, default 50."),
+    }, (a) => call("GET", REGISTRY_URL, "/tools", { headers: keyHeader(REGISTRY_API_KEY), query: { sort: "score", limit: 50, ...clean(a) } }));
+    tool("registry_tool_detail", "[Wicked Registry] One tool's full score breakdown, component history and recent real health checks. x402 or REGISTRY_API_KEY.", { tool_id: z.string().describe("Registry id from registry_search_tools / registry_featured_tools.") }, ({ tool_id }) => call("GET", REGISTRY_URL, `/tools/${encodeURIComponent(tool_id)}`, { headers: keyHeader(REGISTRY_API_KEY) }));
+    tool("registry_featured_tools", "[Wicked Registry] Top scored active tools. Public and free.", {}, () => call("GET", REGISTRY_URL, "/featured-tools"));
+    tool("registry_tool_badge", "[Wicked Registry] A tool's current composite reliability score. Public and free.", { tool_id: z.string().describe("The tool's Wicked Registry id.") }, ({ tool_id }) => call("GET", REGISTRY_URL, `/tools/${encodeURIComponent(tool_id)}/badge`));
+    tool("registry_report_tool", "[Wicked Registry] File a complaint about a tool's reliability or behaviour. Public, rate-limited; reviewed manually, never auto-suspends.", {
+        tool_id: z.string().describe("The tool's Wicked Registry id."),
+        reporter: z.string().describe("Your wallet address or another best-effort identifier."),
+        reason: z.string().describe('"downtime", "incorrect_response", "scam_or_abuse", "schema_violation" or "other".'),
+        evidence: z.string().optional().describe("Optional note or URL."),
+    }, ({ tool_id, reporter, reason, evidence }) => call("POST", REGISTRY_URL, `/tools/${encodeURIComponent(tool_id)}/report`, { json: { reporter, reason, evidence } }));
+    tool("registry_register_tool", '[Wicked Registry] Register a tool you own so it gets real synthetic checks and a live score. Needs YOUR signature over "Wicked Registry — Tool Registration\\nname: {name}\\nendpoint: {endpoint_url}\\ntimestamp: {timestamp}" from owner_wallet; this tool never signs.', {
+        name: z.string(),
+        endpoint_url: z.string().describe("Live, publicly reachable endpoint."),
+        protocol: z.string().describe('"x402", "mcp" or "rest".'),
+        category: z.string(),
+        description: z.string(),
+        owner_wallet: z.string().describe("0x wallet that signed the registration message."),
+        signature: z.string().describe("0x-prefixed ECDSA signature over the registration message."),
+        timestamp: z.string().describe("ISO 8601 timestamp used in the signed message (within 10 minutes of the call)."),
+        schema_url: z.string().optional().describe("Optional JSON Schema URL enabling the schema-conformance score."),
+    }, (a) => call("POST", REGISTRY_URL, "/tools/register", {
+        json: {
+            name: a.name,
+            endpointUrl: a.endpoint_url,
+            protocol: a.protocol,
+            category: a.category,
+            description: a.description,
+            ownerWallet: a.owner_wallet,
+            signature: a.signature,
+            timestamp: a.timestamp,
+            schemaUrl: a.schema_url,
+        },
+    }));
+    // ---- Wicked Identity (reverse-CAPTCHA / Know-Your-Agent) ----
+    const idSig = {
+        wallet: z.string().describe("Your agent's 0x wallet address on Base."),
+        nonce: z.string().describe("Nonce from a FRESH identity_get_nonce call."),
+        signature: z.string().describe("0x-prefixed ECDSA signature over that nonce's message."),
+    };
+    tool("identity_get_nonce", "[Wicked Identity] Step 1: a one-time nonce + message to sign. Every signed identity call needs a fresh nonce (single-use, short TTL).", { wallet: idSig.wallet }, ({ wallet }) => call("GET", IDENTITY_URL, `/agents/${addr(wallet)}/nonce`));
+    tool("identity_register", "[Wicked Identity] Register your wallet (no stake required). Needs your signature over identity_get_nonce's message; this tool never signs.", idSig, ({ wallet, nonce, signature }) => call("POST", IDENTITY_URL, "/agents/register", { json: { wallet_address: wallet, nonce, signature } }));
+    tool("identity_get_challenge", "[Wicked Identity] Request a real time-boxed liveness challenge for a registered wallet (constrained-generation task, ~12s). Answer via identity_submit_response before `expires_at`. Needs a fresh signed nonce.", idSig, ({ wallet, nonce, signature }) => call("POST", IDENTITY_URL, "/verify/challenge", { json: { wallet_address: wallet, nonce, signature } }));
+    tool("identity_submit_response", "[Wicked Identity] Submit your answer to a challenge; scored pass / fail / inconclusive. A pass returns a short-lived signed assertion_token (JWT) verifiable via identity_jwks. Needs a DIFFERENT fresh nonce than identity_get_challenge used.", {
+        ...idSig,
+        challenge_id: z.string().describe("The challenge_id from identity_get_challenge."),
+        response_text: z.string().describe("Your answer exactly as the instructions specify."),
+    }, ({ wallet, nonce, signature, challenge_id, response_text }) => call("POST", IDENTITY_URL, "/verify/response", { json: { wallet_address: wallet, nonce, signature, challenge_id, response_text } }));
+    tool("identity_status", "[Wicked Identity] Does a wallet currently hold a valid, unexpired assertion? No signature needed. x402 or IDENTITY_API_KEY.", { wallet }, ({ wallet }) => call("GET", IDENTITY_URL, `/verify/status/${addr(wallet)}`, { headers: keyHeader(IDENTITY_API_KEY) }));
+    tool("identity_jwks", "[Wicked Identity] Public RS256 keys to verify an assertion_token locally. Free.", {}, () => call("GET", IDENTITY_URL, "/.well-known/jwks.json"));
+    // ---- Wicked Sanity (hallucination / eval check) ----
+    const contextShape = z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe('Source text the claim(s) must be faithful to. Required for mode "grounded".');
+    const modeShape = z.string().optional().describe('"grounded" (default; check against context) or "open" (check against live web evidence — consistency with the web, not objective truth).');
+    tool("sanity_check", '[Wicked Sanity] Verify one claim before acting on it. Verdicts: supported | contradicted | unsupported | insufficient_evidence (see `data`). confidence_score is raw consistency (a "contradicted" verdict scores near 0). Policy: act on supported; treat unsupported/insufficient_evidence as unverified; reject contradicted. x402 or SANITY_API_KEY; 429 means a rate limit — see retry_after.', { claim: z.string().describe("The single statement to verify (max 5,000 chars)."), context: contextShape, mode: modeShape }, ({ claim, context, mode }) => call("POST", SANITY_URL, "/check", { headers: keyHeader(SANITY_API_KEY), json: { claim, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS }));
+    tool("sanity_check_batch", "[Wicked Sanity] Verify up to 50 claims against one shared context in a single call — prefer this over one sanity_check per sentence. `data` is a list in the same order as `claims`.", { claims: z.array(z.string()).min(1).max(50).describe("1-50 statements, each up to 5,000 chars."), context: contextShape, mode: modeShape }, ({ claims, context, mode }) => call("POST", SANITY_URL, "/check/batch", { headers: keyHeader(SANITY_API_KEY), json: { claims, context, mode: mode ?? "grounded" }, timeoutMs: SANITY_TIMEOUT_MS }));
+    // ---- Wicked Memory (wallet-scoped, signature per call) ----
+    tool("memory_prepare", 'Wicked Memory step 1 of every call: returns the exact `message_to_sign`. Sign it with your own wallet (EIP-191 personal_sign), then call the matching memory_* tool with the SAME arguments plus the returned timestamp, nonce and your signature. Timestamp must be within 5 minutes; nonce is single-use, so prepare again for every call.', {
+        operation: z.string().describe('"store", "search", "get", "update", "history", "delete" or "deletions".'),
+        wallet: z.string().describe("Your agent's 0x wallet address (memories are scoped to it)."),
+        params: z.record(z.string(), z.unknown()).optional().describe('The arguments you will pass to the tool, by name, e.g. {"content":"...","tags":["a"]} or {"memory_id":"<uuid>"}.'),
+    }, async ({ operation, wallet, params }) => {
+        let built;
+        try {
+            built = memoryBuild(operation, params);
+        }
+        catch (err) {
+            return { error: err.message, source: "mcp", http_status: 400 };
+        }
+        const timestamp = String(Math.floor(Date.now() / 1000));
+        const nonce = randomBytes(16).toString("hex");
+        return {
+            message_to_sign: memoryMessage(wallet, built.method, built.path, timestamp, nonce, built.body),
+            timestamp,
+            nonce,
+            operation,
+            wallet,
+            request: { method: built.method, path: built.path },
+            next: `Sign message_to_sign with the wallet's key (EIP-191 personal_sign), then call memory_${operation} with the same arguments plus timestamp, nonce and signature.`,
+        };
+    });
+    const memWallet = z.string().describe("Your agent's 0x wallet address.");
+    const memId = z.string().describe("The memory's UUID.");
+    tool("memory_store", "[Wicked Memory] Store a memory (free, fair-use rate limited). A real embedding is computed at write time. Run memory_prepare with operation 'store' and these same arguments first.", {
+        wallet: memWallet,
+        content: z.string().describe("Text to remember (max 16 KB)."),
+        ...sigShape,
+        tags: z.array(z.string()).optional().describe("Up to 20 short tags."),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Free-form JSON object (max 8 KB)."),
+        source: z.string().optional().describe("Which agent/session wrote this."),
+    }, (a) => memoryCall("store", a.wallet, { content: a.content, tags: a.tags, metadata: a.metadata, source: a.source }, a));
+    tool("memory_search", "[Wicked Memory] Semantic search over YOUR memories only, ranked by real cosine similarity. The one metered call: free with MEMORY_API_KEY, otherwise http_status 402 with x402 v2 instructions under `payment_required` (0.001 USDC on Base) — pay, then call again with the SAME arguments (a 402 does not consume the nonce) plus payment_signature.", {
+        wallet: memWallet,
+        q: z.string().describe("What to look for, in natural language."),
+        ...sigShape,
+        limit: z.coerce.number().optional().describe("1-50, default 10."),
+        tags: z.array(z.string()).optional().describe("Only memories having ALL of these tags."),
+        created_after: z.string().optional().describe("ISO-8601 lower bound."),
+        created_before: z.string().optional().describe("ISO-8601 upper bound."),
+        as_of: z.string().optional().describe("ISO-8601 instant; search memory as it stood then."),
+        include_superseded: z.coerce.boolean().optional().describe("Also search old, superseded versions."),
+        payment_signature: z.string().optional().describe("x402 payment payload (base64) for the keyless path."),
+    }, (a) => memoryCall("search", a.wallet, { q: a.q, limit: a.limit, tags: a.tags, created_after: a.created_after, created_before: a.created_before, as_of: a.as_of, include_superseded: a.include_superseded }, a, a.payment_signature));
+    tool("memory_get", "[Wicked Memory] Fetch one of your memories by id (another wallet's or a deleted id returns the same 404).", { wallet: memWallet, memory_id: memId, ...sigShape }, (a) => memoryCall("get", a.wallet, { memory_id: a.memory_id }, a));
+    tool("memory_update", "[Wicked Memory] Update without overwriting: creates a new version and closes the old one (valid_until / superseded_by). Omitted fields carry over; only the current version can be updated (409 otherwise).", {
+        wallet: memWallet,
+        memory_id: z.string().describe("UUID of the CURRENT version to supersede."),
+        ...sigShape,
+        content: z.string().optional().describe("New text (re-embedded). Provide at least one of content/tags/metadata/source."),
+        tags: z.array(z.string()).optional().describe("Replacement tags."),
+        metadata: z.record(z.string(), z.unknown()).optional().describe("Replacement metadata object."),
+        source: z.string().optional().describe("New source label."),
+    }, (a) => memoryCall("update", a.wallet, { memory_id: a.memory_id, content: a.content, tags: a.tags, metadata: a.metadata, source: a.source }, a));
+    tool("memory_history", "[Wicked Memory] Full version chain for a memory, oldest first, with valid_from / valid_until / superseded_by. Works from any version's id.", { wallet: memWallet, memory_id: z.string().describe("UUID of any version in the chain."), ...sigShape }, (a) => memoryCall("history", a.wallet, { memory_id: a.memory_id }, a));
+    tool("memory_delete", '[Wicked Memory] PERMANENTLY hard-delete a memory (right-to-be-forgotten). Default scope "chain" removes every version; "version" only this one. Only an audit row (no content) is kept.', {
+        wallet: memWallet,
+        memory_id: z.string().describe("UUID of any version in the chain."),
+        ...sigShape,
+        scope: z.string().optional().describe('"chain" (all versions, default) or "version".'),
+        reason: z.string().optional().describe("Optional audit-log note (max 200 chars)."),
+    }, (a) => memoryCall("delete", a.wallet, { memory_id: a.memory_id, scope: a.scope ?? "chain", reason: a.reason }, a));
+    tool("memory_deletions", "[Wicked Memory] Your deletion audit log (ids, times, reasons; never content).", { wallet: memWallet, ...sigShape }, (a) => memoryCall("deletions", a.wallet, {}, a));
+    // ---- x402 Paywall (tenant API; needs PAYWALL_API_KEY except signup) ----
+    const routeShape = {
+        price: z.string().describe('Decimal USD amount, e.g. "0.01" or "$0.01".'),
+        network: z.string().describe("CAIP-2 id: Base mainnet eip155:8453, Base Sepolia eip155:84532."),
+        payTo: z.string().describe("Your payout wallet (0x…). Settlement pays here directly; nothing is custodied."),
+        method: z.enum(["GET", "POST"]).optional().describe("Default GET."),
+        path: z.string().optional().describe('Route path, e.g. "/weather".'),
+        asset: z.string().optional().describe("Payment token contract; defaults to USDC on the network."),
+        description: z.string().optional().describe("Up to 200 chars: letters, digits, space . _ -"),
+        upstreamUrl: z.string().optional().describe("Your https backend. Omit for the demo confirmation payload."),
+    };
+    tool("paywall_signup", "[x402 Paywall] Create a tenant account. Returns a Bearer apiKey ONCE — store it and set PAYWALL_API_KEY. Rate-limited to 5/hour per IP.", {
+        name: z.string().describe("Letters, digits, space . _ - (max 100)."),
+        slug: z.string().describe("Lowercase a-z0-9 and hyphens, 2-40 chars; becomes your mount path prefix /{slug}."),
+    }, ({ name, slug }) => call("POST", PAYWALL_URL, "/signup", { json: { name, slug } }));
+    tool("paywall_get_tenant", "[x402 Paywall] Your tenant record (needs PAYWALL_API_KEY).", {}, () => call("GET", PAYWALL_URL, "/tenants/me", { headers: bearer(PAYWALL_API_KEY) }));
+    tool("paywall_list_routes", "[x402 Paywall] List your paywalled routes (needs PAYWALL_API_KEY).", {}, () => call("GET", PAYWALL_URL, "/tenants/me/routes", { headers: bearer(PAYWALL_API_KEY) }));
+    tool("paywall_create_route", "[x402 Paywall] Paywall a new endpoint with x402 pay-per-call, settled in USDC straight to payTo. With upstreamUrl, paid requests are proxied to your backend. Applies live within ~20s (needs PAYWALL_API_KEY).", routeShape, (a) => call("POST", PAYWALL_URL, "/tenants/me/routes", { headers: bearer(PAYWALL_API_KEY), json: a }));
+    tool("paywall_import_routes", "[x402 Paywall] Bulk upsert routes keyed on (method, path) — paywall a whole API in one call (needs PAYWALL_API_KEY).", { routes: z.array(z.object(routeShape)).min(1).describe("Route objects, same fields as paywall_create_route.") }, ({ routes }) => call("POST", PAYWALL_URL, "/tenants/me/routes/import", { headers: bearer(PAYWALL_API_KEY), json: { routes } }));
+    tool("paywall_update_route", "[x402 Paywall] Partial update of a route (e.g. change price or payout wallet); applies live within ~20s (needs PAYWALL_API_KEY).", {
+        id: z.string().describe("Route id from paywall_list_routes."),
+        price: routeShape.price.optional(),
+        network: routeShape.network.optional(),
+        payTo: routeShape.payTo.optional(),
+        method: routeShape.method,
+        path: routeShape.path,
+        asset: routeShape.asset,
+        description: routeShape.description,
+        upstreamUrl: routeShape.upstreamUrl,
+    }, ({ id, ...patch }) => call("PATCH", PAYWALL_URL, `/tenants/me/routes/${encodeURIComponent(id)}`, { headers: bearer(PAYWALL_API_KEY), json: patch }));
+    tool("paywall_delete_route", "[x402 Paywall] Remove a paywalled route; applies within ~20s (needs PAYWALL_API_KEY).", { id: z.string().describe("Route id from paywall_list_routes.") }, ({ id }) => call("DELETE", PAYWALL_URL, `/tenants/me/routes/${encodeURIComponent(id)}`, { headers: bearer(PAYWALL_API_KEY) }));
+    tool("paywall_list_settlements", "[x402 Paywall] Your real on-chain USDC settlements (earnings) (needs PAYWALL_API_KEY).", { limit: z.coerce.number().optional().describe("Default 50, max 200.") }, ({ limit }) => call("GET", PAYWALL_URL, "/tenants/me/settlements", { headers: bearer(PAYWALL_API_KEY), query: { limit } }));
+    return n;
+}
+// Exposed for tests: deterministic builders used by memory_prepare.
+export const __test = { memoryBuild, memoryMessage };

package/package.json

@@ -1,47 +1,55 @@
-{
-  "name": "wickedapi-mcp",
-  "version": "0.1.0",
-  "description": "MCP server for WickedAPI — agent-ready trading & market-data API (crypto/stock prices, indicators, prediction markets, DeFi, macro, AI momentum score). No signup required: pay per call in USDC via x402, or use a partner API key.",
-  "type": "module",
-  "bin": {
-    "wickedapi-mcp": "dist/index.js"
-  },
-  "main": "dist/index.js",
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "license": "MIT",
-  "homepage": "https://api.wickedapi.com",
-  "bugs": {
-    "url": "https://api.wickedapi.com"
-  },
-  "author": "WickedAPI",
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "start": "node dist/index.js",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "trading",
-    "crypto",
-    "stocks",
-    "market-data",
-    "x402",
-    "agent"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "viem": "^2.55.2",
-    "x402-fetch": "^1.2.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^22.20.1",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "wickedapi-mcp",
+  "version": "0.3.0",
+  "description": "MCP server for the whole Wicked suite — trading data, DeFi protocol health, token safety, brokerage sync, agent identity, reputation, tool registry, hallucination checks, persistent memory, and x402 paywalls. 70 tools, 6 resources, 3 prompts. No signup required: pay per call in USDC via x402, or use a partner API key.",
+  "type": "module",
+  "bin": {
+    "wickedapi-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://api.wickedapi.com",
+  "bugs": {
+    "url": "https://api.wickedapi.com"
+  },
+  "author": "WickedAPI",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "trading",
+    "crypto",
+    "stocks",
+    "market-data",
+    "defi",
+    "brokerage",
+    "x402",
+    "agent",
+    "identity",
+    "reputation",
+    "registry",
+    "memory",
+    "sanity",
+    "paywall"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "viem": "^2.55.2",
+    "x402-fetch": "^1.2.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^5.9.3"
+  }
+}