Funding Finder — API Documentation

Overview

The Funding Finder API exposes cross-exchange perpetual funding-rate data and arbitrage opportunities. All responses are JSON. No authentication required for the free tier. Rate limited to 60 req/min/IP.

Base URL: http://178.104.60.252:8083

Coverage: Binance, Bybit, OKX, Bitget, MEXC, Hyperliquid (~3000 USDT-margined perpetuals).

/api/health /api/funding/current /api/funding/arb /api/funding/extremes /api/funding/symbol/<base> /api/funding/history/<base> /api/funding/sentiment /api/funding/divergence /api/funding/heatmap

Health free

GET /api/health

Returns the overall service status, per-exchange freshness, and stale-exchange list. Use this for monitoring or to check whether to trust the data before making decisions.

curl http://178.104.60.252:8083/api/health

Response:

{
  "ok": true,
  "status": "ok",                 // ok | degraded | down
  "data_age_seconds": 4,
  "stale_threshold_seconds": 900,
  "exchanges": [
    {"exchange": "binance", "symbols": 670, "age_seconds": 4, "status": "ok"},
    {"exchange": "bybit", "symbols": 544, "age_seconds": 5, "status": "ok"},
    ...
  ],
  "stale_exchanges": [],
  "total_rows": 41265
}

Current funding rates free

GET /api/funding/current

Returns the latest funding rate per (exchange, symbol). Includes the per-symbol funding interval, mark price, and 24h volume in USD.

curl http://178.104.60.252:8083/api/funding/current

Response:

{
  "fetched_at": 1775597628,
  "count": 2798,
  "rows": [
    {
      "exchange": "binance",
      "symbol": "BTCUSDT",
      "base": "BTC",
      "funding_rate": 0.00004,
      "funding_rate_pct": 0.004,
      "annualized_pct": 4.38,
      "funding_interval_hours": 8,
      "next_funding_time": 1775606400,
      "mark_price": 69673.4,
      "volume_24h_usd": 3627998508.75
    },
    ...
  ]
}

Arbitrage opportunities free

GET /api/funding/arb

The main endpoint. For each base coin available on at least 2 exchanges with sufficient liquidity, computes the cross-exchange spread between the lowest and highest funding rates, annualized correctly per-symbol.

Query parameters

name	type	default	description
`min_yield`	float	`0`	Minimum annualized yield (%) to include
`min_volume`	float	`1000000`	Minimum 24h volume in USD on both legs
`limit`	int	`100`	Max rows returned (sorted by yield desc)

curl 'http://178.104.60.252:8083/api/funding/arb?min_yield=10&min_volume=10000000&limit=10'

Response:

{
  "fetched_at": 1775597628,
  "count": 68,
  "opportunities": [
    {
      "base": "RED",
      "long_exchange": "mexc",
      "long_symbol": "REDUSDT",
      "long_rate_pct": -1.07,
      "long_volume_24h_usd": 16400000,
      "short_exchange": "bybit",
      "short_symbol": "REDUSDT",
      "short_rate_pct": -0.03,
      "short_volume_24h_usd": 215000000,
      "spread_pct": 1.04,
      "annualized_yield_pct": 2289.7,
      "next_funding_long": 1775606400,
      "next_funding_short": 1775606400,
      "exchanges_count": 4
    },
    ...
  ]
}

Strategy reminder

Long the perp on long_exchange, short the perp on short_exchange. Both legs are perpetual futures, no spot, beta-neutral. Capture the funding spread until convergence. Always verify that the spread persists and that order book depth is sufficient before sizing.

Extreme rates free

GET /api/funding/extremes?n=20

Returns the most positive and most negative funding rates (regardless of cross-exchange opportunities). Useful for spotting funding spikes on a single venue.

Per-symbol snapshot free

GET /api/funding/symbol/<base>

Returns the latest funding rate for a base coin across all exchanges that list it. Useful for quickly checking BTC, ETH, or any specific asset.

curl http://178.104.60.252:8083/api/funding/symbol/BTC

Funding rate history free up to 24h · paid up to 720h

GET /api/funding/history/<base>

Returns a time series of funding rates for a base coin, across all exchanges or filtered to one. Granularity is the collector loop interval (5 minutes).

Query parameters

name	type	default	description
`hours`	int	`168`	How many hours of history to return. Capped at 720 (30 days).
`exchange`	string	—	Optional. Filter to a single exchange.

curl 'http://178.104.60.252:8083/api/funding/history/BTC?hours=24&exchange=binance'

Version & metadata free

GET /api/version

Returns the running service version, build timestamp, list of supported exchanges, and tier names. Useful for monitoring and version drift checks.

Prometheus metrics free

GET /metrics

Plain-text Prometheus exposition format. Includes funding_finder_total_rows, funding_finder_data_age_seconds, funding_finder_exchange_symbols per exchange, and funding_finder_endpoint_hits per endpoint. No auth required (intended for internal scraping by Prometheus or similar).

Usage stats free

GET /api/usage

Returns the in-memory request count per endpoint since the API process started. Counts reset on restart. Useful for traffic profiling without a separate analytics stack.

Daily summary free

GET /api/summary

One-call view of the most actionable data: top 5 cross-exchange arbitrage opportunities (vol ≥ $10M), sentiment for BTC/ETH/SOL with interpretation (overheated/neutral/fearful), and the most positive/negative funding rates across the universe.

Use this for daily Telegram bots, content generation, or as a single-call dashboard backend.

By volume free

GET /api/funding/by_volume?limit=50

Ranks every base coin by total cross-exchange 24h volume in USD. Useful for liquidity discovery: which coins are actually traded vs which are listed but inactive. Each row also includes the funding rate spread (min/max) across the venues that list the coin.

Sentiment free

GET /api/funding/sentiment?bases=BTC,ETH,SOL

Lightweight one-call read of market positioning. Returns the average annualized funding rate per base coin (across all venues that list it) plus a coarse label (overheated / neutral / fearful). Useful for status widgets, Twitter bots, or any consumer that doesn't need the full snapshot.

{
  "bases": ["BTC", "ETH", "SOL"],
  "sentiment": {
    "BTC": { "avg_annualized_pct": 4.74, "venues": 18, "interpretation": "neutral" },
    "ETH": { "avg_annualized_pct": 5.48, "venues": 18, "interpretation": "neutral" },
    "SOL": { "avg_annualized_pct": 13.33, "venues": 18, "interpretation": "neutral" }
  }
}

Divergence free

GET /api/funding/divergence?min_venues=3&min_volume=1000000&limit=50

For every base coin available on at least min_venues exchanges, computes the standard deviation of annualized funding rates across venues. Sorted by stddev descending — highest disagreement first.

High stddev means the market disagrees about how to price this perp. Different from /arb: spread tells you the magnitude of the single best pair, but stddev tells you whether the dislocation is structural (multiple venues offside) or just one outlier. High spread + high stddev = real opportunity. High spread + low stddev = single venue weirdness.

Heatmap free

GET /api/funding/heatmap?top=25&min_volume=0

Returns a base × exchange matrix of annualized funding rates, suitable for rendering a heatmap. Cells with no data (or filtered out by min_volume) are returned as null. Pass ?bases=BTC,ETH,SOL to override the auto-selected top-N. The matching frontend lives at /heatmap.

By exchange free

GET /api/funding/by_exchange/<exchange>?sort=annualized

All current funding rates for a specific venue. Useful when you only trade on one exchange and want to scan its funding rates without the noise of cross-exchange comparisons.

Sort options: funding_rate, volume, annualized, symbol.

Best pair free

GET /api/funding/best_pair/<ex_a>/<ex_b>

Restricts the cross-exchange arbitrage scan to a specific venue pair. Use this if you only have margin on 2 exchanges (e.g. /api/funding/best_pair/binance/bybit) and want to focus on opportunities you can actually execute without opening a third account.

Telegram alerts paid tier

Get a Telegram message every time a cross-exchange arbitrage opportunity matches your criteria. Requires a Trader or Pro tier API key. Free tier returns 403 on these endpoints.

POST /api/alerts/create

Body (JSON):

{
  "base": "BTC",                  // optional, null = any coin
  "min_yield_pct": 100,           // required, in % annualized
  "min_volume_usd": 5000000,      // required, USD on both legs
  "exchanges": "binance,bybit",   // optional CSV filter
  "telegram_chat_id": "123456",   // required (your Telegram user ID)
  "cooldown_seconds": 3600        // optional, default 1h
}

Response: {"id": 42, "created": true}

GET /api/alerts/list

Returns all alerts for your API key.

DELETE /api/alerts/delete/<id>

Removes an alert. Requires owner match.

How alerts work

A background worker scans the latest funding rates every 60 seconds. For each active alert it checks whether any cross-exchange opportunity matches the criteria. On match, the worker sends a Telegram message via the bot API and records the trigger time. The cooldown prevents the same alert from re-firing within the cooldown window.

Sample alert message:

Funding Finder alert

`RED` cross-exchange opportunity:
- long `binance` (vol $96.5M)
- short `bybit` (vol $215.0M)
- spread: 1.0539% per period
- annualized: 2308% APY

Cooldown: 3600s. Reply STOP to disable.

CSV exports free

Two endpoints serve CSV downloads of the same data as their JSON counterparts. Useful for spreadsheet imports.

GET /api/funding/current.csv

All current funding rates as CSV. ~6,840 rows.

GET /api/funding/arb.csv

Arbitrage opportunities as CSV. Same query params as /api/funding/arb.

OpenAPI specification free

Machine-readable API spec for code generation, mock servers, and contract testing.

GET /openapi.yaml

GET /openapi.json

Both serve the same OpenAPI 3.1 spec, one in YAML and one in JSON. Compatible with Swagger UI, Postman, openapi-generator, etc.

Errors

code	meaning
`200`	OK
`404`	Endpoint or resource not found (e.g. `/api/funding/symbol/UNKNOWN` when there's no data)
`429`	Rate limit exceeded (60 req/min/IP on the free tier). Wait a minute and retry.
`5xx`	Server error. Check `/api/health` and retry.

Code examples

Python — top 10 opportunities

import requests
r = requests.get("http://178.104.60.252:8083/api/funding/arb",
                 params={"min_yield": 10, "min_volume": 10_000_000, "limit": 10})
for o in r.json()["opportunities"]:
    print(f"{o['base']:8} long {o['long_exchange']:12} short {o['short_exchange']:12} APY {o['annualized_yield_pct']:>+8.1f}%")

Bash — alert on opportunities above 100% APY

curl -s 'http://178.104.60.252:8083/api/funding/arb?min_yield=100&min_volume=20000000' \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'{d[\"count\"]} live opportunities above 100% APY')"