K-line Data

Futures K-line query service for historical candlestick data.

K-line Return Format

All K-line endpoints return a 2D array. Each K-line is an array of 12 elements:

Index	Field	Type	Description
[0]	openTime	integer	Open timestamp (milliseconds)
[1]	closeTime	integer	Close timestamp (milliseconds)
[2]	open	string	Open price
[3]	high	string	High price
[4]	low	string	Low price
[5]	close	string	Close price
[6]	volume	string	Volume
[7]	quoteVolume	string	Turnover
[8]	trades	integer	Number of trades
[9]	takerBuyBaseVolume	string	Taker buy volume
[10]	takerBuyQuoteVolume	string	Taker buy turnover
[11]	isClosed	boolean	Whether the candle is closed

Returned data is sorted in descending time order (latest first), including the current unclosed K-line.

Supported Time Intervals (interval)

1s · 1m · 3m · 5m · 15m · 30m · 1h · 2h · 4h · 6h · 8h · 12h · 1d · 3d · 1w · 1M

---

Query K-line Data

Query historical K-line data for a single futures trading pair. Two mutually exclusive modes are supported:

1. Query by quantity: pass only symbol + interval + limit to return the latest limit K-lines.
2. Query by time range: pass symbol + interval + start_time + end_time to return all K-lines within the time range.

⚠️ The limit parameter is mutually exclusive with start_time / end_time and cannot be used together.

API Information

• Method: GET
• Path: /fapi/v1/klines

Request Parameters

Parameter	Location	Type	Required	Description
symbol	query	string	Yes	Trading pair
interval	query	string	Yes	Time interval (see table above)
start_time	query	integer	No	Start timestamp (milliseconds). Must be used with end_time and is mutually exclusive with limit
end_time	query	integer	No	End timestamp (milliseconds). Must be used with start_time and is mutually exclusive with limit
limit	query	integer	No	Return latest N records, default 500, max 1500. Mutually exclusive with start_time / end_time

Request Example

# By quantity
GET /fapi/v1/klines?symbol=BTC_USDT&interval=1m&limit=100

# By time range
GET /fapi/v1/klines?symbol=BTC_USDT&interval=1h&start_time=1704067200000&end_time=1704153600000

Success Response

Returns a 2D array. Each K-line has 12 elements. See "K-line Return Format".

Error Response

The HTTP status code is always 200. Errors are distinguished by the code field:

• 6000-6999: Client errors
• 7000-7999: Server errors

{
  "code": 6001,
  "message": "invalid interval"
}

Response Example

[
  [
    1704153600000,
    1704153659999,
    "42150.50",
    "42180.00",
    "42140.00",
    "42165.30",
    "125.45",
    "5289456.75",
    2580,
    "68.20",
    "2876543.21",
    false
  ]
]

---

Batch Query K-line Data

Query the latest K-line data for multiple futures trading pairs at once. All trading pairs use the same time interval and limit parameter.

API Information

• Method: GET
• Path: /fapi/v1/klines/batch

Request Parameters

Parameter	Location	Type	Required	Description
symbols	query	string	Yes	Trading pair list, comma-separated, max 20
interval	query	string	Yes	Time interval (see table above)
limit	query	integer	No	Latest N records returned for each trading pair, default 500, max 1500

Request Example

GET /fapi/v1/klines/batch?symbols=BTC_USDT,ETH_USDT&interval=1m&limit=100

Response Fields

Returns a JSON object:

• key: Trading pair name
• value: 2D K-line array of that trading pair (same format as the single-pair endpoint)

K-lines for each trading pair are sorted in descending time order (latest first), including the current unclosed K-line.

Response Example

{
  "BTC_USDT": [
    [1704153600000, 1704153659999, "42150.50", "42180.00", "42140.00", "42165.30", "125.45", "5289456.75", 2580, "68.20", "2876543.21", false]
  ],
  "ETH_USDT": [
    [1704153600000, 1704153659999, "2250.10", "2255.80", "2248.00", "2252.30", "980.50", "2208756.10", 1850, "520.10", "1172345.60", false]
  ]
}