Connect an AI assistant or your own program, step by step

1. What you are setting up

Two doors to the same data, and one key opens both.

1. The AI assistant door (MCP)

   MCP is a plug that lets an assistant such as Claude or ChatGPT call our data while you chat. You ask "what is the BTC funding rate now" and the assistant fetches the answer from us. Nothing to install for the hosted version: you paste one address into the assistant's settings.

2. The program door (API)

   An API is an address your own script, spreadsheet or bot calls to get numbers back as JSON. You send a request with your key attached, we send the data.

3. The key

   A key is a long password that starts with bk_. It tells us which account is asking. A free account comes with one key and 15,000 calls a month, shared between the assistant door and the program door. The key is shown once, when you create it; treat it like a password.

2. Make your key (two minutes)

1. Sign in or create a free account

   Use the Sign in button at the top right. A new account only needs an email address; we send a link, you click it, done.

2. Open Data & API

   After signing in, open your account menu (top right) and choose Data & API. On a phone it is under the Me tab.

3. Create the key

   Scroll to the Keys section. Type a name that tells you where the key will live, for example "my laptop" or "ChatGPT", and press Create.

   The key appears once, in a box with a Copy button. Copy it now and paste it somewhere safe. If you close the page without copying, nothing is lost: revoke that key and create another.

   Below the key you also get a ready-made hosted MCP address with the key already inside. That address is for tools that cannot take a header (ChatGPT). Keep it private like the key.

3. claude.ai (web and mobile)

The hosted server, nothing to install.

1. Add the connector

   Open Settings, then Connectors, then Add custom connector.

   Name: ByKaranteli. URL: https://mcp.bykaranteli.com.

   Under Authentication choose No sign-in (claude.ai may mark it "Detected"). Do not pick "Sign in now" or "Sign in when needed", and leave OAuth Client ID and Client Secret empty.

   Open the request headers (sometimes under Advanced). Add one header: name x-api-key, value your key. Save.

   HeaderCopy

   x-api-key: bk_...your key...

2. Try it

   Start a chat, make sure the ByKaranteli connector is switched on for that chat, and ask: "Show me the liquidation map for BTC." The assistant lists our tools and calls them.

4. ChatGPT

ChatGPT cannot add a header, so the key travels inside the address.

1. Add the connector

   Open Settings, then Connectors (in some accounts this is under Developer mode), then Create.

   Name: ByKaranteli. URL: the address with your key, copied from Data & API. It looks like the line below.

   Authentication: none. Save.

   URLCopy

   https://mcp.bykaranteli.com/?key=bk_...your key...

   That address works like a password. If you paste it somewhere public, revoke the key on Data & API and make a new one.

5. Claude Desktop

Claude Desktop runs the small bykaranteli-mcp program on your computer. It needs Node.js installed (nodejs.org, the LTS download).

1. Edit the config file

   In Claude Desktop open Settings, then Developer, then Edit config. A file named claude_desktop_config.json opens.

   Paste the block below inside it (if the file already has an "mcpServers" part, add the "bykaranteli" entry inside it). Replace bk_... with your key. Save and restart Claude Desktop.

   claude_desktop_config.jsonCopy

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

6. Claude Code and Cursor

1. Claude Code (terminal)

   One command. Replace bk_... with your key.

   TerminalCopy

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

2. Cursor and other editors

   Open the editor's MCP settings (Cursor: Settings, then MCP, then Add) and paste the block below into mcp.json. Any editor that takes a URL plus headers works the same way.

   mcp.jsonCopy

   {
     "mcpServers": {
       "bykaranteli": {
         "url": "https://mcp.bykaranteli.com/mcp",
         "headers": { "Authorization": "Bearer bk_...your key..." }
       }
     }
   }

7. Call the API from a program

No assistant, just your own code or a spreadsheet.

1. Try one call without code

   On Data & API there is a Playground: pick an endpoint, press Send, read the JSON. It uses your browser session, so nothing to paste.

2. The same call from a terminal

   Every address under /api/public/ answers JSON. Attach the key as a header. Replace bk_... with your key.

   curlCopy

   curl -s "https://bykaranteli.com/api/public/funding-heatmap" -H "Authorization: Bearer bk_...your key..."

3. Read the answer's headers

   x-ratelimit-limit and x-ratelimit-remaining: how many calls a minute your plan allows and how many are left this minute.

   x-quota-limit, x-quota-used and x-quota-reset: your monthly figure, where you are, and when it resets.

   The full list of endpoints, fields and examples is on the developers page.

8. Limits, in plain words

1. Free account

   30 calls a minute and 15,000 a month, counted across the assistant door and the program door together. When the month's figure is used up, calls answer 429 ("too many") until the first day of the next month (UTC). Every page on the site keeps working.

2. If you need more

   Terminal ($29 a month) raises the key to 60 a minute and 150,000 a month at the same depth, and adds the member tools on the site.

   Builder ($49 a month) gives 300 a minute, 1,000,000 a month fair use, member depth on the API (LiqMap at every timeframe, 5-minute series) and 1,000 calls a month of the x402 catalog. Business and Scale add commercial licences, bulk exports and the live stream.

   Paid plans are never stopped: past their fair use they answer at the free speed until the month resets.

9. When something goes wrong

Every message below is one we send on purpose, and each has a fix.

The assistant says "this tool call needs an account key".

The connector has no key. In claude.ai add the x-api-key header; in ChatGPT use the address that contains ?key=; in Claude Desktop or Claude Code check the BYKARANTELI_API_KEY value. Listing the tools works without a key, calling one does not.

"The account key this connection sent was not recognised".

The key was copied with a missing character or a space, or it was revoked. Open Data & API, revoke it, create a new one and paste it again.

claude.ai asks for an OAuth Client ID.

The Authentication choice is wrong. Edit the connector, pick No sign-in, leave both OAuth fields empty, and put the key in the x-api-key header.

ChatGPT saved the connector but never answers.

Usually the authentication mode does not match: choose none, and make sure the URL contains ?key= with your full key.

My script gets 401 "key required".

The request has no key. Send it as Authorization: Bearer bk_... (or x-api-key: bk_...). Browsers on our own pages do not need one; programs always do.

429 "monthly quota".

The free 15,000 for this month are used. Wait for the first of the month, or move to Terminal or Builder on the pricing page.

429 "rate limit".

Too many calls in one minute. Slow down to the number in x-ratelimit-limit, or wait the seconds given in retry-after.

I lost my key.

Keys cannot be shown twice. Revoke the old one on Data & API and create a new one; the old one stops working immediately.

Words used on this page

API

An address a program calls to get data back, here as JSON text.

API key

A long password starting with bk_ that identifies your account on every call.

MCP

Model Context Protocol, the plug that lets an AI assistant call outside tools such as ours.

Connector

What claude.ai and ChatGPT call an MCP server you added to your account.

Header

A small label sent with a request; the key travels in one.

Rate limit

How many calls a minute a plan allows.

Quota

How many calls a month a plan allows.