# WickedAPI MCP Server

MCP server for the whole [WickedAPI](https://wickedapi.com) platform — trading data, DeFi protocol health, token safety, and brokerage sync, in one server.

**35 tools** across 4 live services, generated automatically from each service's own live `openapi.json` — the tool list always matches what's actually deployed:

| 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 |

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.

## 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`). |
| `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, auto-generated bridge from MCP tool calls to the live WickedAPI HTTP endpoints across all four services. All the actual market data, indicators, scoring, and risk signals live in the APIs themselves.