{
  "openapi": "3.1.0",
  "info": {
    "title": "Bitcompare API",
    "summary": "Crypto rates, coin metadata, prices, market stats, and stablecoin data.",
    "description": "Public REST API powering Bitcompare and the Bitcompare MCP server. Cryptocurrency interest rates (lending, staking, borrowing), coin metadata, aggregated prices, market stats, and stablecoin peg-stability. Every endpoint is also exposed as an MCP tool at https://api.bitcompare.net/mcp.",
    "version": "1.0.0",
    "contact": {
      "name": "Bitcompare API support",
      "email": "info@bitcompare.net",
      "url": "https://docs.bitcompare.net"
    },
    "license": {
      "name": "Commercial",
      "url": "https://bitcompare.net/terms-of-use"
    },
    "termsOfService": "https://bitcompare.net/terms-of-use"
  },
  "servers": [
    {
      "url": "https://api.bitcompare.net",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Developer documentation",
    "url": "https://docs.bitcompare.net"
  },
  "tags": [
    {
      "name": "rates",
      "description": "Interest rate comparison across providers"
    },
    {
      "name": "coins",
      "description": "Coin metadata, market data, and history"
    },
    {
      "name": "prices",
      "description": "Aggregated spot prices from multiple feeds"
    },
    {
      "name": "market",
      "description": "Global market statistics"
    },
    {
      "name": "stablecoins",
      "description": "Stablecoin index + peg-stability data"
    },
    {
      "name": "symbols",
      "description": "Symbol resolution and normalisation"
    },
    {
      "name": "mcp",
      "description": "Model Context Protocol transport"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "ck_live_*",
        "description": "API keys issued from https://pro.bitcompare.net/dashboard/keys. Send as `Authorization: Bearer ck_live_...`."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "example": "INVALID_API_KEY"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Plan rate limit exceeded — see X-RateLimit-* headers and Retry-After",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string"
                    },
                    "code": {
                      "type": "string",
                      "example": "RATE_LIMIT_EXCEEDED"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/rates": {
      "get": {
        "tags": [
          "rates"
        ],
        "operationId": "get_rates",
        "summary": "Get current rates",
        "description": "List current rates across providers, optionally filtered by symbol, category, or provider. Use this to answer \"what is the best yield on BTC right now?\" style questions.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": {
                            "type": "string",
                            "description": "Provider slug, e.g. `nexo`"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Coin symbol, e.g. `btc`"
                          },
                          "category": {
                            "type": "string",
                            "enum": [
                              "savings",
                              "lending",
                              "staking",
                              "borrowing"
                            ],
                            "description": "Product category"
                          },
                          "apy": {
                            "type": "number",
                            "description": "Annual percentage yield as a decimal (0.05 = 5%)"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the most recent rate refresh"
                          }
                        },
                        "required": [
                          "provider",
                          "symbol",
                          "category",
                          "apy"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Matching rate entries"
                    }
                  },
                  "required": [
                    "rates"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": false,
            "description": "Filter by coin symbol (e.g. \"btc\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "btc"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by product category (e.g. \"savings\", \"lending\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "savings"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max results, default 100",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 10
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/rates/{symbol}": {
      "get": {
        "tags": [
          "rates"
        ],
        "operationId": "get_rate_by_symbol",
        "summary": "Get rates for a single symbol",
        "description": "Fetch all provider rates for a specific coin symbol. Optionally filter by category.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "rates": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "provider": {
                            "type": "string",
                            "description": "Provider slug, e.g. `nexo`"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Coin symbol, e.g. `btc`"
                          },
                          "category": {
                            "type": "string",
                            "enum": [
                              "savings",
                              "lending",
                              "staking",
                              "borrowing"
                            ],
                            "description": "Product category"
                          },
                          "apy": {
                            "type": "number",
                            "description": "Annual percentage yield as a decimal (0.05 = 5%)"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the most recent rate refresh"
                          }
                        },
                        "required": [
                          "provider",
                          "symbol",
                          "category",
                          "apy"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Matching rate entries"
                    }
                  },
                  "required": [
                    "rates"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol, e.g. \"btc\" or \"eth\"",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "eth"
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter to a single product category (e.g. \"savings\", \"lending\", \"staking\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "lending"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/rates/{symbol}/history": {
      "get": {
        "tags": [
          "rates"
        ],
        "operationId": "get_rate_history",
        "summary": "Historical rates",
        "description": "Historical rate timeseries for a symbol. Pro plans get up to 5 years; lower plans are clamped server-side.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "provider": {
                      "type": "string"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "timestamp": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the data point"
                          },
                          "value": {
                            "type": "number",
                            "description": "The recorded numeric value"
                          }
                        },
                        "required": [
                          "timestamp",
                          "value"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Time-ordered rate observations (oldest → newest)"
                    }
                  },
                  "required": [
                    "symbol",
                    "points"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "btc"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Days of history. Clamped to the plan limit (7 Free, 1825 Pro).",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 30
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/providers": {
      "get": {
        "tags": [
          "rates"
        ],
        "operationId": "list_providers",
        "summary": "List rate providers",
        "description": "All rate providers, optionally filtered by product category.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "providers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string",
                            "description": "Stable identifier (e.g. `nexo`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Display name"
                          },
                          "categories": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Categories this provider offers"
                          }
                        },
                        "required": [
                          "slug",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "providers"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter to providers that offer this category (e.g. \"savings\", \"lending\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "savings"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins/{coinId}": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "get_coin",
        "summary": "Get coin metadata",
        "description": "Full metadata for a coin: description, links, categories, market data, developer stats.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "Canonical coin ID (e.g. `bitcoin`)"
                    },
                    "symbol": {
                      "type": "string",
                      "description": "Trading symbol (e.g. `btc`)"
                    },
                    "name": {
                      "type": "string",
                      "description": "Human-readable name (e.g. `Bitcoin`)"
                    },
                    "marketCap": {
                      "type": "number",
                      "description": "Market cap in USD"
                    },
                    "rank": {
                      "type": "integer",
                      "description": "Market cap rank (1 = largest)"
                    },
                    "price": {
                      "type": "number",
                      "description": "Current spot price in USD"
                    }
                  },
                  "required": [
                    "id",
                    "symbol",
                    "name"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "coinId",
            "in": "path",
            "required": true,
            "description": "Canonical coin id or slug (e.g. \"bitcoin\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "bitcoin"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "list_coins",
        "summary": "List coins",
        "description": "Paginated list of coins with optional name/symbol search.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coins": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Canonical coin ID (e.g. `bitcoin`)"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Trading symbol (e.g. `btc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name (e.g. `Bitcoin`)"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Market cap rank (1 = largest)"
                          },
                          "price": {
                            "type": "number",
                            "description": "Current spot price in USD"
                          }
                        },
                        "required": [
                          "id",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "coins"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size, default 20",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 10
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search by name or symbol",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "eth"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins/top": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "top_coins",
        "summary": "Top coins by market cap",
        "description": "Top N coins ordered by market capitalisation.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coins": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Canonical coin ID (e.g. `bitcoin`)"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Trading symbol (e.g. `btc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name (e.g. `Bitcoin`)"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Market cap rank (1 = largest)"
                          },
                          "price": {
                            "type": "number",
                            "description": "Current spot price in USD"
                          }
                        },
                        "required": [
                          "id",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "coins"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of coins, default 100",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 10
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins/{coinId}/similar": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "similar_coins",
        "summary": "Similar coins",
        "description": "Coins related to the given coin by category/sector similarity.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coins": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Canonical coin ID (e.g. `bitcoin`)"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Trading symbol (e.g. `btc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name (e.g. `Bitcoin`)"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Market cap rank (1 = largest)"
                          },
                          "price": {
                            "type": "number",
                            "description": "Current spot price in USD"
                          }
                        },
                        "required": [
                          "id",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "coins"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "coinId",
            "in": "path",
            "required": true,
            "description": "Canonical coin id to find related coins for (e.g. \"bitcoin\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "bitcoin"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max related coins to return, default 10",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 5
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins/{coinId}/markets": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "coin_markets",
        "summary": "Markets trading a coin",
        "description": "Exchanges and trading pairs for a coin, with prices and volumes.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "coinId": {
                      "type": "string"
                    },
                    "markets": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "exchange": {
                            "type": "string",
                            "description": "Exchange / venue name"
                          },
                          "pair": {
                            "type": "string",
                            "description": "Trading pair, e.g. `BTC/USDT`"
                          },
                          "price": {
                            "type": "number",
                            "description": "Last traded price"
                          },
                          "volume24h": {
                            "type": "number",
                            "description": "24h trading volume"
                          }
                        },
                        "required": [
                          "exchange",
                          "pair"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "coinId",
                    "markets"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "coinId",
            "in": "path",
            "required": true,
            "description": "Canonical coin id whose markets to fetch (e.g. \"ethereum\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "ethereum"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Max exchange/pair rows to return, default 50",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 20
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/coins/history/{symbol}": {
      "get": {
        "tags": [
          "coins"
        ],
        "operationId": "coin_history",
        "summary": "Historical coin price chart",
        "description": "Historical price timeseries for a coin symbol.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "points": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "timestamp": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the data point"
                          },
                          "value": {
                            "type": "number",
                            "description": "The recorded numeric value"
                          }
                        },
                        "required": [
                          "timestamp",
                          "value"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Price points, oldest → newest"
                    }
                  },
                  "required": [
                    "symbol",
                    "points"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Coin symbol (e.g. \"btc\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "btc"
          },
          {
            "name": "days",
            "in": "query",
            "required": false,
            "description": "Days of history",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 30
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/prices": {
      "get": {
        "tags": [
          "prices"
        ],
        "operationId": "get_price",
        "summary": "Aggregated exchange price",
        "description": "Current aggregated price for one or more symbols, computed from multiple exchange feeds.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "prices": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "symbol": {
                            "type": "string",
                            "description": "Coin symbol queried"
                          },
                          "priceUsd": {
                            "type": "number",
                            "description": "Aggregated USD spot price"
                          },
                          "updatedAt": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the price aggregation"
                          }
                        },
                        "required": [
                          "symbol",
                          "priceUsd"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "prices"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbols",
            "in": "query",
            "required": true,
            "description": "Single symbol or array of symbols (e.g. \"btc\" or [\"btc\",\"eth\"])",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": [
              "btc",
              "eth"
            ]
          },
          {
            "name": "vs",
            "in": "query",
            "required": false,
            "description": "Quote currency, default \"usd\"",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "usd"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/global-stats/summary": {
      "get": {
        "tags": [
          "market"
        ],
        "operationId": "market_summary",
        "summary": "Global market summary",
        "description": "One-call summary of total market cap, 24h volume, BTC/ETH dominance, and recent trend.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "totalMarketCapUsd": {
                      "type": "number",
                      "description": "Combined market cap of all tracked coins"
                    },
                    "volume24hUsd": {
                      "type": "number",
                      "description": "Combined 24h trading volume"
                    },
                    "btcDominance": {
                      "type": "number",
                      "description": "BTC share of total market cap, 0-100"
                    },
                    "ethDominance": {
                      "type": "number",
                      "description": "ETH share of total market cap, 0-100"
                    },
                    "trend24h": {
                      "type": "number",
                      "description": "24h trend as a decimal (0.02 = +2%)"
                    }
                  },
                  "required": [
                    "totalMarketCapUsd",
                    "volume24hUsd",
                    "btcDominance",
                    "ethDominance"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/global-stats/fear-greed": {
      "get": {
        "tags": [
          "market"
        ],
        "operationId": "fear_greed_index",
        "summary": "Fear & Greed index",
        "description": "Current Fear & Greed index value and historical trend.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "value": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 100,
                      "description": "Current index, 0 (extreme fear) to 100 (extreme greed)"
                    },
                    "classification": {
                      "type": "string",
                      "description": "Label, e.g. `Greed`, `Neutral`, `Extreme Fear`"
                    },
                    "updatedAt": {
                      "type": "string"
                    },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "timestamp": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the data point"
                          },
                          "value": {
                            "type": "number",
                            "description": "The recorded numeric value"
                          }
                        },
                        "required": [
                          "timestamp",
                          "value"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Recent trend of the index"
                    }
                  },
                  "required": [
                    "value",
                    "classification"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/global-stats/movers": {
      "get": {
        "tags": [
          "market"
        ],
        "operationId": "top_movers",
        "summary": "Top gainers/losers",
        "description": "Biggest 24h gainers and losers within a rank segment.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "gainers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Canonical coin ID (e.g. `bitcoin`)"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Trading symbol (e.g. `btc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name (e.g. `Bitcoin`)"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Market cap rank (1 = largest)"
                          },
                          "price": {
                            "type": "number",
                            "description": "Current spot price in USD"
                          }
                        },
                        "required": [
                          "id",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Top 24h gainers in the requested segment"
                    },
                    "losers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Canonical coin ID (e.g. `bitcoin`)"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Trading symbol (e.g. `btc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name (e.g. `Bitcoin`)"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "rank": {
                            "type": "integer",
                            "description": "Market cap rank (1 = largest)"
                          },
                          "price": {
                            "type": "number",
                            "description": "Current spot price in USD"
                          }
                        },
                        "required": [
                          "id",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Top 24h losers in the requested segment"
                    }
                  },
                  "required": [
                    "gainers",
                    "losers"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "segment",
            "in": "query",
            "required": false,
            "description": "Rank segment, default \"top100\"",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "top100"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of gainers and losers to return on each side, default 10",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 10
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/stablecoins/index": {
      "get": {
        "tags": [
          "stablecoins"
        ],
        "operationId": "stablecoin_index",
        "summary": "Stablecoin stability leaderboard",
        "description": "Ranked stablecoin leaderboard with stability scores, peg deviation, and market cap.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stablecoins": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "symbol": {
                            "type": "string",
                            "description": "Stablecoin symbol (e.g. `usdc`)"
                          },
                          "name": {
                            "type": "string",
                            "description": "Human-readable name"
                          },
                          "marketCap": {
                            "type": "number",
                            "description": "Market cap in USD"
                          },
                          "pegDeviation": {
                            "type": "number",
                            "description": "Current peg deviation from target (typically $1.00) in basis points"
                          },
                          "stabilityScore": {
                            "type": "number",
                            "description": "Stability score 0-100, higher is more stable"
                          }
                        },
                        "required": [
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Ranked stablecoin leaderboard"
                    }
                  },
                  "required": [
                    "stablecoins"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Default 50",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": 20
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/stablecoins/{symbol}/peg-stability": {
      "get": {
        "tags": [
          "stablecoins"
        ],
        "operationId": "stablecoin_peg_stability",
        "summary": "Stablecoin peg stability",
        "description": "Peg deviation history and stability stats for a stablecoin.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "pegTarget": {
                      "type": "number",
                      "description": "Target peg in USD (typically 1.0)"
                    },
                    "deviation": {
                      "type": "number",
                      "description": "Current peg deviation in basis points"
                    },
                    "history": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "timestamp": {
                            "type": "string",
                            "description": "ISO-8601 timestamp of the data point"
                          },
                          "value": {
                            "type": "number",
                            "description": "The recorded numeric value"
                          }
                        },
                        "required": [
                          "timestamp",
                          "value"
                        ],
                        "additionalProperties": true
                      },
                      "description": "Recent peg deviation samples"
                    }
                  },
                  "required": [
                    "symbol",
                    "pegTarget",
                    "deviation",
                    "history"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "path",
            "required": true,
            "description": "Stablecoin symbol (e.g. \"usdt\", \"usdc\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "usdc"
          },
          {
            "name": "window",
            "in": "query",
            "required": false,
            "description": "Stability window, default \"30d\"",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "30d"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/symbols/resolve": {
      "get": {
        "tags": [
          "symbols"
        ],
        "operationId": "resolve_symbol",
        "summary": "Resolve symbol to canonical coin",
        "description": "Map an exchange-specific or ambiguous symbol to bitcompare's canonical coin id. Useful when an exchange uses a non-standard ticker.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "input": {
                      "type": "string",
                      "description": "The raw symbol that was queried"
                    },
                    "coinId": {
                      "type": "string",
                      "description": "Canonical Bitcompare coin ID"
                    },
                    "symbol": {
                      "type": "string",
                      "description": "Canonical symbol"
                    },
                    "name": {
                      "type": "string",
                      "description": "Coin display name"
                    }
                  },
                  "required": [
                    "input",
                    "coinId",
                    "symbol",
                    "name"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "symbol",
            "in": "query",
            "required": true,
            "description": "Exchange-specific or ambiguous symbol",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "xbt"
          },
          {
            "name": "context",
            "in": "query",
            "required": false,
            "description": "Source exchange or quote currency to disambiguate (e.g. \"kraken\", \"binance\")",
            "schema": {
              "type": "object",
              "properties": {},
              "additionalProperties": false
            },
            "example": "kraken"
          }
        ],
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/api/v1/symbols/resolve/batch": {
      "post": {
        "tags": [
          "symbols"
        ],
        "operationId": "resolve_symbols_batch",
        "summary": "Batch resolve symbols",
        "description": "Resolve up to 100 symbols in a single request. Requires a plan with bulk endpoints enabled.",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resolved": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "input": {
                            "type": "string",
                            "description": "The raw symbol that was queried"
                          },
                          "coinId": {
                            "type": "string",
                            "description": "Canonical Bitcompare coin ID"
                          },
                          "symbol": {
                            "type": "string",
                            "description": "Canonical symbol"
                          },
                          "name": {
                            "type": "string",
                            "description": "Coin display name"
                          }
                        },
                        "required": [
                          "input",
                          "coinId",
                          "symbol",
                          "name"
                        ],
                        "additionalProperties": true
                      }
                    }
                  },
                  "required": [
                    "resolved"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "description": "Plan rate limit exceeded",
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "symbols": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 100,
                    "description": "Up to 100 symbols to resolve in a single request"
                  },
                  "context": {
                    "type": "string",
                    "description": "Source exchange or quote currency applied to every input symbol"
                  }
                },
                "required": [
                  "symbols"
                ],
                "additionalProperties": true
              },
              "example": {
                "symbols": [
                  "xbt",
                  "weth",
                  "wbtc"
                ],
                "context": "kraken"
              }
            }
          }
        },
        "x-mcp-annotations": {
          "readOnlyHint": true,
          "destructiveHint": false,
          "idempotentHint": true,
          "openWorldHint": true
        }
      }
    },
    "/mcp": {
      "post": {
        "tags": [
          "mcp"
        ],
        "operationId": "mcpEndpoint",
        "summary": "Model Context Protocol endpoint",
        "description": "Streamable HTTP MCP endpoint. Implements the MCP spec; exposes all REST endpoints as named tools for AI agents. See https://api.bitcompare.net/mcp/tools.json for the live tool catalog and https://api.bitcompare.net/.well-known/mcp.json for the server descriptor.",
        "responses": {
          "200": {
            "description": "MCP response (JSON-RPC over Streamable HTTP)"
          }
        }
      }
    }
  }
}