> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nefariouslabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Funding Rates

> Endpoints pour acceder aux funding rates des contrats perpetuels

## GET /api/funding-rates

Recupere les funding rates actuels pour un symbole, agreges depuis plusieurs exchanges.

### Parametres

<ParamField query="symbol" type="string" required>
  Symbole de l'actif (ex: `BTC`, `ETH`, `SOL`). Case insensitive.
</ParamField>

<ParamField query="exchange" type="string">
  Filtre par exchange : `binance`, `bybit`, `okx`, `deribit`, `hyperliquid`
</ParamField>

<ParamField query="quote" type="string">
  Filtre par devise de cotation (`USDT`, `USDC`, `USD`).
</ParamField>

### Reponse

<ResponseField name="data" type="FundingRate[]">
  Tableau des funding rates par exchange

  <Expandable title="FundingRate">
    <ResponseField name="symbol" type="string">
      Symbole normalise (`BTC`, `ETH`, etc.)
    </ResponseField>

    <ResponseField name="rawTicker" type="string">
      Ticker original de l'exchange (`BTCUSDT`, `BTC-PERPETUAL`)
    </ResponseField>

    <ResponseField name="exchange" type="string">
      Nom de l'exchange
    </ResponseField>

    <ResponseField name="rate" type="number">
      Taux de funding (0.0001 = 0.01%)
    </ResponseField>

    <ResponseField name="fundingTime" type="string">
      Timestamp du funding (ISO 8601)
    </ResponseField>

    <ResponseField name="intervalHours" type="number">
      Intervalle de funding en heures (1, 4, ou 8)
    </ResponseField>

    <ResponseField name="markPrice" type="number | null">
      Prix mark du contrat
    </ResponseField>

    <ResponseField name="indexPrice" type="number | null">
      Prix index (spot)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "symbol": "BTC",
        "rawTicker": "BTCUSDT",
        "exchange": "binance",
        "rate": 0.0001,
        "fundingTime": "2024-01-15T08:00:00.000Z",
        "intervalHours": 8,
        "markPrice": 42500.5,
        "indexPrice": 42498.25
      },
      {
        "symbol": "BTC",
        "rawTicker": "BTCUSDT",
        "exchange": "bybit",
        "rate": 0.00012,
        "fundingTime": "2024-01-15T08:00:00.000Z",
        "intervalHours": 8,
        "markPrice": 42501.2,
        "indexPrice": 42499.0
      }
    ]
  }
  ```
</ResponseExample>

### Exemples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.nefariouslabs.dev/api/funding-rates?symbol=BTC"
  ```

  ```bash Filtrer par exchange theme={null}
  curl "https://api.nefariouslabs.dev/api/funding-rates?symbol=ETH&exchange=binance"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.nefariouslabs.dev/api/funding-rates?symbol=BTC"
  );
  const { data } = await response.json();

  // Trouver le taux le plus eleve
  const maxRate = data.reduce((max, item) =>
    item.rate > max.rate ? item : max
  );
  console.log(`Taux max: ${maxRate.rate} sur ${maxRate.exchange}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.nefariouslabs.dev/api/funding-rates",
      params={"symbol": "BTC"}
  )
  data = response.json()["data"]

  # Calculer le taux moyen
  avg_rate = sum(item["rate"] for item in data) / len(data)
  print(f"Taux moyen: {avg_rate:.6f}")
  ```
</CodeGroup>

***

## GET /api/funding-rates/history

Recupere l'historique des funding rates pour un symbole.

### Parametres

<ParamField query="symbol" type="string" required>
  Symbole de l'actif (ex: `BTC`, `ETH`, `SOL`). Case insensitive.
</ParamField>

<ParamField query="exchange" type="string">
  Filtre par exchange : `binance`, `bybit`, `okx`, `deribit`, `hyperliquid`
</ParamField>

<ParamField query="from" type="string">
  Date de debut (ISO 8601). Ex: `2024-01-01T00:00:00Z`
</ParamField>

<ParamField query="to" type="string">
  Date de fin (ISO 8601). Ex: `2024-01-31T23:59:59Z`
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Nombre de resultats (max: 1000)
</ParamField>

### Reponse

<ResponseField name="data" type="FundingRate[]">
  Tableau des funding rates historiques, tries par date decroissante
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "symbol": "ETH",
        "rawTicker": "ETHUSDT",
        "exchange": "binance",
        "rate": 0.00015,
        "fundingTime": "2024-01-15T16:00:00.000Z",
        "intervalHours": 8,
        "markPrice": 2450.75,
        "indexPrice": 2449.5
      },
      {
        "symbol": "ETH",
        "rawTicker": "ETHUSDT",
        "exchange": "binance",
        "rate": 0.00012,
        "fundingTime": "2024-01-15T08:00:00.000Z",
        "intervalHours": 8,
        "markPrice": 2445.25,
        "indexPrice": 2444.0
      }
    ]
  }
  ```
</ResponseExample>

### Exemples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.nefariouslabs.dev/api/funding-rates/history?symbol=ETH&limit=50"
  ```

  ```bash Plage de dates theme={null}
  curl "https://api.nefariouslabs.dev/api/funding-rates/history?symbol=BTC&exchange=binance&from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.nefariouslabs.dev/api/funding-rates/history?" +
    new URLSearchParams({
      symbol: "BTC",
      exchange: "binance",
      from: "2024-01-01T00:00:00Z",
      limit: "100"
    })
  );
  const { data } = await response.json();

  // Analyser l'evolution des taux
  const rates = data.map(item => item.rate);
  const avgRate = rates.reduce((a, b) => a + b, 0) / rates.length;
  ```

  ```python Python theme={null}
  import requests
  from datetime import datetime, timedelta

  # Historique des 7 derniers jours
  from_date = (datetime.utcnow() - timedelta(days=7)).isoformat() + "Z"

  response = requests.get(
      "https://api.nefariouslabs.dev/api/funding-rates/history",
      params={
          "symbol": "BTC",
          "exchange": "binance",
          "from": from_date,
          "limit": 100
      }
  )
  data = response.json()["data"]
  ```
</CodeGroup>

***

## GET /api/exchanges

Liste les exchanges disponibles avec leur statut.

### Reponse

<ResponseField name="data" type="Exchange[]">
  Tableau des exchanges

  <Expandable title="Exchange">
    <ResponseField name="id" type="string">
      Identifiant de l'exchange
    </ResponseField>

    <ResponseField name="name" type="string">
      Nom d'affichage
    </ResponseField>

    <ResponseField name="defaultIntervalHours" type="number">
      Intervalle de funding par defaut (heures)
    </ResponseField>

    <ResponseField name="symbolCount" type="integer">
      Nombre de symboles disponibles
    </ResponseField>

    <ResponseField name="isActive" type="boolean">
      Statut de l'exchange
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "binance",
        "name": "Binance",
        "defaultIntervalHours": 8,
        "symbolCount": 245,
        "isActive": true
      },
      {
        "id": "bybit",
        "name": "Bybit",
        "defaultIntervalHours": 8,
        "symbolCount": 198,
        "isActive": true
      },
      {
        "id": "hyperliquid",
        "name": "Hyperliquid",
        "defaultIntervalHours": 1,
        "symbolCount": 142,
        "isActive": true
      }
    ]
  }
  ```
</ResponseExample>

### Exemple

```bash theme={null}
curl "https://api.nefariouslabs.dev/api/exchanges"
```

***

## GET /health

Verifie la disponibilite du service.

### Reponse

<ResponseField name="status" type="string">
  Statut du service : `healthy`, `degraded`, ou `unhealthy`
</ResponseField>

<ResponseField name="timestamp" type="string">
  Timestamp du check (ISO 8601)
</ResponseField>

<ResponseField name="exchanges" type="ExchangeHealth[]">
  Statut par exchange

  <Expandable title="ExchangeHealth">
    <ResponseField name="exchange" type="string">
      Nom de l'exchange
    </ResponseField>

    <ResponseField name="status" type="string">
      Statut : `healthy`, `stale`, ou `unknown`
    </ResponseField>

    <ResponseField name="ageMinutes" type="integer | null">
      Age des donnees en minutes
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "status": "healthy",
    "timestamp": "2024-01-15T16:10:00.000Z",
    "exchanges": [
      {
        "exchange": "binance",
        "status": "healthy",
        "ageMinutes": 5
      },
      {
        "exchange": "bybit",
        "status": "healthy",
        "ageMinutes": 5
      }
    ]
  }
  ```
</ResponseExample>

### Exemple

```bash theme={null}
curl "https://api.nefariouslabs.dev/health"
```