---
title: Metadata & Discovery
description: Endpoints for discovering available exchanges, symbols, markets, block sizes, tenors, and checking API usage.
---

# Metadata & Discovery

Use these endpoints to discover what data is available before querying `/v1/points`. All metadata and discovery endpoints have **zero weight cost** -- they do not count against your rate limit budget. They use the same base URL and authentication as data queries.

## Markets

<EndpointBar method="GET" path="/v1/markets" weight="0"></EndpointBar>
The primary discovery endpoint. Search and browse available markets with filtering, sorting, and pagination. Use this to find exchange IDs, symbols, and market metadata before making data queries.

### Parameters

| Parameter | Type | Repeatable | Description |
| --- | --- | --- | --- |
| `exchange` | Exchange | Yes | Filter by exchange |
| `coin` | string | Yes | Filter by base asset |
| `category` | Category | Yes | Filter by market class (`SPOT` or `PERPETUAL`) |
| `type` | Type | Yes | Filter by data type |
| `symbolFilter` | string | No | Search across symbols, coin names, and market titles. Case-insensitive. |
| `pageSize` | int32 | No | Number of results to return |
| `pageOffset` | int32 | No | Offset for pagination (zero-based) |
| `sortCriteria.field` | MarketSortField | No | Sort field |
| `sortCriteria.direction` | SortDirection | No | `SORT_DIRECTION_ASC` or `SORT_DIRECTION_DESC` |
| `distinct` | bool | No | When `true`, return only one result per normalized symbol (highest ranked exchange) |

`category` filters by market class: `SPOT` for spot pairs and `PERPETUAL` for perpetual derivatives.

### Sort fields

| Value | Description |
| --- | --- |
| `VOLUME_24H` | 24-hour trading volume |
| `PRICE_CHANGE_24H` | 24-hour price change percentage |
| `PCT_FROM_ATH` | Distance from all-time high |
| `MARKET_SYMBOL_OI_CHANGE_24H` | 24-hour open interest change |
| `MARKET_SYMBOL_ATR_PERCENT` | ATR as percentage of price |
| `MARKET_SYMBOL_MARKETCAP` | Market capitalization |
| `AVAILABLE_SINCE` | When the market became available |

### Example: Search for BTC markets on Binance Futures

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&coin=BTC&pageSize=5"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&coin=BTC&pageSize=5 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&coin=BTC&pageSize=5 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Example: Search by name

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/markets?symbolFilter=ethereum&pageSize=10"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/markets?symbolFilter=ethereum&pageSize=10 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/markets?symbolFilter=ethereum&pageSize=10 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Example: Top markets by volume

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/markets</span>
    <span class="s-p">?exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&pageSize</span>=<span class="s-n">20</span>
    <span class="s-p">&sortCriteria.field</span>=<span class="s-s">VOLUME_24H</span>
    <span class="s-p">&sortCriteria.direction</span>=<span class="s-n">2</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&pageSize=20&sortCriteria.field=VOLUME_24H&sortCriteria.direction=2 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&pageSize=20&sortCriteria.field=VOLUME_24H&sortCriteria.direction=2 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Example: Paginating results

<CodeBlock lang="cURL">
<pre><span class="s-c"># Page 1</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&pageSize=20&pageOffset=0"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Page 2 (use nextOffset from previous response)</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&pageSize=20&pageOffset=20"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

### Response fields

Each market entry in the `symbols` array contains:

| Field | Type | Description |
| --- | --- | --- |
| `exchange` | Exchange | Exchange identifier |
| `rawSymbol` | string | Exchange-specific symbol (use this in data queries) |
| `normalizedSymbol` | string | Cross-exchange normalized market symbol (e.g., `BTC-USDT`, `BTC-USD`) |
| `coin` | string | Base asset |
| `category` | Category | Market class (`SPOT` or `PERPETUAL`) |
| `tenor` | Tenor | Option summary tenor when present |
| `coinName` | string | Full coin name (e.g., "Bitcoin") |
| `quoteCoinName` | string | Quote asset name |
| `fullName` | string | Full market name |
| `lastPrice` | double | Last traded price |
| `volume24h` | double | 24-hour trading volume |
| `volumeChange24h` | double | 24-hour volume change % |
| `priceChange24h` | double | 24-hour price change % |
| `oiChange24h` | double | 24-hour open interest change |
| `marketcap` | double | Market capitalization |
| `iconUrl` | string | Asset icon URL |
| `availableSince` | Timestamp | When the market became available |
| `predictionMarkets` | PredictionMarket[] | Prediction market outcomes. Only present for `exchange=POLYMARKET`. |

The response also includes `nextOffset` for pagination -- pass it as `pageOffset` to get the next page. When `nextOffset` equals your current offset + result count, there are no more results.

### Prediction market fields

When querying Polymarket markets, each entry in the `predictionMarkets` array contains:

| Field | Type | Description |
| --- | --- | --- |
| `slug` | string | Market URL slug |
| `question` | string | Market question (e.g., "Will X happen by Y?") |
| `groupItemTitle` | string | Title within a grouped market |
| `outcomes` | string[] | Possible outcomes (e.g., `["Yes", "No"]`) |
| `lastPrice` | double | Last traded price (0-1, representing probability) |
| `oneDayPriceChange` | double | 24-hour price change |
| `prices` | double[] | Recent price history |
| `totalVolume` | double | Total volume traded |
| `buyVolume24H` | double | 24-hour buy volume |
| `sellVolume24H` | double | 24-hour sell volume |
| `volumeChange24H` | double | 24-hour volume change |
| `openInterest` | double | Current open interest |
| `oneDayOIChange` | double | 24-hour open interest change |
| `uniqueTraders` | double | Number of unique traders |
| `orderPriceMinTickSize` | double | Minimum price tick size for orders |
| `conditionId` | string | Polymarket condition ID |
| `closed` | bool | Whether the market has resolved |
| `availableSince` | Timestamp | When the market opened |
| `availableTo` | Timestamp | Market expiry time |
| `sportsMarketType` | string | Sports market type (if applicable) |
| `line` | double | Line value for sports markets (if applicable) |

---

## Coins

<EndpointBar method="GET" path="/v1/coins" weight="0"></EndpointBar>
List all available base assets.

<CodeBlock lang="cURL">
<pre><span class="s-c"># All coins</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/coins"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Coins available on Binance Futures</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/coins?exchange=BINANCE_FUTURES"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Coins that have candle data on Binance Futures</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/coins?exchange=BINANCE_FUTURES&type=TRADE_SIDE_AGNOSTIC_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

---

## Symbols

<EndpointBar method="GET" path="/v1/symbols" weight="0"></EndpointBar>
List raw (exchange-native) symbols.
`type` is required for this endpoint. Use it together with filters like `exchange` and `coin` to narrow results.

<CodeBlock lang="cURL">
<pre><span class="s-c"># Candle symbols on Binance Futures</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/symbols?exchange=BINANCE_FUTURES&type=TRADE_SIDE_AGNOSTIC_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># BTC symbols on Binance Futures for candle data</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/symbols</span>
    <span class="s-p">?exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&type</span>=<span class="s-s">TRADE_SIDE_AGNOSTIC_AGG</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Symbols with open interest data on Bybit</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/symbols?exchange=BYBIT&type=OPEN_INTEREST_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

---

## Normalized Symbols

<EndpointBar method="GET" path="/v1/normalized-symbols" weight="0"></EndpointBar>
List normalized cross-exchange market symbols such as `BTC-USDT` and `BTC-USD`.
`type` is required for this endpoint.

<CodeBlock lang="cURL">
<pre><span class="s-c"># Normalized symbols available for candles</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/normalized-symbols?type=TRADE_SIDE_AGNOSTIC_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Normalized symbols available on Deribit for funding rate data</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/normalized-symbols?exchange=DERIBIT&type=FUNDING_RATE_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

---

## Block Sizes

<EndpointBar method="GET" path="/v1/block-sizes" weight="0"></EndpointBar>
Get the recommended block size for orderbook heatmaps. The returned value is the **4K (finest) block size**. Multiply by 5 for the HD block size.
You do not need to call this endpoint before `VOLUME_PROFILE_AGG` requests -- volume profile block size is chosen automatically by the server.

<CodeBlock lang="cURL">
<pre><span class="s-c"># Block size for orderbook heatmap</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/block-sizes</span>
    <span class="s-p">?exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&type</span>=<span class="s-s">BLOCK_BOOK_SNAPSHOT_AGG</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span>
&#10;
<span class="s-c"># Block size for TPO</span>
<span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/block-sizes?exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&type=TPO_AGG"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

| Resolution | Block Size |
| --- | --- |
| 4K | Value from this endpoint (e.g., `5`) |
| HD | 5x the value (e.g., `25`) |

---

## Tenors

<EndpointBar method="GET" path="/v1/tenors" weight="0"></EndpointBar>
List available tenor values for the current filter set. Useful for option summary types such as `IMPLIED_VOLATILITY_OPTION_SUMMARY_AGG` and `SKEW_OPTION_SUMMARY_AGG`.

<CodeBlock lang="cURL">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/tenors?type=IMPLIED_VOLATILITY_OPTION_SUMMARY_AGG&exchange=DERIBIT&coin=BTC"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodeBlock>

### Response

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"tenors"</span>: [<span class="s-s">"ONE_W"</span>, <span class="s-s">"ONE_M"</span>, <span class="s-s">"TWO_M"</span>, <span class="s-s">"THREE_M"</span>]
}</pre>
</CodeBlock>

---

## Usage

<EndpointBar method="GET" path="/v1/usage" weight="0"></EndpointBar>
Check your current rate limit quota without consuming any weight.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/usage"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/usage "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/usage "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Response

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"limit"</span>: <span class="s-n">750</span>,
  <span class="s-p">"remaining"</span>: <span class="s-n">680</span>,
  <span class="s-p">"used"</span>: <span class="s-n">70</span>,
  <span class="s-p">"reset"</span>: <span class="s-n">1712345678</span>,
  <span class="s-p">"window_seconds"</span>: <span class="s-n">60</span>
}</pre>
</CodeBlock>

| Field | Description |
| --- | --- |
| `limit` | Your tier's weight budget per window |
| `remaining` | Weight units remaining |
| `used` | Weight units consumed |
| `reset` | Unix timestamp when the bucket refills to full capacity (including burst) |
| `window_seconds` | Window duration in seconds (60) |

See [Rate Limits](/docs/rate-limits) for full details on weight calculation and tier budgets.

## Common filters

The endpoints above (`/v1/coins`, `/v1/symbols`, `/v1/normalized-symbols`, `/v1/block-sizes`) accept the same filter parameters:

| Parameter | Type | Repeatable | Description |
| --- | --- | --- | --- |
| `type` | Type | Yes | Filter by data type |
| `exchange` | Exchange | Yes | Filter by exchange |
| `category` | Category | Yes | Filter by market class (`SPOT` or `PERPETUAL`) |
| `coin` | string | Yes | Filter by coin |
| `rawSymbol` | string | Yes | Filter by raw symbol |
| `normalizedSymbol` | string | Yes | Filter by normalized symbol |

`/v1/symbols` and `/v1/normalized-symbols` require at least one `type` value. Omitting `type` currently returns a server error instead of an empty filter set.