Event-Linked Perpetuals — Research Code

Research code for the Event-Linked Perpetuals programme — a series of empirical papers on Polymarket microstructure and mechanism design.

Papers and status

#	Title	Links	Dataset
Paper 1	Resolution-Aware Perpetual Futures on Binary Prediction Markets: An Empirical Risk-Design Framework	arXiv · SSRN · DOI	pmxt-stylized-facts-v1
Paper 2	A Taxonomy of Event-Linked Perpetual Futures: Variant Designs Beyond the Single-Market Binary Case	arXiv · SSRN · DOI	—
Paper 3	Manipulation, Insider Information, and Regulation in Leveraged Event-Linked Markets	arXiv · SSRN · DOI	—
Paper 4	Fill-Side Non-Retail Trading on Polymarket: An Empirical Study of Behavioral Tiers and Microstructure Signatures Under Quote-Attribution Constraints	arXiv · SSRN · DOI	pmxt-behavioral-clusters-v1

PMXT Dataset Family

All datasets are published at github.com/ForesightFlow/datasets and archived on Zenodo under CC-BY 4.0.

Bundle	DOI	Description	Size
pmxt-stylized-facts-v1	10.5281/zenodo.20107449	SF1–SF9 measurements for 13,314 resolved markets	1.6 MB
pmxt-counterfactual-replay-v1	10.5281/zenodo.20108387	E2/E3 resolution-zone counterfactuals	19 KB
pmxt-behavioral-clusters-v1	TBD (Zenodo forthcoming)	Fill-side behavioral clusters, feature tiers, and per-market microstructure signatures	17.8 MB

Repository structure

event-linked-perps/
│
├── ingest/                          # Data acquisition and augmentation
│   ├── download_archive.py          # PMXT v2 archive downloader
│   ├── uma_resolutions.py           # UMA Optimistic Oracle resolution joiner
│   ├── market_metadata.py           # Gamma market metadata fetcher
│   ├── verify_target_week.py        # Archive integrity verification
│   └── tests/
│
├── evaluation/                      # Experiment evaluation code
│   ├── stylized_facts.py            # SF1–SF9 (Paper 1, CC-004)
│   ├── counterfactual_replay.py     # E2 counterfactual replay (Paper 2, CC-007)
│   ├── resolution_zone_test.py      # E3 resolution-zone protocol (Paper 2, CC-008)
│   ├── g5_evaluation.py             # Gate G5: sample adequacy
│   │
│   ├── paper4/                      # Paper 4 pipeline (CC-013 / CC-015)
│   │   ├── collect_orderfilled_events.py    # Phase 1b: stream 13.4M OrderFilled events
│   │   ├── compute_features.py              # Phase 2: address-level feature vector
│   │   ├── run_clustering.py                # Phase 3: DBSCAN / HDBSCAN / k-means
│   │   ├── per_cluster_microstructure.py    # Phase 4: cluster archetypes + CIs
│   │   ├── manipulation_detection.py        # Phase 5: wash-volume + book-swing detection
│   │   ├── compute_microstructure_metrics.py # Phase 6a: per-market metrics
│   │   ├── compute_ils.py                   # Phase 6b: Informed Liquidity Score
│   │   ├── compute_per_market_address.py    # Phase 6c-A1: per-(market,address) volume
│   │   ├── cluster_microstructure_bilateral.py # Phase 6c: bilateral Spearman analysis
│   │   ├── rerun_bilateral_real.py          # Phase 6c re-run with real volume shares
│   │   ├── compute_feature_tiers.py         # CC-015 B: feature-tier classification
│   │   ├── build_dataset_bundle.py          # CC-015 C: Zenodo bundle assembly
│   │   ├── paper1_feedback_tests.py         # Paper 1 feedback validation
│   │   ├── extract_per_address_tables.py    # Address-level table extraction
│   │   ├── rpc_utils.py                     # Polygon RPC rotation utilities
│   │   └── pmxt-behavioral-clusters-v1/     # Dataset bundle (Zenodo staging)
│   │       ├── README.md
│   │       ├── DATASHEET.md
│   │       ├── CITATION.cff
│   │       ├── LICENSE.txt
│   │       ├── data/                        # 13 data files (17.8 MB)
│   │       ├── docs/                        # SCHEMA.md, METHODOLOGY.md, KNOWN_LIMITATIONS.md
│   │       └── manifests/                   # parameters_locked, library_versions, code, source
│   │
│   ├── output/                      # Locked numerical results (Papers 1–2)
│   │   ├── e2/results.json
│   │   ├── e2b/results.json
│   │   ├── e3/results.json
│   │   └── sf_results_stratified.json
│   └── paper/figures/               # Paper figures (PDF)
│
├── datasets-staging/                # Dataset staging for ForesightFlow/datasets
│   └── pmxt-stylized-facts-v1/
│
├── scripts/                         # Reproducibility scripts
│   ├── env.sh                       # Export environment variables
│   ├── preflight.py                 # Pre-run checks
│   ├── reproduce.sh                 # End-to-end pipeline
│   └── README.md
│
├── data/
│   ├── DATA.md                      # Data acquisition instructions
│   ├── labels/news_windows.json     # Hand-labelled news windows
│   └── raw/                         # Raw archive (gitignored, ~72 GB)
│
├── docs/                            # Verification dumps and research notes
├── paper/figures/                   # Paper-level figures (PDF)
├── tests/smoke/                     # Smoke tests (no archive needed)
├── pyproject.toml
├── requirements.txt
├── CITATION.cff
├── CONTRIBUTING.md
└── LICENSE

Quick start

Requirements: Python 3.11+, ~20 GB free disk space (full archive ~72 GB).

git clone https://github.com/ForesightFlow/event-linked-perps.git
cd event-linked-perps
pip install -r requirements.txt
source scripts/env.sh
python scripts/preflight.py

Paper 1 & 2 — Stylized facts and counterfactual replay

# Gate G5 — sample adequacy (required first)
python -m evaluation.g5_evaluation \
    --archive-dir "$PMXT_V2_ARCHIVE_DIR" \
    --output evaluation/output/table_t_g5_stratified_70k.json \
    --seed 20260505

# Stylized facts SF1–SF9
python -m evaluation.stylized_facts \
    --analysis-sample evaluation/output/table_t_g5_stratified_70k.json \
    --archive-dir "$PMXT_V2_ARCHIVE_DIR" \
    --output evaluation/output/sf_results_stratified.json \
    --seed 20260505

# E2 counterfactual replay
python -m evaluation.counterfactual_replay \
    --analysis-sample evaluation/output/table_t_g5_stratified_70k.json \
    --archive-dir "$PMXT_V2_ARCHIVE_DIR" \
    --output-dir evaluation/output/e2 \
    --seed 20260505

# E3 resolution-zone protocol
python -m evaluation.resolution_zone_test \
    --analysis-sample evaluation/output/table_t_g5_stratified_70k.json \
    --archive-dir "$PMXT_V2_ARCHIVE_DIR" \
    --output-dir evaluation/output/e3 \
    --seed 20260505

Paper 4 — Behavioral clusters and microstructure (CC-013 / CC-015)

Requires Polygon archive RPC access. Set POLYGON_RPC_URL in scripts/env.sh.

# Phase 1b: collect OrderFilled events (~60 min, requires Polygon archive RPC)
python -m evaluation.paper4.collect_orderfilled_events \
    --start-date 2026-04-21 --end-date 2026-04-27

# Phase 2–5: features, clustering, archetypes, manipulation
python -m evaluation.paper4.compute_features
python -m evaluation.paper4.run_clustering
python -m evaluation.paper4.per_cluster_microstructure
python -m evaluation.paper4.manipulation_detection

# Phase 6: microstructure metrics, ILS, per-market attribution, bilateral
python -m evaluation.paper4.compute_microstructure_metrics
python -m evaluation.paper4.compute_ils
python -m evaluation.paper4.compute_per_market_address   # CC-015 A1
python -m evaluation.paper4.rerun_bilateral_real         # ~67 min, BCa bootstrapping

# CC-015 B+C: feature tiers + dataset bundle
python -m evaluation.paper4.compute_feature_tiers
python -m evaluation.paper4.build_dataset_bundle

All seeds and thresholds are locked in evaluation/paper4/pmxt-behavioral-clusters-v1/manifests/parameters_locked.json.

Key findings (Paper 4)

Three-gate verdict:

G-FILL ✅ PASS — 13,356,931 fills attributed via eth_getLogs on CTFExchange
G-QUOTE-LIFE ❌ FAIL universal — off-chain CLOB; no quote lifecycle data on Polygon
G-BOOK ⚠️ PASS partial — market-level best_bid/best_ask only

Feature-tier distribution (43,116 markets · 77,203 addresses · 2026-04-21 to 2026-04-27):

Tier	Addresses	%	Notional	%
whale-tier (≥ $1M)	68	0.1%	$184M	28.0%
high-frequency-operator	2,952	3.8%	$155M	23.5%
power-trader	6,738	8.7%	$197M	29.9%
active-retail	2,062	2.7%	$70M	10.6%
high-breadth-operator	2,025	2.6%	$7M	1.1%
episodic-retail	63,358	82.1%	$45M	6.8%

Top 3 tiers (12.6% of addresses) control 81.4% of notional volume.

Bilateral analysis (real per-market volume shares, BH-FDR α=0.05): 75 / 110 tests significant. Strongest: UNKNOWN×OFI (ρ=+0.66), RETAIL×OFI (ρ=+0.50), fill-MM×VPIN (ρ=+0.44).

Data

Raw data is not committed. See data/DATA.md for the PMXT v2 archive and docs/data_description.md for the Parquet schema.

Global seed: 20260505 — used for all sampling, clustering, bootstrap, and random decisions.

Tests

python -m pytest tests/ evaluation/tests/ ingest/tests/ -v
SKIP_NETWORK=1 python -m pytest tests/ evaluation/tests/ ingest/tests/ -v  # no network

Citation

For the research code:

@misc{nechepurenko2026elp_code,
  title     = {event-linked-perps: Research code for the Event-Linked Perpetuals programme},
  author    = {Nechepurenko, Maksym},
  year      = {2026},
  publisher = {GitHub},
  url       = {https://github.com/ForesightFlow/event-linked-perps}
}

For the behavioral clusters dataset (Paper 4):

@dataset{nechepurenko2026pmxt_clusters,
  author    = {Nechepurenko, Maksym},
  title     = {PMXT Behavioral Clusters v1 — Non-Retail Polymarket Microstructure Dataset},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.XXXXXXXX},
  license   = {CC-BY-4.0}
}

For the stylized facts dataset (Paper 1):

@dataset{nechepurenko2026pmxt_sf,
  author    = {Nechepurenko, Maksym},
  title     = {PMXT Stylized Facts v1 — Polymarket Microstructure Dataset},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20107449},
  license   = {CC-BY-4.0}
}

License

Code: MIT — see LICENSE.
Datasets: CC-BY 4.0 — see respective bundle LICENSE.txt.

Contact

Maksym Nechepurenko — maksym@devnull.ae

Navigation Menu

Uh oh!

Repository files navigation

Event-Linked Perpetuals — Research Code

Papers and status

PMXT Dataset Family

Repository structure

Quick start

Paper 1 & 2 — Stylized facts and counterfactual replay

Paper 4 — Behavioral clusters and microstructure (CC-013 / CC-015)

Key findings (Paper 4)

Data

Tests

Citation

License

Contact

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
data		data
datasets-staging		datasets-staging
docs		docs
evaluation		evaluation
ingest		ingest
paper		paper
papers/paper4		papers/paper4
releases/paper4		releases/paper4
scripts		scripts
tests		tests
.gitignore		.gitignore
CITATION.cff		CITATION.cff
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
requirements.in		requirements.in
requirements.txt		requirements.txt

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Event-Linked Perpetuals — Research Code

Papers and status

PMXT Dataset Family

Repository structure

Quick start

Paper 1 & 2 — Stylized facts and counterfactual replay

Paper 4 — Behavioral clusters and microstructure (CC-013 / CC-015)

Key findings (Paper 4)

Data

Tests

Citation

License

Contact

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages