`GET /v1/futures/top`

Updated November 2026

What does GET /v1/futures/top do?

Contracts ranked by one column on the latest complete bucket, on one venue or across every venue your plan reaches. Ranks futures contracts by a single column, for example the funding rate or open interest value, on the latest complete bucket at your plan’s granularity.

Filter by exchange, by baseAsset and by contractType (perpetual or dated). With baseAsset and no exchange, the same coin is listed on every venue side by side: the cross-venue funding table.

Each venue quotes funding per its own interval (1, 4 or 8 hours), so a cross-venue funding ranking compares rates on different intervals unless you filter them.

Authentication

API key required. Set $BF to the API base and pass your key in $BLACKFORGE_API_KEY.

Parameters

Query parameters for /v1/futures/top
Name	Type	Required	Description
`metric`	string	Yes	The plottable futures column to rank contracts by, e.g. fundingRate, openInterestValue, quoteVolume.
`exchange`	string	No	Futures venue: binance, bitget, bybit, gate, kucoin, mexc, okx. Omitted means every futures venue your plan includes.
`baseAsset`	string	No	Only contracts on this base asset (normalised across venues, so BTC also matches kucoin XBT contracts). With no exchange, ranks the same coin across every venue.
`contractType`	string (perpetual \| dated)	No	Only perpetual contracts (no expiry, funded) or only dated delivery contracts. Omitted means both.
`order`	string (desc \| asc)	No	desc lists the highest values first, asc the lowest.
`limit`	number	No	How many contracts to return, 1 to 100. Each counts as one row.

Parameter shapes from the live OpenAPI document.

Example request

curl -H "x-api-key: $BLACKFORGE_API_KEY" \
  "$BF/v1/futures/top?metric=fundingRate&baseAsset=BTC&contractType=perpetual&order=desc&limit=10"

Example response

Real response, captured 2026-11-09 (trimmed for reading; values move every window)

{
  "metric": "fundingRate",
  "interval": "1m",
  "ts": 1794232500000,
  "order": "desc",
  "rows": [
    {
      "exchange": "kucoin",
      "symbol": "XBTUSDCM",
      "baseAsset": "BTC",
      "value": 0.0003
    },
    {
      "exchange": "binance",
      "symbol": "BTCU",
      "baseAsset": "BTC",
      "value": 0.0001
    },
    {
      "exchange": "binance",
      "symbol": "BTCUSD1",
      "baseAsset": "BTC",
      "value": 0.0001
    },
    {
      "exchange": "binance",
      "symbol": "BTCUSDT",
      "baseAsset": "BTC",
      "value": 0.0001
    },
    {
      "exchange": "mexc",
      "symbol": "BTC_USDT",
      "baseAsset": "BTC",
      "value": 0.0001
    },
    {
      "exchange": "kucoin",
      "symbol": "XBTUSDTM",
      "baseAsset": "BTC",
      "value": 0.000099
    },
    {
      "exchange": "bitget",
      "symbol": "BTCUSDT",
      "baseAsset": "BTC",
      "value": 0.00008
    },
    {
      "exchange": "bybit",
      "symbol": "BTCPERP",
      "baseAsset": "BTC",
      "value": 0.00007727
    },
    {
      "exchange": "bybit",
      "symbol": "BTCUSDT",
      "baseAsset": "BTC",
      "value": 0.00006904
    },
    {
      "exchange": "gate",
      "symbol": "BTC_USDT",
      "baseAsset": "BTC",
      "value": 0.000055
    }
  ]
}

Returns

A JSON object with the metric, interval, ts of the ranked bucket, order, and rows: each with exchange, symbol, baseAsset and value. At most 100 rows.

Responses and errors

Status codes for /v1/futures/top
Status	When
`400`	The metric is unknown or not a number, or limit is out of range.
`401`	The x-api-key header is missing or not a valid key.
`402`	No key and no x402 payment: the pay-per-call challenge is returned.
`403`	The venue or the column is not on your plan.

Columns it returns

Every futures column, its unit, the plan it opens on and the venues that publish it are on the futures data page, with the limits of each venue’s data.

← All endpoints · How the data is measured · Pricing

GET /v1/futures/top