API
Polymarket liquidity metrics: spread, depth, VWAP
The /metrics endpoint returns pre-computed liquidity metrics for every timestamp: spread, bid depth, ask depth, and volume-weighted average price. Here is what each metric means, when to use metrics instead of raw books, and how to pull them.
What this guide covers
- GET /v1/markets/{slug}/metrics returns spread, bid_depth, ask_depth, and vwap
- Metrics are aligned with books and prices endpoints by timestamp
- Use metrics for summary statistics; use raw books for fill simulation
- Same resolution parameter as other endpoints (1s to 60s)
What the metrics endpoint returns
The /markets/{slug}/metrics endpoint returns an array of metric snapshots, one per timestamp, each containing four fields: spread, bid_depth, ask_depth, and vwap.
Spread is the difference between the best ask and best bid price at that timestamp. A spread of 0.02 means the cheapest sell is 2 cents above the highest buy. Tighter spreads indicate more liquid markets.
Bid depth is the total number of shares resting on the bid side of the book at that timestamp. Ask depth is the same for the ask side. Together, they measure how much capital is available to absorb orders.
VWAP (volume-weighted average price) is the average price weighted by the size at each level. It represents the price at which a moderately sized market order would execute, accounting for the depth available at each price level.
| Metric | Type | Description |
|---|---|---|
| spread | float | Best ask minus best bid (0—1 scale) |
| bid_depth | float | Total shares resting on the bid side |
| ask_depth | float | Total shares resting on the ask side |
| vwap | float | Volume-weighted average price across all levels |
When to use metrics vs raw books
Use metrics when you need summary statistics over time. If you’re tracking how spread evolves across a market’s lifecycle, or building a dashboard that shows depth and spread trends, metrics are pre-aggregated and fast to process.
Use raw books when you need the full order book for fill simulation, slippage modeling, or microstructure research. Raw books give you every price level, which metrics compress into summary statistics.
Many workflows use both. Start with metrics for a high-level view — is spread widening? Is depth shifting? — then drill into raw books for the specific timestamps where you see interesting behavior.
Metrics are also useful for alerting. Set thresholds on spread or depth and trigger notifications when conditions change. This is simpler than parsing raw book snapshots on every update.
Interpreting depth imbalances
When bid_depth significantly exceeds ask_depth, it suggests buying pressure — more capital is waiting to buy than to sell. The reverse suggests selling pressure.
Depth imbalance is a directional signal, but it’s not definitive. Large resting orders can be placed strategically and withdrawn before execution. Use depth imbalance as one input among many, not as a standalone signal.
Tracking depth imbalance over time reveals how the market supply and demand dynamics shift. Sudden changes in imbalance often precede price moves.
Pair depth imbalance with spread analysis. A wide spread with balanced depth suggests uncertainty; a narrow spread with imbalanced depth suggests directional conviction.
Code examples
import requests
BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key"}
slug = "btc-updown-5m-1787486400"
metrics = requests.get(
f"{BASE}/markets/{slug}/metrics",
headers=HEADERS,
params={"resolution": "1s"},
).json()
# Compute depth imbalance ratio
for m in metrics:
total = m['bid_depth'] + m['ask_depth']
if total > 0:
imbalance = (m['bid_depth'] - m['ask_depth']) / total
print(f"t={m['timestamp']} imbalance={imbalance:+.3f}")Free tier
The Starter plan is free, includes order books, prices, and metrics at 1-second resolution, with 3 days of history, 60 requests/min, 1,000/day, 1 free AI backtest, and 3 strategy backtests. No credit card required.
Paid data windows from $19/mo extend history to 30–120 days at higher throughput. Backtest AI add-on is +$19/mo or standalone at $29/mo.
FAQ
How are metrics computed?
Metrics are derived from the same L2 order book data used by the /books endpoint. Spread is best_ask minus best_bid. Depth is the sum of all size values on each side. VWAP weights each price level by its size.
Are metrics aligned with book snapshots?
Yes. Metrics, books, and prices share the same timestamps, so you can join them in a DataFrame or analysis tool without any time alignment logic.
Can I get metrics without pulling raw books?
Yes. The metrics endpoint is separate from the books endpoint. If you only need summary statistics, skip the books endpoint and use metrics directly. This saves processing time and reduces data transfer.
What does VWAP tell me that spread doesn’t?
Spread tells you the gap between the best bid and best ask. VWAP tells you the average execution price across all levels, weighted by size. A market can have a tight spread but a high VWAP if there is thin depth beyond the top of book.