Kwery MCP

Rules for running point-in-time backtests on Polymarket and Kalshi using Kwery MCP tools. Apply when building trading strategies or reconstructing historical market state.

# Kwery Backtest

## Look-ahead Bias Prevention

Always use `*_snapshot_at` tools (not `*_snapshots`) when you need the book state at a specific historical time. The `_at` endpoint returns the snapshot *at or before* the requested timestamp — no future data leaks in.

```
polymarket_snapshot_at(symbol="BTC", time="2024-01-15T08:00:00Z")
kalshi_snapshot_at(symbol="BTC", time="2024-01-15T08:00:00Z")
hyperliquid_snapshot_at(symbol="BTC", time="2024-01-15T08:00:00Z")
```

## Critical: token_id for Polymarket

Without `token_id`, `polymarket_candles` returns multiple rows per timestamp (Up + Down legs). This corrupts any backtest. Always pass `clob_token_up` or `clob_token_down` from `polymarket_markets`.

## Backtest Workflow

1. **Discover** — `polymarket_markets` or `kalshi_markets` to find the market
2. **Candles** — `polymarket_candles` with `token_id` for the probability series
3. **Reference price** — `binance_candles` or `chainlink_candles` for spot
4. **Snapshots** — `*_snapshot_at` at each decision point
5. **Analyze** — compare probabilities vs realized outcomes

## Price Conventions

- Polymarket: probabilities [0-1]
- Kalshi: cents [0-100] — normalize with `/100`
- Binance / Chainlink: USD

## Pagination

For full history, paginate with `after=meta.next_cursor` until `meta.next_cursor` is null.

Rules for analyzing perpetual funding rates, open interest, and liquidations across Binance and Hyperliquid using Kwery MCP tools.

# Kwery Derivatives Analysis

## Available Tools

| Tool | Description |
|------|-------------|
| `binance_funding` | Binance futures funding (every 8h) |
| `hyperliquid_funding` | Hyperliquid funding (continuous) |
| `binance_oi` | Binance open interest history |
| `hyperliquid_oi` | Hyperliquid open interest history |
| `binance_liquidations` | Forced liquidation events |
| `hyperliquid_candles` | OHLCV + funding_rate + open_interest per bar |

## Funding Rate Interpretation

- Positive -> longs pay shorts -> crowded long / bullish sentiment
- Negative -> shorts pay longs -> crowded short / bearish sentiment
- Annualized = `rate * 3 * 365` (Binance pays every 8h)
- Extreme: >0.1%/8h = >109% APR -> watch for reversal

## Open Interest Signals

- Rising OI + rising price -> trend confirmation
- Rising OI + falling price -> bearish pressure building
- Falling OI + price move -> short squeeze or liquidation cascade

## Liquidations

Use `side="long"` or `side="short"` and `min_usd` to filter significant events:
```
binance_liquidations(symbol="BTC", side="long", min_usd=100000, limit=1000)
```
`min_usd` filter requires Business plan.

## Tier Limits

Funding/OI: Free 7d - Pro 6mo - Business full
Liquidations: Free 24h - Pro 6mo - Business full

Overview of Kwery AI — unified crypto and prediction market data API. Read this rule to understand what Kwery provides and how to use it in agent workflows.

# Kwery AI Overview

Kwery provides unified historical data for crypto and prediction markets via a single REST API at `https://kwery-api.com`.

## Data Sources

| Source | Data |
|--------|------|
| `binance` | Spot OHLCV, trade ticks, directional flow |
| `binance_futures` | Futures OHLCV, funding rates, OI, liquidations |
| `chainlink` | Oracle price series |
| `polymarket` | Prediction market probabilities, CLOB order book |
| `kalshi` | Binary event markets, order book snapshots |
| `hyperliquid` | Perpetual OHLCV + funding + OI, L2 snapshots |

## Authentication

All requests require `X-API-Key` header. Set `KWERY_API_KEY` environment variable.

## Key Conventions

- **Polymarket prices** are probabilities [0-1]
- **Kalshi prices** are cents [0-100] — divide by 100 to normalize
- **Pagination** uses cursor-based `after` param from `meta.next_cursor`
- **Polymarket candles** require `token_id` for a single backtestable series
- **Point-in-time snapshots** use `*_snapshot_at` (not `*_snapshots`) to avoid look-ahead bias
- **Tier gate errors** (403) include upgrade URL at `https://kwery.xyz/pricing`

## Discovery Tools

```
kwery_limits   — check plan, credits, feature access
kwery_sources  — list all sources, symbols, intervals, tier requirements
kwery_status   — ingestion health per source
```

Rules for researching historical Polymarket and Kalshi prediction market data, resolutions, and cross-platform comparisons using Kwery MCP tools.

# Kwery Prediction Market Research

## Market Discovery

```
polymarket_markets(symbol="BTC", active=false)   # resolved markets
kalshi_markets(symbol="BTC")
```

`active=false` returns resolved markets only. `active=true` returns live only.

## Resolved Market Fields (Polymarket)

- `winner`: "Up" or "Down"
- `resolved_at`: resolution timestamp
- `final_volume`: total USDC traded
- `clob_token_up` / `clob_token_down`: token IDs for candle series

## Cross-Platform Probability Comparison

Kalshi prices are in cents [0-100]. Polymarket in [0-1]. Normalize before comparing:

```
pm_prob = close                    # Polymarket [0-1]
ks_prob = mid_price / 100          # Kalshi cents → [0-1]
divergence = pm_prob - ks_prob
```

## Event-Driven Price Study

Use `polymarket_candles` with `token_id` to get a single price series (probabilities converge to 1.0 or 0.0 at expiry).

## Order Book Depth Over Time

```
polymarket_snapshots(symbol="BTC", interval="1h", include_orderbook=true, depth=10)
```

Each snapshot: `bids`, `asks`, `mid_price`, `spread`, `imbalance`.

## Tier Limits

Candles: Free 14d · Pro 30d · Business full
Snapshots: Free 7d · Pro 30d · Business full

Rules for building cross-platform trading signals from Polymarket, Kalshi, Binance, and Hyperliquid derivatives using Kwery MCP tools.

# Kwery Signal Construction

## Data Normalization -- Critical

**Kalshi prices are cents (0-100). Polymarket is [0-1].** Always normalize before comparing:

- Kalshi: `mid_price / 100` -> [0-1]
- Polymarket: `close` -> already [0-1]

Timestamp field names differ: Kalshi uses `time`, all others use `timestamp`. Align to UTC before cross-source comparisons.

## Signal Patterns

### Funding Rate vs Prediction Market Divergence
High funding + low Kalshi/Polymarket probability = derivatives/PM disagreement -> mean reversion candidate.

```
binance_funding(symbol="BTC", source="binance_futures")
kalshi_prices(symbol="BTC", interval="1h")
```

### Liquidation Cascade Setup
```
binance_liquidations(symbol="BTC", side="long", min_usd=100000)
```
Cluster of large liquidations in a short window = potential capitulation.

### Directional Flow
```
binance_flow(symbol="BTC", interval="1h")
```
`buy_ratio > 0.5` = net buying pressure.

### Kalshi/Polymarket Imbalance
`imbalance > 0.5` = more YES (bid) liquidity = bullish signal.

## Funding Rate Math

Binance pays every 8h. Annualize: `rate * 3 * 365`.
Extreme positive (>0.1%/8h = >109% APR) often precedes corrections.