# hyperd-mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/hyperd-ai/hyperd-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 351  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hyperd-mcp

## Description
Pre-trade DeFi intelligence for AI agents. 20 paid x402 endpoints, USDC on Base.

## Tools
Capabilities this server exposes over MCP:

- **hyperd.catalog.list** — List all available hyperD x402 API endpoints with their prices, descriptions, and example responses. FREE — no wallet required. Use this to discover what tools are available before configuring a wallet.
- **hyperd.pricing.get** — Get the current price list for all hyperD paid endpoints (in USDC on Base). FREE — no wallet required.
- **hyperd.health.check** — Check the health of the hyperD API: which network it's on, whether the payment facilitator is configured, which optional backend keys are wired, and cache stats. FREE — no wallet required.
- **hyperd.balance.get** — Get the on-chain balance for an EVM wallet address. Multi-chain (Base, Ethereum, Polygon, Arbitrum). Supports ERC-20 by symbol or contract address. Pass chain='all' for parallel multi-chain lookup. Costs $0.01 in USDC on Base.
- **hyperd.yield.recommend** — Get an opinionated DeFi yield recommendation. Filters DefiLlama's pool universe by risk tier (low/medium/high), TVL, and IL exposure, then ranks by APY. Returns the top picks plus projected $ yield over your duration. Costs $0.05 in USDC.
- **hyperd.token.info** — Get aggregated token metadata: market cap, supply, contract addresses across chains, recent volume. One call replaces multiple CoinGecko / Etherscan / DefiLlama lookups. Costs $0.01 in USDC.
- **hyperd.token.security** — Get a token's security risk score (0-100). Ensemble of GoPlus signals: honeypot detection, owner permissions, holder concentration, buy/sell taxes, source verification. Returns score, band (safe/caution/warning/danger), and structured findings. Costs $0.05 in USDC.
- **hyperd.wallet.risk** — Check a wallet's risk profile. Combines Chainalysis Sanctions Oracle (OFAC SDN authoritative) with GoPlus address heuristics (mixers, phishing, scams). Returns sanctioned flag + 0-100 heuristic score. Costs $0.10 in USDC.
- **hyperd.protocol.tvl** — Get a DeFi protocol's TVL, audits, chain distribution from DefiLlama. Pass slug for detail (e.g., 'aave', 'morpho-blue') or list=true for top 50. Costs $0.01 in USDC.
- **hyperd.gas.estimate** — Get current gas price + base fee + tip percentiles for fast/standard/slow inclusion. Costs $0.005 in USDC.
- **hyperd.dex.quote** — Get the best DEX swap route across multiple aggregators (Paraswap + 0x). Returns the highest output amount and per-source quotes. Costs $0.02 in USDC.
- **hyperd.wallet.persona** — Classify a wallet's persona based on on-chain behavior. Returns one of: Trader, HODLer, MEV-bot, Whale, Smart-Money, Airdrop-Farmer, Compromised, Inactive — plus confidence and supporting signals. Costs $0.10 in USDC.
- **hyperd.contract.audit** — Pre-trade contract security audit. Composes GoPlus + Sourcify + DefiLlama protocol recognition + on-chain heuristics into a single 0-100 risk score with structured findings. Use BEFORE interacting with any unfamiliar contract. Costs $0.10 in USDC.
- **hyperd.governance.summarize** — Summarize a DAO governance proposal (Snapshot or Tally URL). Returns structured impact analysis: who benefits, who pays, recommended position. LLM-summarized. Costs $0.10 in USDC.
- **hyperd.sentiment.token** — Get a token's sentiment score (0-100) from recent Farcaster discussion. Returns score, band (very_negative to very_positive), volume, trend, sample casts. Costs $0.05 in USDC.
- **hyperd.liquidation.risk** — Cross-protocol liquidation risk for a wallet's lending positions. Health factor, USD-at-risk, and recommendations across Aave V3, Compound v3, Spark Lend, and Morpho Blue. Pass chain='all' for cross-chain aggregate. Costs $0.10 in USDC.
- **hyperd.wallet.anomaly** — Wallet behavioral anomaly detection. Compares recent activity against the wallet's own 180-day baseline — surfaces tx-volume spikes, dormant-wakeup patterns, new-protocol interactions, counterparty diversification. Catches compromised hot wallets, dormant whales, MEV-bot strategy shifts. Costs $0.10 in USDC.
- **hyperd.wallet.pnl** — Realized + unrealized P&L for a wallet over a time window. ERC-20 + native, single chain per call. Three cost-basis methods: FIFO (default, IRS standard), LIFO (last-in-first-out), HCFO (highest-cost-first-out, tax-loss-harvesting view). Per-token breakdown with weighted-avg cost + mark-to-market. Unpriced trades and untracked-proceeds gaps surfaced honestly under coverage.* fields. v1.0 defers per-tx gas-fee USD attribution. Costs $0.05 in USDC.
- **hyperd.budget.guardian** — Agent spend visibility: aggregates recent outbound USDC transfers from a wallet over a configurable window (1h/24h/7d/30d). Returns total spend, by-destination breakdown, projected-24h rate, and an optional under_cap flag if cap_usd is provided. Use this BEFORE initiating the next paid x402 call to enforce a self-imposed budget. Bridged USDC.e variants are NOT counted. Costs $0.01 in USDC.
- **hyperd.bundle** — Bundle multiple paid GET calls into one x402 settlement. Up to 10 sub-calls executed in parallel (concurrency cap 4), per-call results returned in a structured envelope. Fixed $0.20 USDC — typically cheaper than à la carte for any combination summing > $0.24 individually. Best-effort execution: failed sub-calls don't refund in v1.0 (credit ledger planned for v1.1). Use this when you need 3+ paid calls and want to save on facilitator round-trips.
- **hyperd.watch.create** — Subscribe to a continuous watch on a wallet/position. Returns watch_id and webhook_secret (shown ONCE — store it; we cannot recover it). HMAC-SHA256 signed alerts POSTed to your webhook_url when threshold conditions are met. v1.0 supports liquidation watches across Aave V3 / Compound v3 / Spark / Morpho. $3.00 USDC prepays for duration_days (default 30, max 90).
- **hyperd.watch.list** — List the active watches owned by your wallet. $0.001 USDC ops fee — covers the x402 auth path that proves wallet ownership (without it, the server can't tell which wallet is asking). webhook_secret is NEVER returned — store it from the create response.
- **hyperd.watch.cancel** — Cancel a watch you own. $0.001 USDC ops fee covers the x402 auth path. Returns 404 (not 403) if the watch_id doesn't exist OR if you're not the owner — no existence-leak side-channel.
- **hyperd.risk.full_audit** — Composed wallet risk verdict. Fans out to balance, wallet_risk, wallet_persona, contract_audit, and privacy_mixer_risk then returns a Haiku 4.5-authored summary + confidence + band (safe / moderate / elevated / critical). One verdict replaces a manual 5-call audit walk. Costs $0.35 in USDC.
- **hyperd.token.archetype** — Composed token classification. Fans out to token_info, token_security, and protocol_tvl then returns a single archetype (stablecoin / blue_chip / mid_cap / memecoin / wrapped / governance / unverified) plus a plain-language verdict. Costs $0.30 in USDC.
- **hyperd.wallet.thesis** — Composed wallet behavioral thesis. Fans out to balance, wallet_persona, wallet_pnl, and wallet_anomaly then returns a plain-language summary of the wallet's investing posture plus archetype (trader / hodler / yield_farmer / mev_bot / compromised / inactive). Costs $0.50 in USDC.
- **hyperd.wallet.threat_brief** — Composed wallet threat brief. Fans out to wallet_risk, wallet_anomaly, privacy_mixer_risk, budget_guardian, and wallet_persona then returns a 2-3 sentence security verdict + band (clean / watch / elevated / critical). Replaces a manual 5-call security audit walk. Costs $1.50 in USDC.
- **hyperd.gov.translate** — Composed DAO governance translator. Takes a Snapshot or Tally proposal URL, fetches structured data via /api/governance/summarize, then produces a 2-3 sentence plain-language translation + domain band (economic_param / treasury / code_upgrade / governance_meta / social_signal). 1-year cache — proposals are immutable. Costs $1.00 in USDC.
- **hyperd.yield.allocation** — Composed yield allocation recommender. Fans out 3 parallel /api/yield calls at low/medium/high risk tiers for the same amount + duration, then returns a recommended portfolio split + 2-sentence rationale. Bands: conservative / balanced / aggressive / bespoke. 6h cache bucketed by amount tier × duration × chain. Costs $1.00 in USDC.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "hyperd-mcp": {
    "command": "npx",
    "args": ["-y","hyperd-mcp"]
  }
}
```

## Documentation & README

# hyperD MCP Server

Exposes 24 paid hyperD x402 tools — 17 data/risk endpoints, **6 premium synthesis verdicts** ($0.30–$1.50), and a multi-call bundle — plus 3 free meta tools (and 3 watch tools when enabled) from `api.hyperd.ai`. Drop into Claude Desktop, Cursor, Cline, Zed, or any MCP-compatible client.

## What it does

Each tool call:
1. Sends a request to the corresponding `api.hyperd.ai` endpoint
2. Receives an HTTP 402 with payment requirements
3. Signs an EIP-3009 USDC transfer authorization with your wallet
4. Retries with the payment header
5. Returns the data to the AI assistant

You pay **$0.005–$1.50 in USDC on Base** per call — data/risk endpoints $0.005–$0.10, premium synthesis verdicts $0.30–$1.50. No subscription. No accounts.

## Try it free

First 5 calls per IP per 24h are free — no wallet, no signup, no API key. Just curl:

```bash
curl "https://api.hyperd.ai/api/balance?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
```

Lifetime cap: 10 calls per IP. After that (or when daily quota is exhausted), the endpoint returns HTTP 402 — sign a small EIP-3009 USDC payment on Base via the [Python SDK](https://pypi.org/project/hyperd-ai/) or [TypeScript MCP server](https://www.npmjs.com/package/hyperd-mcp). The premium synthesis tier ($0.30+) always requires payment — it is not free-tier eligible.

`/api/wallet/pnl` has a tighter free-tier cap of 1 call/IP/day (heavy upstream).

## What you need

- A wallet with **at least $0.30 USDC on Base** (the seed cost for trying every tool once is ~$0.62)
- The wallet's private key OR 12-word BIP-39 mnemonic
- Node 20+ installed

## Install + configure

### Step 1 — Generate or use an existing wallet

For testing, **use a fresh wallet, not your main one.** A simple way:

```bash
node -e "const {generatePrivateKey, privateKeyToAccount} = require('viem/accounts'); const pk = generatePrivateKey(); console.log('Address:', privateKeyToAccount(pk).address); console.log('Private key:', pk);"
```

Send ~$1 of USDC on Base to the printed address.

### Step 2 — Claude Desktop

Edit your Claude Desktop config (location: macOS `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows `%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "hyperd": {
      "command": "npx",
      "args": ["-y", "hyperd-mcp"],
      "env": {
        "HYPERD_WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
      }
    }
  }
}
```

Restart Claude Desktop. The hyperD tools appear in the conversation tool list.

### Step 3 — Try it

Ask Claude in any conversation:

> "What's the security score for USDC on Base? Use the hyperd.token.security tool."

Claude calls our endpoint, pays $0.05 from your wallet, returns the result. The whole flow takes ~2 seconds.

### Cursor / Cline / Zed

Each MCP-compatible client has a similar config file. Same pattern: name the server `hyperd`, command is `npx -y hyperd-mcp`, set `HYPERD_WALLET_PRIVATE_KEY` env var.

For the full MCP client list and per-client config docs see https://modelcontextprotocol.io/clients.

## Local-development install (without npm publish)

If you want to run from source instead of `npx`:

```bash
git clone https://github.com/hyperd-ai/hyperd-mcp.git
cd hyperd-mcp
npm install
npm run build
```

Then in your Claude Desktop config, point at the local build:

```json
{
  "mcpServers": {
    "hyperd": {
      "command": "node",
      "args": ["/full/path/to/hyperd-mcp/dist/server.js"],
      "env": {
        "HYPERD_WALLET_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HERE"
      }
    }
  }
}
```

## Available tools

| Tool | Price | What it does |
|---|---|---|
| `hyperd.balance.get` | $0.01 | Multi-chain ERC-20 + native balance lookup |
| `hyperd.yield.recommend` | $0.05 | Opinionated DeFi yield recommendation |
| `hyperd.token.info` | $0.01 | Aggregated token metadata (CoinGecko + DefiLlama) |
| `hyperd.token.security` | $0.05 | GoPlus-backed security risk score |
| `hyperd.wallet.risk` | $0.10 | Chainalysis sanctions + GoPlus heuristics |
| `hyperd.protocol.tvl` | $0.01 | DefiLlama protocol health |
| `hyperd.gas.estimate` | $0.005 | Gas oracle with tip percentiles |
| `hyperd.dex.quote` | $0.02 | Multi-aggregator best DEX route |
| `hyperd.wallet.persona` | $0.10 | Behavioral wallet classification |
| `hyperd.contract.audit` | $0.10 | Pre-trade contract security composite |
| `hyperd.governance.summarize` | $0.10 | LLM-summarized DAO proposals |
| `hyperd.sentiment.token` | $0.05 | Token sentiment from Farcaster |
| `hyperd.liquidation.risk` | $0.10 | Cross-protocol liquidation risk (Aave V3 / Compound v3 / Spark / Morpho) |
| `hyperd.wallet.anomaly` | $0.10 | Wallet anomaly detection vs 180-day baseline |
| `hyperd.wallet.pnl` | $0.05 | Realized + unrealized P&L (FIFO/LIFO/HCFO) |
| `hyperd.budget.guardian` | $0.01 | Agent USDC spend visibility + cap check |
| `hyperd.bundle` | $0.20 fixed | Multi-call: 1-10 paid GETs in one settlement |
| `hyperd.watch.create` | $3.00 prepay | Subscribe to a continuous liquidation watch (HMAC webhooks) |
| `hyperd.watch.list` | (free for owner) | List your active watches |
| `hyperd.watch.cancel` | (free for owner) | Cancel one of your watches |

### Synthesis tier — composed verdicts (Haiku 4.5, v1.1.0)

Each synthesis tool fans out multiple sub-calls internally and returns a single `verdict` + `inputs` + `methodology.version` + `coverage` envelope, authored by Claude Haiku 4.5.

| Tool | Price | What it does |
|---|---|---|
| `hyperd.risk.full_audit` | $0.35 | Composed wallet risk: balance + sanctions + persona + contract + mixer. Bands: safe / moderate / elevated / critical. |
| `hyperd.token.archetype` | $0.30 | Token classification: stablecoin / blue_chip / mid_cap / memecoin / wrapped / governance / unverified. |
| `hyperd.wallet.thesis` | $0.50 | Plain-language behavioral thesis: trader / hodler / yield_farmer / mev_bot / compromised / inactive. |
| `hyperd.wallet.threat_brief` | $1.50 | 2-3 sentence security verdict: clean / watch / elevated / critical. |
| `hyperd.gov.translate` | $1.00 | Snapshot/Tally proposal in plain language (1y cache). |
| `hyperd.yield.allocation` | $1.00 | Portfolio split across risk tiers for a given amount (6h cache). |

Full HTTP API docs: https://api.hyperd.ai/api/discover

## Security

- **Use a hot wallet**, not your primary. The MCP server has the private key in process memory while it runs.
- **Cap your spend** by transferring only what you want to use. There's no built-in spending limit; the wallet's balance IS the limit.
- **Don't commit your private key.** The Claude Desktop config file is local; don't share it.

## Configuration via mnemonic instead of private key

If you have a 12 or 24-word BIP-39 mnemonic instead of a raw key:

```json
"env": {
  "HYPERD_WALLET_MNEMONIC": "word1 word2 ... word12"
}
```

Derives at the standard Ethereum path `m/44'/60'/0'/0/0`.

## Optional env vars

- `HYPERD_API_BASE` — default `https://api.hyperd.ai`. Override for testnet or self-hosted.
- `HYPERD_BASE_RPC` — default public Base RPC. Override for higher rate limits.

## Remote MCP-over-HTTPS (no install)

If you don't want to run the stdio server locally, hyperD's full tool catalog is also available as a remote MCP server:

```
POST https://api.hyperd.ai/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/list"}
```

Same 24 paid tools, same free-tier quota (5 calls/IP/day, 10 lifetime), same `X-Payment` auth model for paid calls after quota. No `npm install`, no per-IDE config — just a URL.

Useful when:
- You're deploying an agent to a serverless platform (Vercel, Lambda) and don't want to bundle the stdio process
- You're using an MCP-aware service that expects a remote URL (Smithery enterprise, hosted gateways)
- You want to test the API surface from the command line with `curl` before committing to a local install

Server card: [`https://api.hyperd.ai/.well-known/mcp.json`](https://api.hyperd.ai/.well-known/mcp.json).

## License

MIT — same as the parent repo.