Polymarket Inefficiency Scanner

Private, read-only Crystal scanner for real Polymarket market-relationship analysis.

Safety Defaults

• No real order placement.
• No wallet or private-key configuration.
• No authenticated trading endpoints.
• Dashboard/API binds to 127.0.0.1 by default.
• Production runtime uses public read-only Polymarket Gamma listings and CLOB books.
• Fixture data is limited to specs and explicitly injected test helpers.
• Trading-critical values use PolyScan::Fixed fixed-point integer math.

Run

shards install
crystal spec
crystal build src/poly_scan.cr
./poly_scan --config config/app.example.yml --once
./poly_scan --config config/app.example.yml --serve

Then open:

• http://127.0.0.1:8765/
• http://127.0.0.1:8765/api/health
• http://127.0.0.1:8765/api/opportunities
• http://127.0.0.1:8765/api/paper-trades

For a smaller real-data probe:

./poly_scan --config config/live.example.yml --serve

Then open http://127.0.0.1:8765/api/markets. The app uses public read-only Gamma market listings for discovery and public CLOB /book?token_id=... responses for executable book data. It does not configure a wallet, private key, auth token, or order-placement endpoint.

Migrations

Database schema changes are managed with Micrate. App startup automatically applies pending migrations from db/migrations before opening the configured SQLite database.

For manual migration work, install the official micrate CLI and pass the SQLite connection with DATABASE_URL:

DATABASE_URL=sqlite3://./data/poly_scan.example.db micrate status
DATABASE_URL=sqlite3://./data/poly_scan.example.db micrate up
DATABASE_URL=sqlite3://./data/poly_scan.example.db micrate down

Configuration

The app loads YAML from --config PATH, or from POLY_SCAN_CONFIG when no --config argument is provided. If neither is set, it uses config/app.example.yml.

Trading-critical decimal values must be quoted strings with up to six decimal places, for example "0.005000". They are parsed into fixed-point integer atoms by PolyScan::Fixed; do not write these values as YAML floats.

Unknown configuration keys are rejected at startup. This applies to both top-level options and nested sections such as http, paper_trading, and telegram.

Top-level options:

HTTP options under http:

Paper trading options under paper_trading:

Telegram options under telegram:

Environment overrides:

Legacy runtime fixture keys (data_source, gamma_fixture_path, and clob_books_path) are rejected in production config. Parser fixtures remain available to specs.

Example:

POLY_SCAN_DATABASE_PATH=tmp/dev.db \
POLY_SCAN_RELATIONSHIPS_PATH=config/relationships.example.yml \
./poly_scan --config config/app.example.yml --serve

Relationship Rules

Manual relationship rules live in config/relationships.example.yml and support:

• implication
• mutually_exclusive
• exhaustive_group
• complement
• correlated_group

Production rules must reference token IDs present in the loaded real Polymarket listings. The scanner does not infer exhaustiveness from market titles. Use verified_exhaustive: true only for manually checked exactly-one groups.

Rule fields: