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

# Markets API

> Trading pairs, tickers, and exchange availability

# Markets API

The Markets API provides aggregated market data across supported exchanges, including:

* Trading pairs available on each exchange (spot + perps)
* Current price and 24h change from CoinGecko (per quote currency)
* Per-pair 24h volume aggregated across listing exchanges via CCXT `fetch_tickers`
* Exchange capability information

## Data Sources

| Data                | Source                              | Cache TTL  |
| ------------------- | ----------------------------------- | ---------- |
| Symbol availability | CCXT `load_markets()`               | 4 hours    |
| Price, 24h change   | CoinGecko API (per `vs_currency`)   | 60 seconds |
| Per-pair volume     | CCXT `fetch_tickers()` per exchange | 60 seconds |
| Coin ID mapping     | CoinGecko `/coins/list`             | 24 hours   |

`volume_24h_usd` on each symbol is the **per-pair** 24h volume, the sum of
`quoteVolume` from each listing exchange's ticker for that exact pair,
converted to USD via FX rates anchored on BTC's price. So `BTC/USDT` and
`BTC/EUR` have different volumes, reflecting their actual pair-level
liquidity rather than BTC's total cross-pair volume.

## Supported Exchanges

| Exchange    | Spot | Perp |
| ----------- | ---- | ---- |
| Binance     | Yes  | Yes  |
| Bybit       | Yes  | Yes  |
| Gate.io     | Yes  | Yes  |
| Kraken      | Yes  | Yes  |
| OKX         | Yes  | Yes  |
| Hyperliquid | No   | Yes  |

## Authentication

All endpoints require authentication via an API key. Include the `X-API-Key` header in your requests:

```bash theme={null}
X-API-Key: ak_xxxxxxxxxxxxxxxxxxxx
```

| Endpoint             | Required Roles        |
| -------------------- | --------------------- |
| GET /symbols         | admin, trader, viewer |
| GET /symbol/{symbol} | admin, trader, viewer |
| GET /exchanges       | admin, trader, viewer |
| GET /stats           | admin, trader, viewer |
| POST /refresh        | admin                 |

## Endpoints

### List Symbols

Get aggregated symbols across exchanges with ticker data.

<ParamField query="market_type" type="string" default="spot">
  Market type: "spot" or "perp"
</ParamField>

<ParamField query="exchanges" type="string">
  Comma-separated exchange filter (e.g., "binance,bybit")
</ParamField>

<ParamField query="search" type="string">
  Filter by symbol substring (e.g., "BTC")
</ParamField>

<ParamField query="quote" type="string">
  Filter by quote currency (e.g., "USDT")
</ParamField>

<ParamField query="sort_by" type="string" default="volume">
  Sort order: "volume", "change", or "symbol"
</ParamField>

<ParamField query="limit" type="number" default="100">
  Max results (1-500)
</ParamField>

```bash theme={null}
# Get top 20 spot symbols by volume
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/symbols?market_type=spot&limit=20"

# Get perp symbols for Binance and Bybit
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/symbols?market_type=perp&exchanges=binance,bybit"

# Search for BTC pairs with USDT quote
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/symbols?search=BTC&quote=USDT"
```

<ResponseExample>
  ```json theme={null}
  {
    "isError": false,
    "message": "Success",
    "statusCode": 200,
    "data": {
      "symbols": [
        {
          "symbol": "BTC/USDT",
          "base": "BTC",
          "quote": "USDT",
          "price": 98500.50,
          "change_24h_pct": -2.15,
          "volume_24h_usd": 2990000000,
          "exchanges": ["binance", "bybit", "gateio", "kraken", "okx"]
        },
        {
          "symbol": "ETH/USDT",
          "base": "ETH",
          "quote": "USDT",
          "price": 3450.25,
          "change_24h_pct": 1.82,
          "volume_24h_usd": 1250000000,
          "exchanges": ["binance", "bybit", "gateio", "kraken", "okx"]
        }
      ],
      "total": 1523,
      "market_type": "spot"
    }
  }
  ```
</ResponseExample>

### Get Symbol Detail

Get detailed info for a single symbol with exchange availability.

<ParamField path="symbol" type="string" required>
  Trading pair (e.g., "BTC/USDT" or "BTC-USDT")
</ParamField>

<ParamField query="market_type" type="string" default="spot">
  Market type: "spot" or "perp"
</ParamField>

```bash theme={null}
# Get BTC/USDT spot details
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/symbol/BTC-USDT?market_type=spot"

# Get ETH/USDT perp details
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/symbol/ETH-USDT?market_type=perp"
```

<ResponseExample>
  ```json theme={null}
  {
    "isError": false,
    "message": "Success",
    "statusCode": 200,
    "data": {
      "symbol": "BTC/USDT",
      "base": "BTC",
      "quote": "USDT",
      "price": 98500.50,
      "change_24h_pct": -2.15,
      "volume_24h_usd": 2990000000,
      "by_exchange": {
        "binance": {"available": true},
        "bybit": {"available": true},
        "gateio": {"available": true},
        "kraken": {"available": true},
        "okx": {"available": true}
      }
    }
  }
  ```
</ResponseExample>

### List Exchanges

Get supported exchanges with their capabilities.

```bash theme={null}
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/exchanges"
```

<ResponseExample>
  ```json theme={null}
  {
    "isError": false,
    "message": "Success",
    "statusCode": 200,
    "data": {
      "exchanges": [
        {"id": "binance", "name": "Binance", "spot": true, "perp": true},
        {"id": "bybit", "name": "Bybit", "spot": true, "perp": true},
        {"id": "gateio", "name": "Gate.io", "spot": true, "perp": true},
        {"id": "kraken", "name": "Kraken", "spot": true, "perp": true},
        {"id": "okx", "name": "OKX", "spot": true, "perp": true},
        {"id": "hyperliquid", "name": "Hyperliquid", "spot": false, "perp": true}
      ]
    }
  }
  ```
</ResponseExample>

### Get Market Stats

Get statistics about loaded markets.

```bash theme={null}
curl -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/stats"
```

<ResponseExample>
  ```json theme={null}
  {
    "isError": false,
    "message": "Success",
    "statusCode": 200,
    "data": {
      "spot_symbols": 1523,
      "perp_symbols": 892,
      "exchanges_loaded": 6,
      "markets_by_exchange": {
        "binance": 2400,
        "bybit": 1800,
        "gateio": 3200,
        "kraken": 600,
        "okx": 1500,
        "hyperliquid": 150
      }
    }
  }
  ```
</ResponseExample>

### Refresh Markets

Force refresh markets cache (admin only).

<ParamField query="exchange" type="string">
  Specific exchange to refresh (omit for all)
</ParamField>

```bash theme={null}
# Refresh all exchanges (admin only)
curl -X POST -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/refresh"

# Refresh only Binance (admin only)
curl -X POST -H "X-API-Key: $API_KEY" \
  "https://api.renesis.fi/order-execution/markets/refresh?exchange=binance"
```

<ResponseExample>
  ```json theme={null}
  {
    "isError": false,
    "message": "Success",
    "statusCode": 200,
    "data": {
      "refreshed": ["binance", "bybit", "gateio", "kraken", "okx", "hyperliquid"]
    }
  }
  ```
</ResponseExample>

## Error Responses

### Unauthorized (401)

```json theme={null}
{
  "isError": true,
  "message": "Unauthorized - Invalid or missing API key.",
  "statusCode": 401
}
```

### Forbidden (403)

```json theme={null}
{
  "isError": true,
  "message": "Forbidden - Insufficient permissions.",
  "statusCode": 403
}
```

### Invalid Market Type

```json theme={null}
{
  "isError": true,
  "message": "Error - market_type must be 'spot' or 'perp'.",
  "statusCode": 400
}
```

### Symbol Not Found

```json theme={null}
{
  "isError": true,
  "message": "Error - Symbol 'INVALID/USDT' not found for market_type='spot'.",
  "statusCode": 404
}
```

### Exchange Not Supported

```json theme={null}
{
  "isError": true,
  "message": "Error - Exchange 'invalid' not supported.",
  "statusCode": 400
}
```

## Notes

* **First Request**: The first request may be slow as markets are loaded from all exchanges. Subsequent requests use cached data.
* **CoinGecko Rate Limits**: Free tier allows 10-30 calls/minute. Set `COINGECKO_API_KEY` for Pro tier with higher limits.
* **Symbol Format**: Accepts both `/` and `-` as separators (e.g., "BTC/USDT" or "BTC-USDT").
* **Perp Symbols**: Perpetual contracts are identified as "swap" type in CCXT.