Grammar
Generated from the contract: research_query.v2 · feature_defs.v1 · 136 features. Also machine-readable at GET /api/v1/research/registry.
Document shape
{
"schema_version": "research_query.v2",
"normalization_version": "archive_normalization.v1",
"feature_version": "feature_defs.v1",
"target": "record_occurrences",
"where": { "all": [ [field, operator, value], ... ] },
"sequence": { "steps": [ { "all": [...] }, ... ], "within": "30m" }, // optional
"sort": ["times.anchor_time", "asc" | "desc"],
"page": { "limit": 1..50, "cursor": null | "opaque" }
}Clauses are AND-combined triples. Unknown fields, operators or values fail validation. The scan requires at least one times.anchor_time bound.
Features (136)
| ID | DTYPE | RANGE / VALUES |
|---|---|---|
feature.basis_pct | number | -1 .. 1 |
feature.basis_change_1h | number | -2 .. 2 |
feature.basis_pctrank_30d | number | 0 .. 1 |
feature.funding_basis_divergence | number | -2 .. 2 |
feature.spot_perp_close_basis | number | -1 .. 1000000 |
feature.vpin | number | 0 .. 1 |
feature.vpin_regime | enum | normal · elevated · high · critical |
feature.book_imbalance | number | -1 .. 1 |
feature.book_imbalance_pctrank | number | 0 .. 1 |
feature.spread_norm | number | 0 .. 1 |
feature.funding_rate | number | -0.05 .. 0.05 |
feature.funding_norm | number | 0 .. 1 |
feature.oi_velocity_pctrank | number | 0 .. 1 |
feature.oi_contract_change_1h | number | -1 .. 1000 |
feature.turnover_multiple_1h | number | 0 .. 1000000 |
feature.liq_intensity_norm | number | 0 .. 1 |
feature.cascade_clustering_index | number | 0 .. 1 |
feature.liq_notional_usd_1h | number | 0 .. 1000000000000000 |
feature.taker_net_ratio_1h | number | -1 .. 1 |
feature.taker_net_ratio_4h | number | -1 .. 1 |
feature.liq_long_notional_usd_1h | number | 0 .. 1000000000000000 |
feature.liq_short_notional_usd_1h | number | 0 .. 1000000000000000 |
feature.liq_side_skew_1h | number | -1 .. 1 |
feature.top_trader_long_ratio | number | 0 .. 1 |
feature.global_long_ratio | number | 0 .. 1 |
feature.top_global_long_skew | number | -1 .. 1 |
feature.ret_15m | number | -1 .. 5 |
feature.ret_1h | number | -1 .. 5 |
feature.range_pct_1h | number | 0 .. 5 |
feature.realized_vol_1h | number | 0 .. 1 |
feature.realized_vol_pctrank | number | 0 .. 1 |
feature.vwap_dist | number | -1 .. 5 |
feature.taker_buy_ratio_15m | number | 0 .. 1 |
feature.large_trade_share_15m | number | 0 .. 1 |
feature.mins_to_funding | number | 0 .. 480 |
feature.candle_body_15m | number | -1 .. 1 |
feature.candle_upper_wick_15m | number | 0 .. 1 |
feature.candle_lower_wick_15m | number | 0 .. 1 |
feature.candle_compression_15m | number | 0 .. 10 |
feature.candle_engulfing_15m | enum | none · bullish · bearish |
feature.candle_sweep_reclaim_15m | enum | none · bullish · bearish |
feature.candle_containment_15m | enum | none · inside · outside |
feature.candle_body_1h | number | -1 .. 1 |
feature.candle_engulfing_1h | enum | none · bullish · bearish |
feature.candle_sweep_reclaim_1h | enum | none · bullish · bearish |
feature.candle_compression_1h | number | 0 .. 10 |
feature.candle_compression_4h | number | 0 .. 10 |
feature.desc_resistance_active | enum | none · active_4h · active_1d · active_both |
feature.desc_resistance_support | enum | none · rising · flat · falling |
feature.desc_resistance_compression | number | 0 .. 20 |
feature.desc_resistance_span_days | number | 0 .. 365 |
feature.desc_resistance_dist_atr | number | -100 .. 500 |
feature.desc_resistance_touches | number | 0 .. 50 |
feature.desc_resistance_broken_dist_atr | number | -500 .. 100 |
feature.desc_resistance_hours_since_break | number | 0 .. 720 |
feature.desc_resistance_broken_touches | number | 0 .. 50 |
feature.desc_resistance_short_active | enum | none · active_4h |
feature.desc_resistance_short_support | enum | none · rising · flat · falling |
feature.desc_resistance_short_compression | number | 0 .. 20 |
feature.desc_resistance_short_span_days | number | 0 .. 365 |
feature.desc_resistance_short_dist_atr | number | -100 .. 500 |
feature.desc_resistance_short_touches | number | 0 .. 50 |
feature.desc_resistance_short_broken_dist_atr | number | -500 .. 100 |
feature.desc_resistance_short_hours_since_break | number | 0 .. 720 |
feature.desc_resistance_short_broken_touches | number | 0 .. 50 |
feature.coil_state_1h | enum | none · armed · broke |
feature.coil_line_dist_pct_1h | number | -1 .. 10 |
feature.coil_span_candles_1h | number | 0 .. 2200 |
feature.coil_touches_1h | number | 0 .. 60 |
feature.coil_support_touches_1h | number | 0 .. 60 |
feature.coil_support_rise_pct_1h | number | 0 .. 1 |
feature.coil_width_ratio_1h | number | 0 .. 1 |
feature.coil_squeeze_1h | number | 0 .. 50 |
feature.coil_near_line_pct_1h | number | -1 .. 1 |
feature.coil_dominance_candles_1h | number | 0 .. 2000 |
feature.coil_prior_rise_pct_1h | number | 0 .. 1000 |
feature.coil_depth_pct_1h | number | 0 .. 1 |
feature.coil_gap_ratio_1h | number | 0 .. 3 |
feature.coil_hours_since_break_1h | number | 0 .. 720 |
feature.coil_broken_dist_pct_1h | number | -1 .. 10 |
feature.coil_break_open_below_pct_1h | number | -10 .. 1 |
feature.coil_break_close_above_pct_1h | number | -1 .. 10 |
feature.coil_break_volume_multiple_1h | number | 0 .. 10000 |
feature.coil_state_4h | enum | none · armed · broke |
feature.coil_line_dist_pct_4h | number | -1 .. 10 |
feature.coil_span_candles_4h | number | 0 .. 2200 |
feature.coil_touches_4h | number | 0 .. 60 |
feature.coil_support_touches_4h | number | 0 .. 60 |
feature.coil_support_rise_pct_4h | number | 0 .. 1 |
feature.coil_width_ratio_4h | number | 0 .. 1 |
feature.coil_squeeze_4h | number | 0 .. 50 |
feature.coil_near_line_pct_4h | number | -1 .. 1 |
feature.coil_dominance_candles_4h | number | 0 .. 2000 |
feature.coil_prior_rise_pct_4h | number | 0 .. 1000 |
feature.coil_depth_pct_4h | number | 0 .. 1 |
feature.coil_gap_ratio_4h | number | 0 .. 3 |
feature.coil_hours_since_break_4h | number | 0 .. 720 |
feature.coil_broken_dist_pct_4h | number | -1 .. 10 |
feature.coil_break_open_below_pct_4h | number | -10 .. 1 |
feature.coil_break_close_above_pct_4h | number | -1 .. 10 |
feature.coil_break_volume_multiple_4h | number | 0 .. 10000 |
feature.bottoms_state_1d | enum | none · broke |
feature.bottoms_kind_1d | enum | double · triple |
feature.bottoms_hours_since_break_1d | number | 0 .. 720 |
feature.bottoms_width_days_1d | number | 0 .. 365 |
feature.bottoms_depth_pct_1d | number | 0 .. 100 |
feature.bottoms_level_spread_1d | number | 0 .. 1 |
feature.bottoms_capitulation_1d | enum | no · yes |
feature.bottoms_neck_dist_pct_1d | number | -1 .. 100 |
feature.bottoms_base_dist_pct_1d | number | -1 .. 100 |
feature.depth_ask_pull_max_1m | number | 0 .. 1 |
feature.depth_bid_pull_max_1m | number | 0 .. 1 |
feature.depth_cost_bid_100k_bps | number | 0 .. 500 |
feature.depth_cost_ask_100k_bps | number | 0 .. 500 |
feature.book_source | enum | none · chd_derived · firehose_5s · native |
feature.depth_source | enum | none · chd · live |
feature.spread_bps | number | 0 .. 10000 |
feature.effective_spread_bps_15m | number | 0 .. 10000 |
feature.volume_usd_15m | number | 0 .. 1000000000000000 |
feature.volume_usd_pctrank | number | 0 .. 1 |
feature.vpin_pctrank | number | 0 .. 1 |
feature.liq_intensity_pctrank | number | 0 .. 1 |
feature.funding_abs_pctrank | number | 0 .. 1 |
feature.price_oi_ratio_cross_5m_v1 | enum | none · above · below |
feature.price_oi_ratio_window_cross_5m_v1 | enum | none · above · below |
feature.smt_divergence_1h_v1 | enum | none · bullish · bearish |
feature.oi_mcap_ratio | number | 0 .. 10 |
feature.oi_conversion_1h | number | -1 .. 1 |
feature.amihud_illiq_1h | number | 0 .. 1000000000000 |
feature.amihud_illiq_pctrank | number | 0 .. 1 |
feature.jump_ratio_1h | number | 0 .. 1 |
feature.flow_autocorr_1h | number | -1 .. 1 |
feature.liq_field_dist_above_near_pct | number | 0 .. 5 |
feature.liq_field_dist_below_near_pct | number | 0 .. 5 |
feature.liq_field_dist_above_far_pct | number | 0 .. 5 |
feature.liq_field_dist_below_far_pct | number | 0 .. 5 |
Operators
| FIELD KIND | OPERATORS |
|---|---|
| numeric features + windows | gte lte between |
| enum features | eq in |
| identity.symbol / identity.exchange | eq in |
| times.anchor_time | gte lte between |
Windows
Numeric features may be windowed: window.<feature>.<agg>_<duration>, e.g. window.book_imbalance.mean_15m. Closed lists:
| AGGREGATES | DURATIONS |
|---|---|
| min · max · mean · last · delta | 5m · 15m · 30m · 1h · 4h |
Sequences
2-4 steps, each 1-6 clauses over feature.* / window.* only, bound by within. Write the document form; the engine speaks the ISO form on the wire (translated for you):
| DOCUMENT FORM | WIRE FORM |
|---|---|
15m | PT15M |
30m | PT30M |
1h | PT1H |
4h | PT4H |
12h | PT12H |
24h | PT24H |
Limits
| LIMIT | VALUE |
|---|---|
| clauses (where + all steps) | 16 |
| values across all clauses | 50 |
| page limit | 50 |
Error codes
Validation failures answer 422 {"errors":[{code, message}]} with these codes, VERBATIM - the same set the app validator and the engine speak:
INVALID_SHAPE UNSUPPORTED_FIELD UNSUPPORTED_OPERATOR INVALID_VALUE QUERY_LIMIT UNSUPPORTED_TARGET TARGET_FIELD_MISMATCH UNSUPPORTED_FEATURE INVALID_SEQUENCE OUTCOME_IN_PREDICATE INVALID_CURSOR STALE_CURSOR PREVALENCE_SCOPE_UNSUPPORTED
Transport codes ride the {"error", "code"} envelope:
AUTH_REQUIRED KEY_INVALID KEY_REVOKED SCOPE_MISSING RATE_LIMITED RESEARCH_ALLOWANCE_EXHAUSTED CREDITS_UNAVAILABLE SCAN_BUSY SCAN_TIMEOUT ENGINE_UNREACHABLE ENGINE_UNCONFIGURED TOKENS_UNCONFIGURED INTERPRETER_UNCONFIGURED FEATURE_DISABLED CURSOR_UNAVAILABLE
The honesty rule
Outcome fields (outcome.*) are computed forward from each anchor and can NEVER be filtered: asking answers OUTCOME_IN_PREDICATE. To study "setup then move", state the move as a sequence step (example 1) - the anchor becomes the completion, and rates come from outcomes_summary over ALL occurrences.