eventedge 0.1.1

A zero-dependency Python toolkit for event-contract and prediction-market research.

EventEdge

EventEdge is a zero-dependency Python toolkit for event-contract and prediction-market research. It focuses on transparent math for binary market quotes, fee/slippage-aware expected value, Kelly sizing, watchlist reporting, resolution-rule checklists, and no-arbitrage checks for related events.

The first release is deliberately small but useful: deterministic calculations, a CLI, CSV scanning, Markdown reports, resolution-rule validation, examples, and tests. The goal is to become a practical research helper for maintainers, analysts, and students who need reproducible tooling around Polymarket-style and event-contract-style markets.

Features

• Evaluate YES/NO positions with fair probability, fees, slippage, and position size.
• Compute probability edge, expected value, expected ROI, break-even probability, win/loss payoff, expected profit, and capped Kelly fraction.
• Scan and rank a CSV watchlist for fee-adjusted opportunities.
• Generate Markdown reports for research notes or pull requests.
• Validate resolution-rule metadata and flag ambiguous wording before a market enters a research watchlist.
• Check YES+NO complement bundles and exhaustive outcome bundles for guaranteed-profit conditions.
• Check conjunction, union, and implication bounds between related event markets.
• Accept decimal, percent, and cent-style probabilities such as 0.42, 42%, and 42c.
• Run fully offline with the Python standard library.

Install

From a local clone:

python -m pip install -e .

No third-party packages are required.

CLI Examples

Evaluate a YES position:

eventedge evaluate --market-id btc-100k --yes-price 0.42 --fair-yes 0.50 --size-usd 100 --fee-bps 25 --slippage-bps 10

Evaluate a NO position:

eventedge evaluate --market-id eth-etf --yes-price 0.64 --fair-yes 0.55 --side NO --size-usd 100

Scan a CSV watchlist:

eventedge scan-csv examples/markets.csv --min-edge 0.03 --fee-bps 25 --slippage-bps 10

Generate a Markdown watchlist report:

eventedge report-csv examples/markets.csv --min-edge 0.03 --output watchlist-report.md

Check a binary YES+NO complement bundle:

eventedge complement --yes-price 47c --no-price 50c

Check an exhaustive outcome bundle:

eventedge bundle "candidate-a=0.31,candidate-b=0.28,candidate-c=0.36"

Check conjunction bounds:

eventedge bounds --p-a 0.60 --p-b 0.55 --p-ab 0.40

Check union bounds:

eventedge union --p-a 60% --p-b 55% --p-a-or-b 70%

Generate a resolution-rule checklist:

eventedge resolution-check --market-id btc-100k --title "BTC above 100k" --rule-text "Resolves YES if Coinbase BTC-USD daily close is greater than 100000." --data-source "Coinbase BTC-USD daily close" --source-url "https://example.com/btc-usd" --metric daily_close --resolution-datetime 2026-12-31T23:59:00+00:00 --timezone UTC --comparator ">" --threshold 100000 --markdown

Python Example

from eventedge import FeeModel, read_quotes_csv, evaluate_quotes, rank_evaluations

quotes = read_quotes_csv("examples/markets.csv")
results = evaluate_quotes(quotes, fee_model=FeeModel(fee_bps=25, slippage_bps=10))
ranked = rank_evaluations(results, min_edge=0.03)

for result in ranked:
    print(result.market_id, result.expected_profit, result.kelly_fraction)

CSV Format

scan-csv expects:

market_id,yes_price,fair_yes,side,size_usd
btc-100k,0.42,0.50,YES,100
eth-etf,0.64,0.55,NO,100

side and size_usd are optional. Defaults are YES and 100. group and notes columns are accepted and reserved for future report enrichment.

Formula Notes

The core payoff model is documented in docs/FORMULAS.md. Short version: a contract bought at cost c pays 1 if the selected side is true and 0 otherwise, so expected value per share is p - c. The capped Kelly fraction used here is

f* = max(0, min(cap, (p - c) / (1 - c)))

where p is the researcher's fair probability and c is the fee-adjusted entry cost.

Resolution Rule Notes

Resolution risk is documented in docs/RESOLUTION_CHECKLIST.md. EventEdge checks that a market has an explicit data source, metric, threshold, timestamp, timezone, and rule text, then flags ambiguous words such as official, significant, around, and reported.

Project Scope

EventEdge is research infrastructure, not an execution bot. It does not place orders, hold API keys, or promise profitability. Its job is to make event-market math auditable and easy to test.

Near-term roadmap:

• Add optional public-data connectors behind explicit extras.
• Add notebook examples for prediction-market research.
• Add richer arbitrage primitives for related event trees.
• Add richer Markdown reports with grouped watchlists and assumptions.

Development

Run tests:

python -m unittest discover -s tests

Run the CLI from source without installing:

$env:PYTHONPATH = "src"
python -m eventedge.cli evaluate --market-id demo --yes-price 0.42 --fair-yes 0.50

Contributing

Issues and pull requests are welcome once the repository is public. Useful contributions include test cases for market math, new no-arbitrage checks, example datasets, and documentation improvements.

License

MIT.