{
  "id": "surf.exchange.candles",
  "object": "tool",
  "name": "Exchange Historical Candles",
  "summary": "Returns persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market.",
  "description": "Returns persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market. Intervals: 5m, 4h, and 1w. bitFlyer is currently reliable for weekly (1w) OHLCV only. Pagination: use from/to to bound the time range and limit to cap returned candles. Results are ordered newest first. Synthetic candles: include_synthetic=true by default, so carry-forward candles for no-trade intervals are included for continuous charts. Set include_synthetic=false for raw exchange-only candles. Sparse Korbit markets may rely on synthetic rows to keep charts continuous.\n\nRaw surf#exchange/candles endpoint: input is { body, queryParams, pathParams } as the provider documents them (https://docs.asksurf.ai/data-api/exchange/candles).",
  "category": "lookup",
  "hosted_by": "Surf",
  "runtime": "partner",
  "side_effects": false,
  "status": "live",
  "credits": 0,
  "price": null,
  "providers": [
    {
      "id": "surf",
      "name": "Surf",
      "price": null,
      "own_key_only": true
    }
  ],
  "mcp_name": "surf_exchange_candles",
  "input_schema": {
    "type": "object",
    "properties": {
      "queryParams": {
        "type": "object",
        "properties": {
          "exchange": {
            "type": "string",
            "enum": [
              "bithumb",
              "upbit",
              "hashkey",
              "bitflyer",
              "coinone",
              "korbit"
            ],
            "description": "Exchange identifier. Example: bithumb."
          },
          "pair": {
            "type": "string",
            "minLength": 1,
            "description": "Trading pair in base/quote form, e.g. BTC/KRW. Example: BTC/KRW."
          },
          "interval": {
            "default": "5m",
            "type": "string",
            "enum": [
              "5m",
              "4h",
              "1w"
            ],
            "description": "Candle interval. Example: 5m. Defaults to \"5m\"."
          },
          "from": {
            "type": "string",
            "minLength": 1,
            "description": "Start of time range. Accepts Unix seconds or date string. Example: 2026-06-24T09:00:00Z."
          },
          "to": {
            "type": "string",
            "minLength": 1,
            "description": "End of time range. Accepts Unix seconds or date string. Example: 2026-06-24T10:00:00Z."
          },
          "include_synthetic": {
            "default": true,
            "type": "boolean",
            "description": "Whether to include carry-forward candles for no-trade intervals. Defaults to true for continuous charts; set false for raw exchange-only candles. Example: True. Defaults to true."
          },
          "limit": {
            "default": 100,
            "type": "integer",
            "minimum": 1,
            "maximum": 300,
            "description": "Max number of candles to return. Weekly candles allow up to 300 rows for a 5-year chart; intraday intervals are capped at 100. Example: 100. Defaults to 100."
          },
          "offset": {
            "default": 0,
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Pagination offset. Example: 0. Defaults to 0."
          }
        },
        "required": [
          "exchange",
          "pair"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "queryParams"
    ],
    "additionalProperties": false
  },
  "kind": "endpoint"
}