// SYSTEM_INTRODUCTION

BitMidpoint API

BitMidpoint is a multi-exchange crypto price aggregation platform that surfaces real-time price spreads across major crypto exchanges. Our API provides developers with access to unified token pricing, exchange-level spread detection, and arbitrage opportunity identification.

Unlike traditional price aggregators (CoinGecko, CMC), BitMidpoint doesn't just average prices—we capture the full distribution across exchanges, letting you identify and exploit arbitrage windows that most tools hide.

Base URL: https://bitmidpoint.com/api/v1

See CryFolio

A portfolio tracker built on this API. Real-time P/L with multi-exchange prices.

Learn more →

// AUTHENTICATION

Authentication

The BitMidpoint API supports two authentication modes:

Anonymous Access

Public endpoints allow anonymous requests (rate limited to 30 req/min per session/IP). No authentication header required.

API Key Authentication

For higher rate limits (120 req/min) and usage tracking, generate a free API key from your Account dashboard. Include your key in the X-API-Key header.

API Key Format: cbv_<uuid> (e.g., cbv_3f9a2b1c-...)

REQUEST HEADERS

Header	Value	Required	Description
`X-API-Key`	`cbv_your-key`	Optional	API key for higher rate limits
`Content-Type`	`application/json`	POST	Required for POST requests

// API_ENDPOINTS

Endpoints

GET /api/v1/tokens

Fetch all tracked tokens sorted by volume and spread. This is the primary entry point for discovering aggregated crypto pricing data.

Parameters

Parameter	Type	Required	Description
—	—	—	No query parameters

Response

{ "success": true, "count": 500, "data": [ { "rank": 1, "symbol": "BTC", "name": "Bitcoin", "avgPrice": 45230.50, "minPrice": 45100.00, "maxPrice": 45450.00, "spreadPct": 0.782, "totalVolume": 28500000000, "exchanges": ["Binance", "Coinbase", "Kraken", "Huobi"] }, ... ] }

GET /api/v1/tokens/:symbol

Get detailed information for a single token by symbol. Returns the same data structure as the /tokens endpoint but for a specific cryptocurrency.

Parameters

Parameter	Type	Required	Description
`symbol`	string	✓	Token symbol (e.g., BTC, ETH)

Response

{ "success": true, "data": { "rank": 1, "symbol": "BTC", "name": "Bitcoin", "avgPrice": 45230.50, "minPrice": 45100.00, "maxPrice": 45450.00, "spreadPct": 0.782, "totalVolume": 28500000000, "exchanges": ["Binance", "Coinbase", "Kraken", "Huobi"] } }

GET /api/v1/tokens/:symbol/history

Fetch historical price data for a token over a specified time range. Data points are hourly snapshots of min/avg/max prices across exchanges.

Parameters

Parameter	Type	Required	Description
`symbol`	string	✓	Token symbol (path parameter)
`range`	string	—	24h, 7d, or 30d (default: 24h)

Response

{ "success": true, "data": [ { "timestamp": "2026-03-20T08:00:00Z", "avgPrice": 45230.50, "minPrice": 45100.00, "maxPrice": 45450.00 }, { "timestamp": "2026-03-20T09:00:00Z", "avgPrice": 45180.25, "minPrice": 45000.00, "maxPrice": 45400.00 }, ... ] }

GET /api/v1/markets

Get aggregate market statistics including total tokens tracked, connected exchanges, average spread percentage, and top arbitrage opportunities.

Parameters

Parameter	Type	Required	Description
—	—	—	No query parameters

Response

{ "success": true, "data": { "totalTokens": 500, "totalExchanges": 8, "avgSpread": 0.621, "consensusScore": 82, "topArbitrage": [ { "symbol": "SHIB", "spreadPct": 3.245, "minPrice": 0.00000852, "maxPrice": 0.00000879 }, ... ] } }

// RATE_LIMITING

Rate_Limits

The API implements a fixed 60-second sliding window rate limiter with burst-friendly parallelism. All requests are counted within a rolling 60-second window.

Authentication Mode	Limit	Identifier	Window
Anonymous (no API key)	30 req/min	Session ID or IP	60 seconds
API Key (authenticated)	120 req/min	Per API key	60 seconds

Response Headers

Every API response includes rate limit information in headers:

X-RateLimit-Limit: 30 X-RateLimit-Remaining: 18 X-RateLimit-Reset: 2026-03-20T14:32:45.000Z X-RateLimit-Window: 60

Rate Limit Exceeded (429)

When the rate limit is exceeded, you'll receive a 429 response:

{ "success": false, "error": "Rate limit exceeded for your API key", "hint": "Upgrade to a higher tier or wait 18 seconds", "retryAfter": 18, "resetAt": "2026-03-20T14:32:45.000Z" }

// ERROR_HANDLING

Error_Responses

All errors follow a consistent response format with a machine-readable error code and human-readable description.

Standard Error Format

{ "success": false, "error": "Human-readable error message", "errorCode": "RESOURCE_NOT_FOUND" }

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Invalid or missing API key
404	Not Found	Token or resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error; try again later
502	Bad Gateway	Upstream service unavailable

// MCP_INTEGRATION

MCP Server

BitMidpoint exposes a Model Context Protocol (MCP) server, enabling AI agents like Claude, Cursor, ChatGPT, and any MCP-compatible client to access crypto price data directly through natural language.

The MCP endpoint is a Streamable HTTP server — no local installation needed. Point your client at the URL and start querying.

Setup

Add BitMidpoint to your MCP client configuration. The config file location depends on your client:

Client	Config File
Cursor	`.cursor/mcp.json` (in your project root)
Claude Desktop	`claude_desktop_config.json`
VS Code (Copilot)	`.vscode/mcp.json`
Any MCP Client	See your client's MCP documentation

Without API Key (30 req/min)

Works immediately — no authentication required:

              
              
              
              mcp.json
            
{
  "mcpServers": {
    "bitmidpoint": {
      "url": "https://bitmidpoint.com/mcp"
    }
  }
}

With API Key (120 req/min)

Add a headers block with your API key. Get a free key from your Account page. The key applies to all tool calls automatically — you never need to pass it in prompts.

              
              
              
              mcp.json
            
{
  "mcpServers": {
    "bitmidpoint": {
      "url": "https://bitmidpoint.com/mcp",
      "headers": {
        "X-API-Key": "cbv_your-key-here"
      }
    }
  }
}

Restart your client (or reload the window in Cursor). BitMidpoint tools will appear automatically.

// MCP_TOOLS

MCP Tools

Four tools are available via the MCP server. AI agents call these automatically based on your prompt — you don't need to specify tool names manually.

TOOL get_all_tokens

Returns all tracked tokens sorted by volume with price spreads, exchange data, and market rank. Equivalent to GET /api/v1/tokens.

No parameters required.

Example prompt: "Show me all available tokens sorted by volume"

TOOL get_token

Returns detailed price and spread data for a specific token. Equivalent to GET /api/v1/tokens/:symbol.

Parameter	Type	Required	Description
`symbol`	string	Yes	Token symbol (BTC, ETH, SOL, XRP)

Example prompt: "What's the current Bitcoin price across exchanges?"

TOOL get_token_history

Returns historical price data for a token over 24 hours, 7 days, or 30 days. Equivalent to GET /api/v1/tokens/:symbol/history.

Parameter	Type	Required	Description
`symbol`	string	Yes	Token symbol (BTC, ETH, SOL)
`range`	string	—	24h, 7d, or 30d (default: 24h)

Example prompt: "Show me ETH price history for the last 7 days"

TOOL get_markets

Returns market overview with average spreads, consensus score, and top 10 arbitrage opportunities. Equivalent to GET /api/v1/markets.

No parameters required.

Example prompt: "What are the best arbitrage opportunities right now?"

Endpoint

The MCP server is available at:

https://bitmidpoint.com/mcp

Protocol: Streamable HTTP (JSON-RPC 2.0 over HTTP POST). No WebSocket or SSE subscription required. Stateless — each request is independent.

GET /tokens

                
                curl_request.sh
              
curl -X GET "https://bitmidpoint.com/api/v1/tokens" \
  -H "X-API-Key: cbv_your-key-here"

GET /tokens/:symbol

                
                curl_request.sh
              
curl -X GET "https://bitmidpoint.com/api/v1/tokens/BTC" \
  -H "X-API-Key: cbv_your-key-here"

GET /tokens/:symbol/history

                
                curl_request.sh
              
curl -X GET "https://bitmidpoint.com/api/v1/tokens/BTC/history?range=7d" \
  -H "X-API-Key: cbv_your-key-here"

GET /markets

                
                curl_request.sh
              
curl -X GET "https://bitmidpoint.com/api/v1/markets" \
  -H "X-API-Key: cbv_your-key-here"

Fetch All Tokens

                
                
                
                index.js
              
const res = await fetch('https://bitmidpoint.com/api/v1/tokens', {
  method: 'GET',
  headers: {
    'X-API-Key': 'cbv_your-key-here',
    'Content-Type': 'application/json'
  }
});

const { data } = await res.json();
console.log(data);

Fetch Single Token

                
                index.js
              
const symbol = 'BTC';
const res = await fetch(`https://bitmidpoint.com/api/v1/tokens/${symbol}`, {
  headers: { 'X-API-Key': 'cbv_your-key-here' }
});

const { data } = await res.json();
console.log(`${data.symbol}: ${data.avgPrice}`);

Fetch Price History

                
                
                
                index.js
              
const res = await fetch('https://bitmidpoint.com/api/v1/tokens/BTC/history?range=7d', {
  headers: { 'X-API-Key': 'cbv_your-key-here' }
});

const { data } = await res.json();
data.forEach(point => {
  console.log(`${point.timestamp}: $${point.avgPrice}`);
});

Fetch All Tokens

                
                main.py
              
import requests

headers = {'X-API-Key': 'cbv_your-key-here'}
response = requests.get('https://bitmidpoint.com/api/v1/tokens', headers=headers)
data = response.json()['data']

for token in data:
    print(f"{token['symbol']}: ${token['avgPrice']}")

Fetch Single Token

                
                main.py
              
import requests

headers = {'X-API-Key': 'cbv_your-key-here'}
response = requests.get('https://bitmidpoint.com/api/v1/tokens/BTC', headers=headers)
token = response.json()['data']

print(f"Spread: {token['spreadPct']}%")

Fetch Price History

                
                
                
                main.py
              
import requests
from datetime import datetime

headers = {'X-API-Key': 'cbv_your-key-here'}
response = requests.get('https://bitmidpoint.com/api/v1/tokens/BTC/history?range=7d', headers=headers)
history = response.json()['data']

for point in history:
    ts = datetime.fromisoformat(point['timestamp'].replace('Z', '+00:00'))
    print(f"{ts}: ${point['avgPrice']}")

Example Response

{ "success": true, "data": [ { "symbol": "BTC", "avgPrice": 45230.50, "spreadPct": 0.782, "totalVolume": 28500000000 } ] }