Reference-level entry conditions for Polymarket backtests

• Backtest AI entry types: price, change, reference, time and or
• A reference entry reads the archived spot or TWAP level for the market's asset
• The reference series is the settlement input, not the CLOB price
• Entries can be combined with the or type to fire on multiple conditions

The backtester understands four entry conditions. A price entry fires on a level in the market's own book. A change entry fires on a move of a given size. A reference entry fires on the underlying asset's archived reference price - spot or TWAP. A time entry fires at a fixed offset into the window.

They are not interchangeable. A price entry answers 'did the contract get cheap'; a reference entry answers 'did the underlying move'. Those are different questions, and mixing them up is a common source of strategies that backtest well and trade badly.

Polymarket crypto markets settle on the underlying asset's 60-second TWAP, not on the contract price. A strategy whose thesis is 'the asset will rise' should therefore enter on the reference series, because that is the series that decides the outcome. Entering on the contract price injects a second, unrelated variable.

Using a reference entry also removes the market's own noise from the signal. On thin assets the contract price can jump on a single small trade while the underlying has not moved at all; a reference entry ignores that and reacts to the real thing.

The or type lets an entry fire on the first of several conditions - for example, a reference move of a given size or a time offset, whichever comes first. This is how you express 'react to the move, but do not wait past halfway through the window'.

Keep the combined set small. Every added condition is another degree of freedom that can be tuned to the past, and the or type makes it easy to add just one more until the strategy fits history and nothing else.

An entry condition is only meaningful paired with an exit rule and a fill model. A perfect reference entry into a market that then cannot be exited at a fair price is worthless. Pair every entry type with an explicit exit - take-profit, stop, trailing stop, time or hold-to-expiry - and a realistic fill.

The backtester enforces this: the strategy object requires both an entry list and an exit, plus the market, side and fee, so an incomplete plan is rejected rather than silently defaulted.

import requests

BASE = "https://api.polyorderbooks.com/v1"
HEADERS = {"X-API-Key": "your-key", "Content-Type": "application/json"}

# Enter when the BTC reference moves 0.1%, exit on a 0.2% take-profit.
body = {
    "strategy": {
        "market": {"coin": "btc", "market_type": "5m"},
        "side": "yes",
        "entry": [{"type": "reference", "change": 0.001}],
        "exit": {"type": "take_profit", "value": 0.002},
        "taker_fee": 0.0,
        "trade_lag_seconds": 1,
    },
    "sampleSize": 50,
    "days": 5,
}
r = requests.post(f"{BASE}/ai/backtest", headers=HEADERS, json=body)
r.raise_for_status()
print(r.json()["report"]["win_rate"])

The Starter plan is free, includes order books, prices, and metrics at 250ms 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.

• Exit rules
• Reference price data
• Backtest AI