{
 "$defs": {
  "contract": {
   "additionalProperties": false,
   "properties": {
    "asset": {
     "description": "the market or indicator code (SPX, BTC, GOLD ...)",
     "minLength": 1,
     "type": "string"
    },
    "end_at": {
     "description": "UTC time of the horizon's last minute (later than reference_at)",
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "horizon": {
     "description": "the horizon label; the Council uses 1d, 1w, 1m, 6m",
     "minLength": 1,
     "type": "string"
    },
    "reference_at": {
     "description": "UTC time of the reference price",
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "rule": {
     "const": "up_if_close_above_reference; draw_if_abs_move_below_band"
    }
   },
   "required": [
    "asset",
    "horizon",
    "reference_at",
    "end_at",
    "rule"
   ],
   "type": "object"
  },
  "contract_v2": {
   "additionalProperties": false,
   "properties": {
    "asset": {
     "minLength": 1,
     "type": "string"
    },
    "end_at": {
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "horizon": {
     "minLength": 1,
     "type": "string"
    },
    "price_provider": {
     "description": "where the minute bars come from",
     "minLength": 1,
     "type": "string"
    },
    "price_symbol": {
     "description": "the symbol at the provider",
     "minLength": 1,
     "type": "string"
    },
    "reference_at": {
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "reference_rule": {
     "description": "the id of the rule that picks the reference and the end price from the bars; its full text is in reference_rules",
     "minLength": 1,
     "type": "string"
    },
    "resolver_version": {
     "description": "the version of the rules that turn prices into an outcome (r1 ...); an empty cell in a CSV row means r1",
     "pattern": "^r[0-9]+$",
     "type": "string"
    },
    "rule": {
     "const": "up_if_close_above_reference; draw_if_abs_move_below_band"
    }
   },
   "required": [
    "asset",
    "horizon",
    "reference_at",
    "end_at",
    "rule",
    "resolver_version",
    "reference_rule",
    "price_provider",
    "price_symbol"
   ],
   "type": "object"
  },
  "csv_row": {
   "properties": {
    "actual_pct": {
     "pattern": "^(|-?[0-9]+(\\.[0-9]+)?([eE][-+]?[0-9]+)?)$",
     "type": "string"
    },
    "asset": {
     "minLength": 1,
     "type": "string"
    },
    "draw": {
     "pattern": "^(|True|False|true|false)$",
     "type": "string"
    },
    "event_end_at": {
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "event_id": {
     "pattern": "^ev1-[0-9a-f]{16}$",
     "type": "string"
    },
    "event_id_v2": {
     "description": "optional: the id of the full contract (contract_v2)",
     "pattern": "^(|ev2-[0-9a-f]{16})$",
     "type": "string"
    },
    "event_reference_at": {
     "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
     "type": "string"
    },
    "horizon": {
     "minLength": 1,
     "type": "string"
    },
    "methodology_version": {
     "pattern": "^m[0-9]+$",
     "type": "string"
    },
    "price_provider": {
     "type": "string"
    },
    "price_symbol": {
     "type": "string"
    },
    "prob_up": {
     "description": "stated chance of up, % (0-100), empty when none",
     "pattern": "^(|[0-9]+(\\.[0-9]+)?)$",
     "type": "string"
    },
    "reference_rule": {
     "type": "string"
    },
    "resolver_version": {
     "pattern": "^(|r[0-9]+)$",
     "type": "string"
    }
   },
   "required": [
    "event_id",
    "event_reference_at",
    "event_end_at",
    "asset",
    "horizon",
    "methodology_version"
   ],
   "type": "object"
  }
 },
 "$id": "https://trends.polyhelper.ai/api/v1/event-contract.schema.json",
 "$ref": "#/$defs/contract",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "checks_beyond_schema": [
  "event_id equals the hash of the contract rebuilt from asset, horizon, event_reference_at, event_end_at",
  "event_end_at is later than event_reference_at",
  "when event_id_v2 is given: reference_rule, price_provider and price_symbol are given, reference_rule is one of reference_rules, and event_id_v2 equals the hash of contract_v2 rebuilt from the row (resolver_version empty = r1)",
  "prob_up, when given, is between 0 and 100",
  "the sign of the outcome: draw=False with actual_pct <= 0 is not “up”; draw=True needs actual_pct; actual_pct with no draw flag is incomplete"
 ],
 "description": "The contract of one forecast event: market x horizon x reference price x end time. event_id = \"ev1-\" + first 16 hex of sha256 of the canonical JSON of the contract (keys sorted, no spaces, UTF-8) with the five keys of `contract`. Rule: the event is “up” if the value at end_at is above the value at reference_at (move > 0); a move smaller than the league's draw band (noise) is a draw. License CC BY 4.0. The FULL contract is `contract_v2` (event_id_v2 = \"ev2-\" + first 16 hex of sha256 of its canonical JSON): the same five keys and the resolver version, the reference rule (`reference_rules`), the price provider and the price symbol (`price_sources`); event_id (ev1) is never changed and stays beside it.",
 "example_csv": "run_id,asset,horizon,event_reference_at,event_end_at,event_id,methodology_version,prob_up,actual_pct,draw,resolver_version,event_id_v2,reference_rule,price_provider,price_symbol",
 "examples": [
  {
   "contract_v2": {
    "asset": "SPX",
    "end_at": "2026-10-20T20:00:00Z",
    "horizon": "1d",
    "price_provider": "yahoo_finance_chart_v8_1m",
    "price_symbol": "^GSPC",
    "reference_at": "2026-10-20T13:30:00Z",
    "reference_rule": "first_1m_bar_at_or_after_reference_at__last_1m_bar_at_or_before_end_at__v1",
    "resolver_version": "r1",
    "rule": "up_if_close_above_reference; draw_if_abs_move_below_band"
   },
   "event_id": "ev1-51dee40f8f414f63",
   "event_id_v2": "ev2-ef9959e9134a8eb0",
   "what": "a US index, one day"
  },
  {
   "contract_v2": {
    "asset": "US10Y",
    "end_at": "2026-10-20T19:00:00Z",
    "horizon": "1d",
    "price_provider": "yahoo_finance_chart_v8_1m",
    "price_symbol": "^TNX",
    "reference_at": "2026-10-20T13:30:00Z",
    "reference_rule": "first_1m_bar_at_or_after_reference_at__last_1m_bar_at_or_before_end_at__v1",
    "resolver_version": "r1",
    "rule": "up_if_close_above_reference; draw_if_abs_move_below_band"
   },
   "event_id": "ev1-7502e65bcc586be7",
   "event_id_v2": "ev2-60a7ec75666b9b67",
   "what": "US10Y: the end is 15:00 ET (^TNX minute bars stop at 14:59)"
  },
  {
   "contract_v2": {
    "asset": "SPX",
    "end_at": "2026-11-27T18:00:00Z",
    "horizon": "1d",
    "price_provider": "yahoo_finance_chart_v8_1m",
    "price_symbol": "^GSPC",
    "reference_at": "2026-11-27T14:30:00Z",
    "reference_rule": "first_1m_bar_at_or_after_reference_at__last_1m_bar_at_or_before_end_at__v1",
    "resolver_version": "r1",
    "rule": "up_if_close_above_reference; draw_if_abs_move_below_band"
   },
   "event_id": "ev1-fe41b2fa35f2ef03",
   "event_id_v2": "ev2-5d614c2ec78d3a3e",
   "what": "an early close of the NYSE (13:00 ET)"
  },
  {
   "contract_v2": {
    "asset": "BTC",
    "end_at": "2026-10-21T13:25:00Z",
    "horizon": "1d",
    "price_provider": "yahoo_finance_chart_v8_1m",
    "price_symbol": "BTC-USD",
    "reference_at": "2026-10-20T13:25:00Z",
    "reference_rule": "first_1m_bar_at_or_after_reference_at__last_1m_bar_at_or_before_end_at__v1",
    "resolver_version": "r1",
    "rule": "up_if_close_above_reference; draw_if_abs_move_below_band"
   },
   "event_id": "ev1-e1a8637333ee51df",
   "event_id_v2": "ev2-87378a8098fb028a",
   "what": "BTC: the reference is the minute of the seal, the end 24 h later"
  }
 ],
 "price_sources": {
  "BRENT": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:DCOILBRENTEU",
   "symbol": "BZ=F"
  },
  "BTC": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "coingecko:bitcoin",
   "symbol": "BTC-USD"
  },
  "COPPER": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": null,
   "symbol": "HG=F"
  },
  "DJI": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:DJIA",
   "symbol": "^DJI"
  },
  "DXY": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": null,
   "symbol": "DX-Y.NYB"
  },
  "GOLD": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": null,
   "symbol": "GC=F"
  },
  "NDX": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:NASDAQ100",
   "symbol": "^NDX"
  },
  "SOX": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": null,
   "symbol": "^SOX"
  },
  "SPX": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:SP500",
   "symbol": "^GSPC"
  },
  "US10Y": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:DGS10",
   "symbol": "^TNX"
  },
  "VIX": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:VIXCLS",
   "symbol": "^VIX"
  },
  "WTI": {
   "provider": "yahoo_finance_chart_v8_1m",
   "second_source": "FRED:DCOILWTICO",
   "symbol": "CL=F"
  }
 },
 "reference_rules": {
  "first_1m_bar_at_or_after_reference_at__last_1m_bar_at_or_before_end_at__v1": "Prices are the minute bars (interval 1m) of price_provider for price_symbol. The reference price is the close of the FIRST bar whose start is at or after reference_at (not the last bar before it). Markets of the list other than BTC: it is accepted when that bar starts no later than 15 minutes after reference_at, else the event waits for data and is never moved to another time. BTC: there is no such allowance for the reference price (the first bar at or after the seal minute is taken; none yet - the event waits). The end price is the close of the LAST bar whose start is at or before end_at; it is accepted when that bar is no earlier than 15 minutes before end_at (BTC: 10 minutes). It is the final (confirmed) end bar when it is at most 60 seconds before end_at or a bar after end_at already exists; an earlier bar stands as the close only after the wait for the full bar is over and is named close_early. For the sessions from 2026-10-21 (PRICE_CHECK_FROM) both prices are checked against a second source (second_source) and a disagreement holds the event back; the sessions before are scored from the minute bars alone. Only an explicit price_fix line of the book replaces the prices. reference_at: 09:30 ET of the session for the markets of the list; BTC - the minute of the seal of the run. end_at: the close of the horizon's last NYSE session (16:00 ET; 13:00 ET on an early close of the NYSE calendar); US10Y - 15:00 ET (its ^TNX minute bars stop at 14:59); BTC - 24 h after the seal for 1d but at most the close of the session that scores the run, and 7, 30, 182 calendar days after the seal for 1w, 1m, 6m. The draw band (|move| below it is a draw) is k = thresholds.noise_sigma = 0.1 times a scale of the move: for 1d, k x the mean absolute 1-minute move (%) of the last 4 sessions of minute bars before the reference x sqrt(390) (minute moves across a recorded change of contract are left out; the band is frozen once scored, council_score noise_of); for 1w, 1m, 6m, k x the mean absolute daily move (%) of the last 60 New York days before the reference x sqrt(N), N = the horizon's sessions (BTC: calendar days). The band itself is in the score line (`noise`)."
 },
 "title": "Forecast event contract"
}