# Coinversaa Mcp Server

> Hyperliquid trading intelligence for AI agents — cohort analytics, liquidation heatmaps, trader profiling, and real-time market data across 710K+ wallets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-coinversaa-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Coinversaa](https://agentstack.voostack.com/s/coinversaa)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.2.1
- **License:** MIT
- **Upstream author:** [Coinversaa](https://github.com/Coinversaa)
- **Source:** https://github.com/Coinversaa/mcp-server
- **Website:** https://coinversaa.ai/developers

## Install

```sh
agentstack add mcp-coinversaa-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Coinversa Pulse — MCP Server

Crypto intelligence for AI agents. Query the full Hyperliquid wallet universe, indexed trade history with PnL attribution, behavioral cohorts, and live market data through any MCP-compatible client. Call `pulse_global_stats` to see exact current coverage (tracked wallets, indexed trades, volume, PnL, data window).

**Now with HIP-4 outcome contracts and builder dex support** — inspect prediction-market style outcome contracts, settlements, commodities (gold, silver, oil), stocks (TSLA, AAPL), and perps across 8 dexes and 369+ markets.

## What's new in 0.9.0

**Entity resolution, tier-aware sessions, and chain-verified answers.**

| New tool | What it answers |
|----------|-----------------|
| `pulse_entity_profile` [Pro] | "Who owns this wallet — and what is their REAL combined book across every sub-account?" |
| `pulse_entity_leaderboard` [Pro] | "Top traders deduped by OWNER, not wallet — a fund running 35 sub-accounts shows as one entity." |
| `pulse_my_plan` | "What plan is this API key on, what are the limits, and what does upgrading unlock?" |
| `pulse_exchange_volume` | "24h volume — total and per dex (builder dexes are ~43% and most trackers miss them)." |
| `pulse_exchange_oi` | "Open interest by dex with long/short split." |
| `pulse_active_traders` | "How many wallets traded in the last 24h?" |
| `pulse_exchange_positions` | "How many positions are open right now, per dex?" |
| `pulse_pnl_leaders` | "Who made and lost the most in the last 24h, exchange-wide?" |

Also in 0.9.0:
- **Tier-aware errors** — a tier-gated or rate-limited request now explains the caller's tier, the required tier, and carries a direct upgrade link. (Fixes valid free-tier keys being told their key was "rejected" on Pro endpoints.)
- **Verified-vs-chain stamps** — entity responses carry the chain-state block they were last reconciled against.

Tool count: **83 → 91**.

## What's new in 0.8.0

**Position lifecycles, execution quality, and trader archetypes.** v0.8.0 adds 28 tools built on a fully re-derived position-lifecycle dataset — every open→close cycle reconstructed from on-chain fills, now carrying MAE/MFE (the worst adverse and best favorable price each position ever saw). This unlocks execution-quality analysis, not just PnL.

| New tool | What it answers |
|----------|-----------------|
| `pulse_trader_lifecycles` | "Show me every open→close position for this wallet, with entry/exit and hold time." |
| `pulse_trader_lifecycle_summary` | "What are this wallet's position-level stats — win rate, avg hold, biggest win/loss?" |
| `pulse_lifecycle` | "Break down lifecycle 12345 into every fill that built and unwound it." |
| `pulse_trader_demo` | "Give me a quick wallet brief before a deeper dive." |
| `pulse_wallet_drawdown_curve` | "How far underwater did each of this wallet's positions go before working?" |
| `pulse_max_pain_events` | "Which winners survived the deepest drawdowns before recovering?" |
| `pulse_perfect_exits` | "Which exits captured most of the maximum favorable move?" |
| `pulse_backstop_events` | "What were the most catastrophic individual liquidations?" |
| `pulse_survivors` / `pulse_anti_survivors` | "Who blew up and recovered — and who never did?" |
| `pulse_persistent_winners` | "Who is profitable across multiple distinct months, not just lucky once?" |
| `pulse_capital_titans` | "Who extracts the most PnL per dollar of fees paid?" |
| `pulse_one_month_wonders` | "Who had one huge month then gave it back?" |
| `pulse_newcomer_whales` | "Who just showed up and is already trading big notional?" |
| `pulse_coin_kings` | "Who is the top earner of each coin?" |
| `pulse_top_liquidators` | "Who profits most by liquidating others?" |
| `pulse_lethal_coins` | "Which coins blow people up most often?" |
| `pulse_coin_alpha_map` | "Per coin, how big are the winner vs loser profit pools?" |
| `pulse_hour_profitability` | "What UTC hour of close is most profitable?" |
| `pulse_market_concentration` | "How concentrated is alpha — do the top 1% take everything?" |
| `pulse_style_distribution` | "Do scalpers or swing traders make more money?" |
| `pulse_compare` | "Head-to-head: who is the better trader, A or B?" |
| `pulse_cohort_recent_*` | "What are wallets that are printing RIGHT NOW (last-30-day tier) doing — positions, trades, top lifecycles, concentration?" |
| `pulse_lifecycles_recent` | "What just closed exchange-wide right now?" (global feed; successor to `pulse_recent_closed_positions`) |

The legacy closed-position tools (`pulse_trader_closed_positions`, `pulse_trader_closed_position_stats`, `pulse_recent_closed_positions`) are kept for backward compatibility but **superseded** by the lifecycle tools, which read the corrected `position_lifecycles_full` table (more history, MAE/MFE, spot).

Tool count: **55 → 83**. An API key is required for every tool; backend tiering determines which tools and limits are available.

## What's new in 0.7.0

**HIP-4 outcome contract intelligence.** v0.7.0 adds 12 tools for discovering active outcomes, reading question metadata, inspecting settlements and recent fills, tracking daily volume, ranking outcome traders, measuring outcome/perp overlap, and joining outcome holders to their currently open perp positions on the same underlying asset.

| New tool | What it answers |
|----------|-----------------|
| `hip4_outcomes` | "What outcome contracts are active right now?" |
| `hip4_outcome` | "What is outcome 123 and what side tokens does it use?" |
| `hip4_outcome_summary` | "How much volume/PnL has this outcome done across both sides?" |
| `hip4_outcome_recent_trades` | "Show me recent fills for this prediction market." |
| `hip4_questions` | "What HIP-4 questions and named outcomes exist?" |
| `hip4_recent_settlements` | "Which outcomes settled recently and which side won?" |
| `hip4_daily_volume` | "Is HIP-4 outcome volume growing day by day?" |
| `hip4_most_active` | "Which outcome contracts are most active?" |
| `hip4_top_traders` | "Who are the top outcome traders?" |
| `hip4_trader_outcomes` | "What outcomes did this wallet trade?" |
| `hip4_cross_product_overlap` | "How much overlap is there between outcome traders and perp traders?" |
| `hip4_perp_position_context` | "Do outcome 25 traders currently have open BTC perp exposure, and is it aligned or hedged?" |

Tool count: **43 → 55**. An API key is required for every tool; backend tiering determines which tools and limits are available. Get a key from [coinversa.ai/developers](https://coinversa.ai/developers).

## What's new in 0.6.0

**Canonical cross-market asset taxonomy.** The same underlying asset can appear under different tickers on different venues (e.g. `GOLD` on xyz, `PAXG` on native Hyperliquid — both track gold). v0.6.0 added 3 tools that resolve synonyms server-side and aggregate across venues, plus a ground-truth OI tool:

| New tool | What it answers |
|----------|-----------------|
| `list_assets` | "What assets are available? Which are listed on 2+ venues?" |
| `list_asset` | "Where does GOLD trade? Is PAXG the same as GOLD?" |
| `pulse_cross_market_asset` | "Is gold more crowded on xyz or hyna? Do dexes disagree on BTC direction?" |
| `live_official_oi` | "What does Hyperliquid itself report for BTC OI — do our numbers match?" |

Synonyms baked in: `PAXG → GOLD`, `XAUT → GOLD`, `XAGT → SILVER`. Prefix grouping (`BTC` ≡ `flx:BTC` ≡ `hyna:BTC`) works automatically.

Other 0.6.0 housekeeping: default API URL points at production; removed stale hard-coded "710K+ wallets / 1.8B+ trades" marketing figures (call `pulse_global_stats` for current coverage); `pulse_market_overview` kept as a deprecated alias for the canonical `list_markets`.

## Quick Start

### API Key Required

Get a key at [coinversa.ai/developers](https://coinversa.ai/developers) or email [chat@coinversaa.ai](mailto:chat@coinversaa.ai).

You can connect in two ways:

| Method | Endpoint / command | Best for |
|--------|--------------------|----------|
| Hosted Remote MCP | `https://mcp.coinversa.ai/mcp` | Remote MCP clients and custom connectors that support Streamable HTTP |
| Local stdio MCP | `npx -y @coinversaa/mcp-server@0.9.0` | Claude Desktop, Cursor, Claude Code, Codex, and local MCP clients |

Remote MCP clients should send the Coinversa key as either `Authorization: Bearer cvsa_...` or `X-API-Key: cvsa_...`.

Local MCP clients must pass `COINVERSAA_API_KEY`:

```json
{
  "mcpServers": {
    "coinversaa": {
      "command": "npx",
      "args": ["-y", "@coinversaa/mcp-server@0.9.0"],
      "env": {
        "COINVERSAA_API_KEY": "cvsa_your_key_here"
      }
    }
  }
}
```

#### Claude Desktop

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

```json
{
  "mcpServers": {
    "coinversaa": {
      "command": "npx",
      "args": ["-y", "@coinversaa/mcp-server@0.9.0"],
      "env": {
        "COINVERSAA_API_KEY": "cvsa_your_key_here"
      }
    }
  }
}
```

#### Cursor

Add to `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "coinversaa": {
      "command": "npx",
      "args": ["-y", "@coinversaa/mcp-server@0.9.0"],
      "env": {
        "COINVERSAA_API_KEY": "cvsa_your_key_here"
      }
    }
  }
}
```

#### Claude Code

```bash
claude mcp add coinversaa -- npx -y @coinversaa/mcp-server@0.9.0
```

Set the env var in your shell:
```bash
export COINVERSAA_API_KEY="cvsa_your_key_here"
```

That's it. No cloning, no building — `npx` handles everything for local MCP.

## Remote MCP (HTTPS Connector)

Hosted remote endpoint:

```text
https://mcp.coinversa.ai/mcp
```

Use the hosted endpoint with remote MCP clients such as Perplexity custom
connectors, or any MCP client that supports Streamable HTTP.

The npm / stdio workflow above remains the recommended path for Claude Desktop,
Cursor, Claude Code, Codex, and other local MCP clients.

For remote MCP clients such as Perplexity custom connectors, this repo also
ships a separate HTTP entrypoint:

```bash
npm run build
PORT=3000 npm run start:http
```

Remote endpoints:

| Endpoint | Transport | Notes |
|----------|-----------|-------|
| `/mcp` | Streamable HTTP | Recommended remote MCP endpoint |
| `/sse` | HTTP + SSE | Legacy compatibility endpoint |
| `/health` | JSON | Health check |

Authentication is read-only API-key forwarding. The remote MCP accepts a
Coinversa key via either header:

```text
Authorization: Bearer cvsa_...
X-API-Key: cvsa_...
```

The remote server forwards that key to the Coinversa API as `X-API-Key`. If no
key is supplied, MCP requests are rejected. The default backend is production (`https://api.coinversa.ai`); set
`COINVERSAA_API_URL` only for self-hosted or staging deployments.

Coinversa's hosted production Remote MCP URL is:

```text
https://mcp.coinversa.ai/mcp
```

For self-hosted deployments, run `build/remote.js` behind TLS at your own stable
URL.

Optional deployment env vars:

| Variable | Purpose |
|----------|---------|
| `PORT` | HTTP port, default `3000` |
| `HOST` | Bind host, default `0.0.0.0` |
| `COINVERSAA_API_URL` | Backend API base URL override |
| `COINVERSAA_REMOTE_ALLOWED_HOSTS` | Comma-separated allowed Host headers |
| `COINVERSAA_REMOTE_ALLOW_ENV_API_KEY=true` | Allow env-key fallback for private/internal deployments only |

## Builder Dex Markets

Hyperliquid supports multiple builder dexes beyond the native perps exchange. Each dex has its own set of markets, collateral token, and symbol format.

| Dex | What it trades | Collateral | Example symbols |
|-----|----------------|------------|-----------------|
| *(native)* | Core perps (crypto) | USDC | BTC, ETH, SOL, HYPE |
| `xyz` | Commodities, stocks, indices | USDC | xyz:GOLD, xyz:SILVER, xyz:TSLA |
| `flx` | Perps | USDH | flx:BTC, flx:ETH |
| `vntl` | Perps | USDH | vntl:ANTHROPIC, vntl:BTC |
| `hyna` | Perps | USDE | hyna:SOL, hyna:BTC |
| `km` | Energy & commodities | USDH | km:OIL, km:NATGAS |
| `abcd` | Misc | USDC | abcd:BITCOIN |
| `cash` | Stocks & equities | USDT0 | cash:TSLA, cash:AAPL |

**Symbol format:**
- Native Hyperliquid symbols: `BTC`, `ETH`, `SOL`
- Builder dex symbols: `prefix:COIN` — e.g. `xyz:GOLD`, `cash:TSLA`, `hyna:SOL`

Use the `list_markets` tool to discover all available symbols and which dex they belong to.

Backend trading note for agentic traders: Coinversaa's backend-signed Hyperliquid orders use an approved Hyperliquid agent wallet, not a `vaultAddress`. If the backend signer changes, re-approve that signer on Hyperliquid before submitting orders. Builder dex orders may also require unified account mode so USDC collateral is shared across supported dexes. For isolated-only markets, omitted `marginMode` now defaults to `isolated`; do not assume `cross` is available on builder dex symbols.
Frontend account-mode note: the app can now prepare a user-signed abstraction change via `POST /api/v1/hyperliquid/prepare-abstraction`, which lets the user enable or disable Unified Account mode without leaving Coinversa. Hyperliquid may still reject a transition for exchange-side reasons.

## Cross-Market Asset Taxonomy

The same underlying asset can appear under different tickers on different venues (e.g. `GOLD` on xyz and `PAXG` on hyna both track gold). Coinversa exposes a **canonical asset registry** so you don't have to reinvent the grouping.

- **Canonical** — the economic-exposure identifier (`GOLD`, `BTC`, `ETH`).
- **Symbol** — what a venue lists it as (`xyz:GOLD`, `hyna:PAXG`, `BTC`, `flx:BTC`).
- **Synonyms** (ticker → canonical): `PAXG → GOLD`, `XAUT → GOLD`, `XAGT → SILVER`.

Use `list_assets` / `list_asset` / `pulse_cross_market_asset` for anything asset-level (venue availability, cross-venue OI, cross-venue bias disagreement). Use `list_markets` / `market_price` for single-venue queries.

**How grouping works:**
- Same ticker across venues (`BTC`, `flx:BTC`, `hyna:BTC`) → automatically grouped under canonical `BTC`. Zero-config.
- Different ticker, same exposure (`PAXG` and `GOLD` both track 1 oz gold) → resolved via the synonym table above.
- Wrapped or staked variants (`WBTC`, `WETH`, `stETH`, `wstETH`) → **not** aggregated by default. They have different risk profiles and liquidity; treat them as independent assets.

**Example: what "GOLD" looks like aggregated** (live snapshot, April 2026):
- 6 venues: `xyz:GOLD` ($149M OI dominant), `PAXG` (native HL, $39M), `cash:GOLD`, `km:GOLD`, `flx:GOLD`, `hyna:GOLD`
- `netBias: 0.27` — moderately long across venues
- `biasRange: 0.61` — venues disagree strongly on strength of conviction (worth flagging in any answer)
- `synonyms: ["GOLD", "PAXG"]` — confirms PAXG was correctly merged into canonical GOLD

Numbers are illustrative — call `pulse_cross_market_asset` with `canonical: "GOLD"` for current values.

### Backend dependency

The 3 asset tools call `/api/public/v1/assets*` endpoints on the production Coinversa backend (`https://api.coinversa.ai`). Self-hosted or forked setups need to run a backend that exposes these routes; see the Coinversa backend repo for the reference implementation.

## Available Tools (82)

All 91 tools require an API key. The MCP registers the full tool set, and the Coinversa API enforces access by key tier. Free API keys can use public/discovery routes, while Starter, Pro, and Enterprise keys unlock deeper trader, HIP-4, risk, historical, and official OI tools.

### Risk Tools Freshness

Syncer-backed risk tools such as `live_risk_overview`, `live_coin_risk_snapshot`, `live_coin_risk_history`, `live_mark_dislocations`, `live_recent_liquidations`, `live_liquidation_summary`, `live_oi_history`, and `live_cohort_bias_history` are best treated as **beta recent-intelligence tools**. For venue ground-truth OI, `live_official_oi` pulls directly from Hyperliquid's Info API as a cross-check.

- Best for research, LLM training, liquidation analysis, OI trend work, and crowding detection
- Best queried over recent wind

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Coinversaa](https://github.com/Coinversaa)
- **Source:** [Coinversaa/mcp-server](https://github.com/Coinversaa/mcp-server)
- **License:** MIT
- **Homepage:** https://coinversaa.ai/developers

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.2.1 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.2.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-coinversaa-mcp-server
- Seller: https://agentstack.voostack.com/s/coinversaa
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.