---
title: Rate Limits
description: Weight-based rate limiting, tier budgets, and response headers.
---

# Rate Limits

Every request consumes **weight** from your per-minute budget. Lighter queries cost less, heavier queries cost more.

## Pricing tiers

|  | Free | Basic | Standard | Advanced |
| --- | --- | --- | --- | --- |
| **Price** | 0 | 99 USD/mo | 199 USD/mo | 599 USD/mo |
| **Weight / minute** | 10 | 50 | 100 | 750 |
| **Burst capacity** | 20 | 100 | 200 | 1,500 |
| **Weight / day** | 1000 | unlimited | unlimited | unlimited |
| **History depth** | 7 days | 30 days | 90 days | 1 year |
| **Multi-exchange aggregation** | No | No | No | Yes |
| **Liquidation heatmap** | No | No | No | Yes |
| **Custom data type (CDT)** | No | No | No | Yes |

Custom data type includes:
- Bitcoin Dominance
- Implied Volatility
- Skew

## Weight formula

<CodeBlock lang="Formula">
<pre><span class="s-v">base_points</span> <span class="s-o">=</span> time_range_seconds / interval_seconds
<span class="s-v">base_weight</span> <span class="s-o">=</span> <span class="s-f">ceil</span>(base_points / <span class="s-n">1000</span>) <span class="s-o">x</span> cost_multiplier</pre>
</CodeBlock>

When querying multiple exchanges with aggregation, an exchange multiplier applies:

<CodeBlock lang="Formula">
<pre><span class="s-v">exchange_multiplier</span> <span class="s-o">=</span> <span class="s-n">1</span> + (<span class="s-n">0.2</span> <span class="s-o">x</span> number_of_exchanges)</pre>
</CodeBlock>

Depth-sensitive heatmap types also apply a `maxDepth` multiplier:

<CodeBlock lang="Formula">
<pre><span class="s-v">depth_multiplier</span> <span class="s-o">=</span> <span class="s-n">1</span>
<span class="s-k">if</span> maxDepth &gt; included_depth:
  <span class="s-v">depth_multiplier</span> <span class="s-o">=</span> <span class="s-n">1</span> + (<span class="s-n">0.2</span> <span class="s-o">x</span> <span class="s-f">floor</span>((maxDepth - <span class="s-n">1</span>) / included_depth))
<span class="s-v">total_weight</span> <span class="s-o">=</span> <span class="s-f">ceil</span>(base_weight <span class="s-o">x</span> exchange_multiplier <span class="s-o">x</span> depth_multiplier)</pre>
</CodeBlock>

The minimum weight for any data request is **1**. Metadata and discovery endpoints have **zero** weight.

### Depth surcharge

For most data types, `depth_multiplier` stays at `1.0x`. It only applies to:

| Data Type | Included Depth | Depth Surcharge |
| --- | --- | --- |
| Orderbook Heatmap (`BLOCK_BOOK_SNAPSHOT_AGG`) | 3500 | +20% for each additional 3500-level band |
| Liquidation Heatmap (`HYPERLIQUID_LIQUIDATION_AGG`) | 1500 | +20% for each additional 1500-level band |

If you omit `maxDepth`, or set it at or below the included depth, the depth multiplier stays at `1.0x`.

## Weight costs per data type

| Data Type | Cost | Max Points per Request |
| --- | --- | --- |
| Candles (`TRADE_SIDE_AGNOSTIC_AGG`) | 1x | 100,000 |
| Candles per-side (`TRADE_AGG`) | 1x | 100,000 |
| Open Interest (`OPEN_INTEREST_AGG`) | 1x | 100,000 |
| Funding Rate (`FUNDING_RATE_AGG`) | 1x | 100,000 |
| Bitcoin Dominance (`TOKEN_SUPPLY_AGG`) | 1x | 100,000 |
| Implied Volatility (`IMPLIED_VOLATILITY_OPTION_SUMMARY_AGG`) | 1x | 100,000 |
| Skew (`SKEW_OPTION_SUMMARY_AGG`) | 1x | 100,000 |
| Liquidations (`LIQUIDATION_AGG`) | 1x | 100,000 |
| Volume Profile (`VOLUME_PROFILE_AGG`) | 2x | 20,000 |
| TPO / Market Profile (`TPO_AGG`) | 5x | 20,000 |
| Liquidation Heatmap (`HYPERLIQUID_LIQUIDATION_AGG`) | 5x | 5,000 |
| Orderbook Heatmap (`BLOCK_BOOK_SNAPSHOT_AGG`) | 10x | 4,000 |
| Discovery (`/v1/markets`, `/v1/usage`, etc.) | 0 | -- |

Polymarket analytics endpoints use a fixed weight instead of the point-based formula above:

| Endpoint | Cost | Notes |
| --- | --- | --- |
| `/v1/polymarket/analytics/leaderboard` | 60 fixed | Pro-tier only |
| `/v1/polymarket/analytics/trader-profile` | 100 fixed | Pro-tier only |
| `/v1/polymarket/analytics/positions` | 40 fixed | Pro-tier only |
| `/v1/polymarket/analytics/market-summary` | 60 fixed | Pro-tier only |
| `/v1/polymarket/analytics/user-categories` | 40 fixed | Pro-tier only |

## Multi-exchange cost examples

| Exchanges | Multiplier | Example: 1x type, 1000 points | Example: 10x type, 1000 points |
| --- | --- | --- | --- |
| 2 | 1.4x | 2 weight | 14 weight |
| 3 | 1.6x | 2 weight | 16 weight |
| 5 | 2.0x | 2 weight | 20 weight |

## Depth cost examples

These examples assume a 1,000-point request before exchange aggregation:

| Data Type | `maxDepth` | Depth Multiplier | Total Weight |
| --- | --- | --- | --- |
| Orderbook Heatmap (`BLOCK_BOOK_SNAPSHOT_AGG`) | `3500` or less | 1.0x | 10 weight |
| Orderbook Heatmap (`BLOCK_BOOK_SNAPSHOT_AGG`) | `3501` to `7000` | 1.2x | 12 weight |
| Orderbook Heatmap (`BLOCK_BOOK_SNAPSHOT_AGG`) | `7001` to `10500` | 1.4x | 14 weight |
| Liquidation Heatmap (`HYPERLIQUID_LIQUIDATION_AGG`) | `1500` or less | 1.0x | 5 weight |
| Liquidation Heatmap (`HYPERLIQUID_LIQUIDATION_AGG`) | `1501` to `3000` | 1.2x | 6 weight |
| Liquidation Heatmap (`HYPERLIQUID_LIQUIDATION_AGG`) | `3001` to `4500` | 1.4x | 7 weight |

## Burst capacity

Your tier has a burst capacity (2x your per-minute budget) that absorbs short traffic spikes. The bucket refills continuously at your sustained rate. For example, an Advanced tier user can briefly use up to 1,500 weight before being throttled.

## Response headers

| Header | Description |
| --- | --- |
| `X-RateLimit-Limit` | Your tier's weight budget per minute |
| `X-RateLimit-Remaining` | Weight remaining in the current window |
| `X-RateLimit-Used` | Weight consumed in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the bucket refills to full capacity (including burst) |
| `Retry-After` | Seconds to wait before retrying (only on 429) |

## Check your usage

Use the rate limit endpoint to check your current 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>

<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>