bykaranteli-mcp

MCP (Model Context Protocol) server for live crypto derivatives data: funding rates, cross-exchange funding arbitrage, open interest pressure, liquidations, options, ETF flows, Fear & Greed and BTC dominance.

68 read-only and account tools over the public JSON API of bykaranteli.com: the market data tools only read, and the alert and watchlist tools act on your own account through your key (Account tools). Since 2026-09-10 the API asks programs for an account key: a free key comes with any verified account at https://bykaranteli.com/dashboard/api (30 requests a minute and 15,000 a month, public depth), and the Builder, Business and Scale plans raise the rate and the monthly fair use and unlock member depth (LiqMap on seven timeframes, 5-minute series) and a monthly allowance of x402 catalog calls within each plan's history window (Plans and paid depth). Set it as BYKARANTELI_API_KEY. Data covers Binance USDT-M perpetuals; funding arbitrage, liquidations, order book depth, options, positioning and insurance funds add the other venues each board lists on bykaranteli.com/coverage.

Hosted endpoint (no install)

Paste https://mcp.bykaranteli.com as a custom connector in any MCP-capable assistant. The same tools, nothing to install. Every tool call needs your account key (free at https://bykaranteli.com/dashboard/api); connecting and listing the tools work without one. The key travels one of three ways:

• the request header x-api-key: bk_... (claude.ai custom connectors, Cursor, Claude Code);
• the request header Authorization: Bearer bk_...;
• the address https://mcp.bykaranteli.com/?key=bk_... for clients that cannot send headers (ChatGPT). Treat that address like a password and revoke the key if it leaks.

Or sign in with OAuth 2.1 where the client offers it (claude.ai custom connectors: Authentication, Sign in; ChatGPT connectors: OAuth): the client identifies itself with its client metadata document (an https client id the authorization server reads, the way the 2026-07-28 MCP revision prefers) or registers itself (RFC 7591), always with PKCE S256; you approve it once on bykaranteli.com and it runs on a key of your own account, which the Data and API page lists under connected apps. Discovery: https://mcp.bykaranteli.com/.well-known/oauth-protected-resource.

A free account covers the API and the hosted MCP on one monthly counter; Builder and above bring higher rates and member depth.

Step-by-step guide for beginners: https://bykaranteli.com/guide/connect

Quick start

Claude Code

claude mcp add bykaranteli -e BYKARANTELI_API_KEY=bk_... -- npx -y bykaranteli-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "bykaranteli": {
      "command": "npx",
      "args": ["-y", "bykaranteli-mcp"],
      "env": { "BYKARANTELI_API_KEY": "bk_..." }
    }
  }
}

Cursor / other MCP clients

Any stdio MCP client works: command npx, args ["-y", "bykaranteli-mcp"], env BYKARANTELI_API_KEY.

Requires Node.js 20 or newer (1.0.0; the 0.x releases ran on 18). The server speaks both the 2026-07-28 revision of the protocol and the 2025-era initialize handshake, so every MCP client released so far connects unchanged.

Tools

All market answers are JSON and carry a generatedAt timestamp, a source URL to the human-readable page and a provenance block: source_page, api_path, the answer's own generated_at, fetched_at, and when the answer carries them the venues behind the number, coverage (full, sampled or mixed), stale_venues and recorded_since, plus the proof page (https://bykaranteli.com/proof). A field the answer does not carry is left out, never filled in. Symbols accept both BTCUSDT and bare BTC.

Answers are sized for a model's context: a call without arguments returns a short first page (for example 30 rows, or the newest points of a series), never a whole board. Every shortened list is named in trimmed with field, returned, total and more, the parameter that returns the rest (symbol, coin, asset, limit, days, detail and the like); a filtered call keeps its full detail. One answer is capped at 100,000 characters; above that the tool says how to narrow the call.

Thirteen large tools (get_liqmap, get_turkey_premium, get_correlations, get_hl_whales, get_options_flow, get_funding_arbitrage, get_desk_notes, get_positioning, get_coverage, get_new_listings, get_venue_markets, get_tokenized_stocks, get_factor_board) also take detail: "compact" answers a shorter page than the default one (fewer rows, numbers rounded to six significant digits, long free text cut, grids left out; every cut named in trimmed), "full" the whole route answer. get_liqmap and get_coverage keep their boolean form, where true means full. Since 1.1.0.

Account tools (alerts and watchlist)

These tools read and change your own ByKaranteli account with the same key: the alert recipes that notify you on Telegram, email, push or webhook, and your watchlists. They never trade, move funds or touch another account.

• The write tools carry readOnlyHint: false (and destructiveHint: true for the two that remove something), so clients that ask before a change will ask.
• How many recipes an account keeps follows its plan; past it, create_alert_recipe answers with the limit instead of saving.
• Every call counts on the key's plan like any other request; writes are also rate limited per key, and each write is recorded on the account with the key that made it.
• Recipes and watchlist changes show up at once on https://bykaranteli.com/dashboard/alerts and https://bykaranteli.com/dashboard/watchlist.
• If a tool call answers 401, the body's error_description says what to send and the x-byk-mcp-auth header names the cause: key_required (no credential at all), key_unusable (a header or the address carried no key: the bk_... placeholder, an unset variable, a non-Bearer scheme, an OAuth token of the wrong shape), key_wrong_type (a prepaid bk_live_ key, which pays per call on /api/x402/* and does not open the MCP) or key_unrecognised (mistyped, expired or revoked). The WWW-Authenticate challenge starts the OAuth sign-in in clients that support it. This package forwards the REST body verbatim, so the same sentence reaches the model over stdio.

Configuration

Data notes

• The signal engine was retired in September 2026; this server publishes recorded market data only, no trading signals or performance claims.
• Funding, OI and pressure data refresh every 15 to 30 minutes; indices every 30 minutes.
• Nothing here is financial advice. See bykaranteli.com/risk-guide.

Development

npm install
npm run build
node dist/index.js   # speaks MCP over stdio

Release notes per version: CHANGELOG.md.

License

Server: MIT. Data: personal and research use with attribution "ByKaranteli (bykaranteli.com)"; commercial use with the Business plan. Licence text: https://bykaranteli.com/data#license.

Plans and paid depth

Prices: https://bykaranteli.com/pricing

A Free or Terminal key past its monthly figure gets 429 until the month resets. A paid key past its fair use is never stopped: it answers at the Free rate (30 a minute) until the month resets, with x-quota-state: slow on every answer.

Full table: https://bykaranteli.com/developers#tiers. For recorded history and raw records beyond the live snapshots, bykaranteli.com also exposes pay-per-call x402 endpoints for anonymous agents (USDC on Solana or Base, priced per call, no account): https://bykaranteli.com/developers#x402 · machine catalog: https://bykaranteli.com/api/x402. Builder, Business and Scale keys call those routes unpaid within the plan's catalog allowance (table above); each included call also counts as 10 requests of the monthly fair use. A call the plan does not include answers x402_allowance_used, history_window or raw_tier_required, and a route the plan does not carry answers tier_required (bulk exports start at Business): pay it with a prepaid key in x-api-key while the account key stays in Authorization: Bearer, or without the account key from a wallet.