Swolecharts
Live crypto data · 10 exchanges
Log inSign up

MCP server

A free, read-only Model Context Protocol server for AI agents and MCP clients: the same recorded market data as the JSON API, with units, UTC times, coverage gaps and freshness on every result.

8 toolsFree, read-onlyKey optional

Connect

Streamable HTTP, protocol 2025-11-25

Server URL: https://swolecharts.com/mcp. No account and no payment. A free API key is optional; send it as an X-API-Key header (never in the URL).

Machine-readable discovery: MCP server card.

Copy-paste setup for Claude Code, Claude Desktop, Cursor and VS Code is below, then 6 worked examples, including Hyperliquid API data. Leave out headers to call without a key. Supported protocol versions: 2025-11-25, 2025-06-18.

Set up your client

4 clients

Claude Code

Run once in a terminal. The second line adds the optional key.

claude mcp add --transport http swolecharts https://swolecharts.com/mcp
claude mcp add --transport http swolecharts https://swolecharts.com/mcp --header "X-API-Key: YOUR_KEY"

Claude Desktop

Add to claude_desktop_config.json (Settings, Developer, Edit Config), then reopen the app. The mcp-remote bridge needs Node.js. Or add the URL as a custom connector in Settings, Connectors.

{
  "mcpServers": {
    "swolecharts": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://swolecharts.com/mcp"
      ]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). Add a headers object for a key.

{
  "mcpServers": {
    "swolecharts": {
      "url": "https://swolecharts.com/mcp"
    }
  }
}

VS Code

Add to .vscode/mcp.json (GitHub Copilot agent mode). Add a headers object for a key.

{
  "servers": {
    "swolecharts": {
      "type": "http",
      "url": "https://swolecharts.com/mcp"
    }
  }
}

Examples

prompt, tool call, trimmed response

Illustrative responses are trimmed to one or two rows and show the data field of the result envelope (see below), except the Hyperliquid example which includes selected envelope fields. Live calls also carry status, freshness, coverage and units.

1. “Which ETH perpetual markets hold the most open interest right now, and what is their funding?”

market_snapshot with {"base": "ETH", "limit": 2}

{
 "base": "ETH",
 "truncated": true,
 "markets": [
  {
   "market": "binance:perp:ETHUSDT",
   "venue": "binance",
   "type": "perp",
   "symbol": "ETHUSDT",
   "price_usd": 2400.5,
   "oi_usd": 5100000000,
   "volume_24h_usd": 9800000000,
   "funding_8h_fraction": 0.0001,
   "funding_interval_h": 8,
   "observed_at": "2026-09-30T11:59:00Z",
   "stale_fields": []
  },
  {
   "market": "binance:perp:ETHUSDC",
   "venue": "binance",
   "type": "perp",
   "symbol": "ETHUSDC",
   "price_usd": 2400.3,
   "oi_usd": 610000000,
   "volume_24h_usd": 1300000000,
   "funding_8h_fraction": 8e-05,
   "funding_interval_h": 8,
   "observed_at": "2026-09-30T11:59:00Z",
   "stale_fields": []
  }
 ]
}

2. “Show SOL's 8-hour funding rate over the last 30 days at daily steps. When was it most negative?”

funding_history with {"base": "SOL", "range": "30d", "step": "1d"}

{
 "base": "SOL",
 "requested_step": "1d",
 "actual_step_s": 86400,
 "coarsened": false,
 "points": [
  {
   "time": "2026-09-01T00:00:00Z",
   "funding_8h_fraction": 0.0001
  },
  {
   "time": "2026-09-02T00:00:00Z",
   "funding_8h_fraction": -4e-05
  }
 ]
}

3. “How did BTC open interest change over the past week, hour by hour?”

oi_history with {"base": "BTC", "range": "7d", "step": "1h"}

{
 "base": "BTC",
 "requested_step": "1h",
 "actual_step_s": 3600,
 "coarsened": false,
 "points": [
  {
   "time": "2026-09-23T12:00:00Z",
   "oi_usd": 31200000000
  },
  {
   "time": "2026-09-23T13:00:00Z",
   "oi_usd": 31350000000
  }
 ]
}

4. “Were more longs or shorts liquidated on BTC in the last 24 hours?”

liquidations_history with {"base": "BTC", "range": "24h", "step": "1h"}

{
 "base": "BTC",
 "requested_step": "1h",
 "actual_step_s": 3600,
 "coarsened": false,
 "points": [
  {
   "time": "2026-09-30T10:00:00Z",
   "long_usd": 5200000,
   "short_usd": 1900000
  },
  {
   "time": "2026-09-30T11:00:00Z",
   "long_usd": 800000,
   "short_usd": 3100000
  }
 ]
}

5. “Did the latest BTC volume spikes continue? What was the price 15 minutes later?”

spike_feed with {"base": "BTC", "limit": 2}

{
 "spikes": [
  {
   "id": "123456789",
   "time": "2026-09-30T11:50:00Z",
   "market": "binance:perp:BTCUSDT",
   "base": "BTC",
   "venue": "binance",
   "side": "buy",
   "volume_usd": 12000000,
   "baseline_multiple": 6.5,
   "spike_return_fraction": 0.01,
   "taker_buy_share": 0.8
  }
 ],
 "next_cursor": null
}

spike_outcomes with {"ids": ["123456789"]}

{
 "outcomes": [
  {
   "id": "123456789",
   "side": "buy",
   "horizons": [
    {
     "minutes": 5,
     "state": "observed",
     "return_fraction": 0.002,
     "directional_return_fraction": 0.002,
     "observed_at": "2026-09-30T11:55:00Z"
    },
    {
     "minutes": 15,
     "state": "observed",
     "return_fraction": -0.001,
     "directional_return_fraction": -0.001,
     "observed_at": "2026-09-30T12:05:00Z"
    }
   ]
  }
 ]
}

6. “How do I get Hyperliquid API data for BTC and its last seven days of funding?”

These calls select BTC perpetual markets on Hyperliquid. 0.0001 = 0.01% per 8h equivalent; Hyperliquid settles hourly. The history is the bucket average of normalized rates, not an annualized rate or an actual settlement payment series. Check live coverage, gaps and coarsened before using it.

Without MCP, use the equivalent public JSON URL: /api/series/funding?base=BTC&venue=hyperliquid&range=7d&step=1h (JSON funding reference).

This is one coin's venue history. The REST-only /api/hyperliquid/open-interest/history instead reports aggregate USD open interest as v (total), native and hip3; it is not BTC's history. Browse Hyperliquid funding rates and Hyperliquid open interest.

market_snapshot with {"base": "BTC", "venue": "hyperliquid"}

{
 "tool": "market_snapshot",
 "coverage": {
  "venues": [
   "hyperliquid"
  ]
 },
 "units": {
  "funding_8h_fraction": "fraction per 8 hours",
  "funding_interval_h": "h"
 },
 "data": {
  "base": "BTC",
  "truncated": false,
  "markets": [
   {
    "market": "hyperliquid:perp:BTC",
    "venue": "hyperliquid",
    "funding_8h_fraction": 0.0001,
    "funding_interval_h": 1
   }
  ]
 }
}

funding_history with {"base": "BTC", "venue": "hyperliquid", "range": "7d", "step": "1h"}

{
 "tool": "funding_history",
 "coverage": {
  "venues": [
   "hyperliquid"
  ]
 },
 "units": {
  "funding_8h_fraction": "fraction per 8 hours",
  "actual_step_s": "s"
 },
 "data": {
  "base": "BTC",
  "requested_step": "1h",
  "actual_step_s": 3600,
  "coarsened": false,
  "points": [
   {
    "time": "2026-10-20T01:00:00Z",
    "funding_8h_fraction": 0.0001
   }
  ]
 }
}

Tools

all read-only
ToolWhat it returns
market_snapshotMarket snapshot. Current price, open interest, 24h volume and 8-hour-normalised funding for one coin's markets across tracked exchanges, sorted by open interest. USD is exchange quote notional; funding is a fraction (0.0001 = 0.01% per 8 hours).
funding_historyFunding rate history. Funding rate history as an 8-hour-normalised fraction per bucket: each market's average in the bucket, OI-weighted across markets. Up to 10 years where settlement backfill exists. Descriptive history, not projected income.
oi_historyOpen interest history. Open interest in USD per bucket: the sum over markets of each market's last observation in the bucket (not summed across time). Up to 730 days.
liquidations_historyLiquidations history. Liquidated long and short notional in USD per bucket, from exchange liquidation reports (some venues publish only a sample). Missing buckets are omitted, never zero-filled. Up to 730 days.
spike_feedVolume spike feed. Persisted one-minute volume spike alerts, newest first, within a UTC window of at most 24 hours (default: the last hour). Page with next_cursor. Fetch outcomes with spike_outcomes.
spike_outcomesVolume spike outcomes. Observed price returns 5, 15 and 60 minutes after up to 50 volume spikes (ids from spike_feed). Return = later close / alert price - 1; directional return flips sign for sell spikes. Observed history only, no probabilities or predictions.
xray_risk_rankingPerp index risk ranking (estimate). Perpetuals ranked by estimated liquidation exposure within a price band divided by the estimated order-book depth of their mark-price index to that band (USD; ratio). Only fresh full-coverage rows are ranked; partial ones are listed apart; stale or insufficient ones are counted only. Static-book estimates from public exchange data: not a real cost to move any price, not a mark-price forecast, not trading advice or instructions. Sensitivity is uncalibrated (sensitivity_calibrated=false).
xray_risk_historyPerp index risk history (estimate). One perpetual's estimated index depth, liquidation exposure and exposure-to-depth ratio per band over time (5-minute or hourly, at most 300 points; longer windows are clamped to end at the requested end), with coverage states and the current index composition (exchange, pair, weight). Static-book estimates from public exchange data: not a real cost to move any price, not a mark-price forecast, not trading advice or instructions. Sensitivity is uncalibrated (sensitivity_calibrated=false).

History tools take exactly one of base (e.g. BTC) or market (binance:perp:BTCUSDT), and either range (24h, 30d, 1y; default 1d) or start+end in UTC ending in Z, never in the future. Optional step (1m, 5m, 15m, 1h, 4h, 1d), venue and type (perp, spot, all). Funding reaches back up to 10 years where settlement backfill exists; OI and liquidations 730 days. At most 1500 points per call (6000 with a key); a finer step is raised and reported as coarsened. market_snapshot returns up to 50 markets of one coin, spike_feed up to 200 spikes per page in a window of at most 24 hours, spike_outcomes up to 50 ids.

Units, freshness and gaps

  • Every result is one JSON envelope, as structuredContent and as a text block: status (ok, partial, unavailable), as_of, freshness, provenance (stores and method), coverage (requested and available bounds, recording gaps), units, warnings and data.
  • USD is exchange quote notional. Funding, returns and shares are fractions: 0.0001 = 0.01%. Funding is normalised to 8 hours; nothing is annualised. Times are UTC.
  • Missing buckets are omitted, never zero-filled. A period the recorder was down is a gap (recording_gap, status partial); unknown coverage says so (coverage_unknown).
  • History buckets are timed by their start; a current window is fresh while its newest bucket is at most one step plus 15 minutes old. A completed window is historical, not stale.
  • When a store is down a tool returns status: unavailable with isError: true and a retry_after_s hint, never an empty success. Spike outcomes are observed returns only: pending until due, unavailable with missing_outcome when overdue. No predictions or probabilities.

Limits and errors

RuleValue
Tool calls, shared with /api/series30/min per IP without a key, 120/min per key; cached answers count too
initialize, tools/list, ping and rejected calls60/min per IP
Calls in progress4 at once; beyond that HTTP 429 with Retry-After
Request body / result32 KiB / 1 MiB
Unknown keyHTTP 401
Bad arguments, unknown toolJSON-RPC error -32602
Batch requests, GET streams, sessionsnot supported (-32600, HTTP 405)

Try it with curl

H='-H Content-Type:application/json -H Accept:application/json,text/event-stream'
curl -s $H https://swolecharts.com/mcp -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl -s $H -H MCP-Protocol-Version:2025-11-25 https://swolecharts.com/mcp -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
curl -s $H -H MCP-Protocol-Version:2025-11-25 https://swolecharts.com/mcp \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"oi_history","arguments":{"base":"BTC","range":"7d","step":"1h"}}}'

Python, standard library only:

import json, urllib.request

URL = "https://swolecharts.com/mcp"
HEAD = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}

def rpc(i, method, params=None):
    body = json.dumps({"jsonrpc": "2.0", "id": i, "method": method, "params": params or {}}).encode()
    req = urllib.request.Request(URL, body, dict(HEAD, **{"MCP-Protocol-Version": "2025-11-25"}))
    with urllib.request.urlopen(req, timeout=15) as r:
        return json.load(r)["result"]

rpc(1, "initialize", {"protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": {"name": "demo", "version": "1"}})
print([t["name"] for t in rpc(2, "tools/list")["tools"]])
out = rpc(3, "tools/call", {"name": "market_snapshot", "arguments": {"base": "BTC", "limit": 3}})["structuredContent"]
print(out["status"], out["data"]["markets"] if out["data"] else out["reason"])

Usage counting

We count calls per tool per UTC day and estimate distinct callers with a keyed, rotating hash sketch. No arguments, IP addresses, keys, prompts or per-request logs are stored. Terms are the API terms: free, no SLA, attribution when you publish, no resale.

MCP FAQ

Does the MCP server cost anything?

No. It is free and read-only: no account, no payment and no trading tools. An optional free API key raises the limits.

Are the MCP limits separate from the JSON API?

No. Tool calls and /api/series requests share one budget: 30 a minute per IP without a key, 120 a minute per key.

Where does the data come from?

From exchange public APIs, recorded by swolecharts. The MCP server never calls an exchange itself; every result names its stores, coverage gaps and freshness.

What does the server store about my calls?

Only daily aggregate counts per tool and an approximate distinct-caller count. No arguments, IP addresses, keys or per-request logs are kept.