polymarket-microstructure

KO | EN

gitlite — search

#php #javascript #python #css #hacktoberfest #objective-c #java #c #unmaintained #battleship #game #theme

polymarket-microstructure

★ 15 Open GitHub ↗

Replication package for 'The Anatomy of a Decentralized Prediction Market: Microstructure Evidence from the Polymarket Order Book.' Eight stylized facts on a pre-registered 600-market panel plus a methodological result: feed-inferred trade direction agrees with on-chain ground truth on ~59% of buckets vs ~80% Lee-Ready on equities.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# polymarket-microstructure

[![arXiv](https://img.shields.io/badge/arXiv-2604.24366-b31b1b.svg)](https://arxiv.org/abs/2604.24366)
[![SSRN](https://img.shields.io/badge/SSRN-6658364-0072BB.svg)](https://ssrn.com/abstract=6658364)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19811426.svg)](https://doi.org/10.5281/zenodo.19811426)

Replication package for *The Anatomy of a Decentralized Prediction Market: Microstructure Evidence from the Polymarket Order Book.*

The paper documents eight cross-sectional stylized facts on a pre-registered 600-market panel of Polymarket markets, plus a methodological contribution: trade-direction inference from Polymarket's public WebSocket order-book feed agrees with the on-chain ground truth on only ~59% of comparable buckets, with downstream sign-flip rates of 67% on the effective half-spread and 60% on Kyle's λ between feed-inferred and on-chain estimates.

The compiled paper is at `paper/build/anatomy.pdf`.

---

## What's in this repository

| Path | Contents |
|---|---|
| `paper/` | LaTeX manuscript, figures, tables, bibliography, compiled PDF |
| `polydata/` | Python package: order-book replay, on-chain trade joiner, microstructure measures, panel construction, stylized-fact computations |
| `scripts/` | End-to-end pipeline scripts (panel construction, measure compute, comparison panels, sensitivity tests) |
| `tests/` | pytest suite |
| `data/panel.parquet` | The 600-market pre-registered panel (top-100 by on-chain volume + random-500 from the long tail) |
| `data/panel_metadata.parquet` | CLOB REST metadata (`question`, `end_date_iso`, etc.) for the panel |
| `data/panel_trade_measures.parquet` | Six trade-based measures × 600 markets |
| `data/panel_quote/*.parquet` | Quote-based measures (spread, depth, intensity, latency, clock) × 600 markets |
| `data/clob_token_map.parquet` | 934k-row `(condition_id, yes_token_id, no_token_id)` mapping (regenerate via `scripts/pull_token_ids_clob.py`; not redistributed because the file exceeds GitHub's 100 MB limit) |
| `artifacts/sf*.{parquet,png}` | Per-stylized-fact tables and figures (SF1–SF8) |
| `artifacts/measures_compare*.parquet` | STRICT-vs-on-chain measure comparison panels |
| `artifacts/spread_decomposition*.{parquet,png}` | Glosten-Harris decomposition |
| `artifacts/sign_agreement_robustness.parquet` | Per-(window, market) sign-agreement panel for §7 |
| `artifacts/sample_step_sensitivity.parquet` | Sample-step sensitivity grid |
| `docs/preregistration_plan3c.md` | Pre-registration document (locked rules + panel SHA-256) |

What is **not** in this repository:

- The 30-billion-event raw WebSocket archive (623.8 GB across 1,262 hourly Parquet files). Acquisition is described in §3.1 of the paper; the collector configuration is sufficient to reproduce.
- The 14 GB on-chain `OrderFilled` scrape (242 slice Parquets). Acquisition is described in §3.2 and `scripts/scrape_onchain_fills.py`.

Both can be regenerated by anyone with WebSocket subscription access to Polymarket and a Polygon archive RPC provider.

### Regeneration cost notes

- **CLOB token map (`data/clob_token_map.parquet`, ~99 MB):** ~6 minutes against the public CLOB REST endpoint. Free.
- **On-chain scrape (~14 GB across 242 slice parquets, 28-day window):** the public `polygon-rpc.com` endpoint is rate-limited to the point of being impractical for this scrape. On Alchemy's free tier the author measured ~15 minutes per 5{,}000-block slice (chunk size 10) due to per-second-limit throttling, which extrapolates to ~50 hours of wall time for the full 28-day window — workable but slow. A paid Alchemy or QuickNode tier with archive access typically runs $50–$200/month and finishes the same scrape in a small number of hours; the exact figure depends on the provider's per-request and per-second pricing. Re-running with `scripts/scrape_onchain_fills.py` writes one parquet per slice and is fully resumable.
- **WebSocket archive (~624 GB):** acquisition is described in §3.1 of the paper. The author's collector ran continuously for 52 days against a single VPS and a Polymarket WebSocket subscription; the marginal cost is the VPS plus the subscription, not a per-event RPC fee.

---

## Reproducing the paper

### Build the PDF

```bash
make pdf
```

Requires TeX Live with `pdflatex`, `bibtex`, `natbib`, `booktabs`, `graphicx`. The Makefile runs `pdflatex → bibtex → pdflatex → pdflatex` from the `paper/` directory and writes `paper/build/anatomy.pdf`.

### Re-run the analyses

The full pipeline assumes Python 3.11 with [`uv`](https://docs.astral.sh/uv/) for environment management.

```bash
uv sync                                # installs dependencies from uv.lock
uv run pytest                          # runs the test suite
uv run python scripts/run_sf.py        # regenerates SF1–SF8 + Glosten-Harris artifacts
                                       # using the panel parquets shipped here
```

The end-to-end pipeline that builds `data/panel.parquet` and `data/panel_*.parquet` from raw inputs is documented in the paper (Section 3) and the corresponding scripts:

- `scripts/scrape_onchain_fills.py` — Polygon `OrderFilled` scraper
- `scripts/pull_token_ids_clob.py` — CLOB REST market token-pair pull
- `scripts/build_panel.py` — pre-registered panel construction
- `scripts/compute_panel_trade_measures.py` — trade-based measures
- `scripts/compute_panel_quote_measures.py` — quote-based measures
- `scripts/compare_strict_vs_onchain_top100.py` — §7 STRICT-vs-on-chain panel
- `scripts/diagnose_inference_recall_panel.py` — §7 sign-agreement robustness

Re-running the full pipeline from raw data takes several hours of compute and assumes both the WebSocket archive and the on-chain scrape are present locally. With the panel parquets already in `data/`, the SF runners and the §7 / Glosten-Harris computations finish in minutes.

---

## Citation

```
Dubach, Philipp D. (2026). The Anatomy of a Decentralized Prediction Market:
Microstructure Evidence from the Polymarket Order Book. arXiv preprint
arXiv:2604.24366. https://arxiv.org/abs/2604.24366
SSRN: https://ssrn.com/abstract=6658364
Replication package: https://github.com/philippdubach/polymarket-microstructure
Replication DOI: 10.5281/zenodo.19811426
```

```bibtex
@misc{dubach-2026-anatomy,
  author        = {Dubach, Philipp D.},
  title         = {The Anatomy of a Decentralized Prediction Market:
                   Microstructure Evidence from the Polymarket Order Book},
  year          = {2026},
  eprint        = {2604.24366},
  archivePrefix = {arXiv},
  primaryClass  = {q-fin.TR},
  url           = {https://arxiv.org/abs/2604.24366},
  note          = {SSRN: \url{https://ssrn.com/abstract=6658364}},
}

@misc{dubach-2026-replication,
  author    = {Dubach, Philipp D.},
  title     = {Replication package: The Anatomy of a Decentralized
               Prediction Market},
  year      = {2026},
  publisher = {Zenodo},
  version   = {v1.0},
  doi       = {10.5281/zenodo.19811426},
  url       = {https://doi.org/10.5281/zenodo.19811426},
}
```

---

## License

MIT (see `LICENSE`). The data artifacts are derived from public Polymarket order-book broadcasts and on-chain Polygon transaction logs and are released under the same terms.

polymarket-microstructure

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README