Coinversaa Mcp Server

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.

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

{
  "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):

{
  "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:

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

Claude Code

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

Set the env var in your shell:

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:

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:

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:

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:

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
• Source: Coinversaa/mcp-server
• License: MIT
• Homepage: https://coinversaa.ai/developers

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