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)

Signing in from claude.ai, ChatGPT or Claude Code (sections 3, 4 and 6)? Skip this. A key is for Claude Desktop, Cursor, your own programs and any connector you set up without sign-in.

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 can neither sign in nor take a header. Keep it private like the key.

3. claude.ai (web and mobile)

The hosted server: nothing to install and nothing to copy. You sign in once.

1. Add the connector

   Open Settings, then Connectors, then Add custom connector.

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

   Under Authentication choose Sign in (now or when needed). Leave OAuth Client ID and Client Secret empty: claude.ai registers itself with bykaranteli.com. Save.

2. Sign in and approve

   Press Connect if claude.ai does not open it on its own. A bykaranteli.com window opens: sign in, or create a free account there.

   The consent page names claude.ai and lists what it may do: use the data tools, and read and change your alerts, watchlist and tracked addresses, never your account, keys or billing. Press Allow.

   You are back in claude.ai and the connector shows as connected. It runs on your account and your plan. To disconnect it later, use Connected apps on Data & API, or remove the connector in claude.ai.

3. Or with a key instead

   Choose No sign-in under Authentication, open the request headers (sometimes under Advanced) and add one header: name x-api-key, value your key from section 2. Save.

   HeaderCopy

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

4. 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

Two ways: sign in with OAuth (nothing to copy), or put the key inside the address.

1. Add the connector with sign-in

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

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

   Authentication: OAuth. Leave any client ID and secret fields empty: ChatGPT registers itself with bykaranteli.com. Save, sign in on the bykaranteli.com window and press Allow on the consent page.

2. Or with the key in the address

   Authentication: none. URL: the address with your key, copied from Data & API. It looks like the line below. 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)

   Hosted, with sign-in: add the server with the first command, then type /mcp inside Claude Code, pick bykaranteli and choose Authenticate. A browser window opens; sign in and press Allow.

   Or run the package on your computer with your key (Node.js needed): the second command. Replace bk_... with your key.

   Terminal, hosted with sign-inCopy

   claude mcp add --transport http bykaranteli https://mcp.bykaranteli.com

   Terminal, local with a keyCopy

   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

   A free key is for evaluation and personal use: trying the API, a personal script or Jupyter notebook, a look at the data. Anything that runs continuously, a bot, a dashboard or an agent that polls, takes a plan: Terminal for a hobby bot, Builder for one person's tools at member depth, Business for anything that serves other people or earns money.

   Terminal, the membership for people (price on the pricing page), raises the key to 60 a minute and 150,000 a month at the same depth, and adds the desk that runs on our side while you are away: alerts, member depth on the boards and the LiqMap workspace.

   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 the x402 catalog with 1,000 calls a month over the last 90 days, summary series only (each call also counts as 10 requests of the monthly fair use). Business and Scale add commercial licences, raw records, a longer history window, 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 and is not signed in. claude.ai and Claude Code show a sign-in prompt for this: follow it (in Claude Code type /mcp and choose Authenticate). Otherwise choose Sign in on the claude.ai connector or add the x-api-key header; in ChatGPT choose OAuth or use the address that contains ?key=; in Claude Desktop 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.

Leave both OAuth fields empty in either case. With Sign in, claude.ai registers itself and no id is typed; with No sign-in, the key goes in the x-api-key header.

ChatGPT saved the connector but never answers.

Usually the authentication mode does not match the address: with OAuth use the plain address and sign in; with none the URL must contain ?key= and your full key.

My script gets 401 "key required".

The request reached the gate without a usable key: no key header, an empty value (an unset variable), something that is not a full key (the bk_... placeholder, the prefix from the key list) or Authorization without the Bearer scheme; the reason field in the 401 body names which. Send the full key 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.

Can the assistant change anything on my account?

Only your alerts, your watchlist and your tracked addresses, and only through the tools create_alert_recipe, delete_alert_recipe, add_watchlist_symbol, remove_watchlist_symbol, add_tracked_address and remove_tracked_address. They are marked as writes, so an assistant that confirms changes asks you first. They use the same key, count on your plan, and every change is recorded on your account and shows at once on the alerts, watchlist and tracked addresses pages. Nothing trades or moves funds. To stop it, disconnect the app under Connected apps on Data & API if it signed in, or revoke the key it holds there if it uses one.

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.

Sign in (OAuth)

Connecting an assistant to your account by approving it once on bykaranteli.com; the assistant gets a key of its own and you copy nothing.

Rate limit

How many calls a minute a plan allows.

Quota

How many calls a month a plan allows.