`skills/polymtrx/SKILL.md`

120 lines
---
name: polymtrx
description: 'Scan LIVE Polymarket prediction markets and rank them by tradeable-edge signals — real-money volume, order-book liquidity/spread, time-to-resolution, price contest (near 50/50), longshot mispricing, and recent movement — then synthesize a grounded read of where the best opportunity is right now. Runs a zero-dependency, no-key, $0-local Python engine over Polymarket''s public Gamma + CLOB APIs. READ-ONLY: it surfaces opportunities, it never trades, never touches a wallet or key. This skill should be used when the user asks what is happening on Polymarket, wants prediction-market odds/opportunities on a topic, asks "where is the edge / best bet", wants to see trending or most-active markets, asks about a specific market''s price/liquidity/spread, or invokes /polymtrx or mentions MTRX / Polymtrx / PolyMatrix. Not for placing trades, wallet operations, or non-Polymarket markets.'
argument-hint: 'polymtrx scan "fed rate cut" | polymtrx trending | polymtrx market <slug> | polymtrx scan bitcoin --no-clob'
allowed-tools: Bash, Read, WebSearch, AskUserQuestion
license: MIT
user-invocable: true
metadata:
  type: reference
  inspired-by: MTRX (@Polymtrx) on X — the "prediction markets + AI to find the best opportunities" idea
  engine: scripts/polymtrx.py
  tags:
    - polymarket
    - prediction-markets
    - opportunity-scanner
    - odds
    - trading-signals
    - engagement-ranked
    - read-only
    - no-key
    - zero-cost
---

# /polymtrx

## Overview

`/polymtrx` answers **"where is the best opportunity on Polymarket right now?"**
It reproduces the MTRX / @Polymtrx (PolyMatrix) workflow — *prediction markets +
signal analysis to surface the best opportunities* — as a deterministic engine
that pulls **live** Polymarket data, scores each market on tradeable-edge
signals, and hands back the raw numbers for the agent to reason over.

This is a **research + signal contract**, not a keyword to improvise against.
Always run the engine (never answer Polymarket odds from memory — they move by
the minute). Then synthesize.

> **Provenance note.** The seed idea is the tweet at
> `x.com/polymtrx/status/2076318987441357033`. X paywalls automated reads, so
> the exact technique in that specific post could not be captured verbatim; this
> skill implements the confirmed workflow category (Polymarket opportunity
> intelligence). If the source describes a sharper, more specific method,
> tighten `scripts/polymtrx.py`'s scoring to match — the scaffold is built to be
> refined, not frozen.

## HARD RAIL — read-only

The engine **only fetches public market data**. It never places an order, never
touches a wallet / private key / CLOB credential, and never signs anything.
Surfacing an opportunity is the whole job; deciding and acting is a human's (or a
separately-gated step's). Do not extend this skill to auto-trade.

## Cost

**$0 (local).** Every call hits Polymarket's free public endpoints (Gamma +
CLOB). No API keys. State `$0 (local)` when reporting results, per Steve's
always-show-costs rule.

## Workflow

### Step 1 — pick the command
| Intent | Command |
| --- | --- |
| Opportunities on a **topic** ("fed", "election", "bitcoin", a team) | `scan "<topic>"` |
| **Most active** markets right now, no topic | `trending` |
| Deep detail on **one** market (price, liquidity, spread, timing) | `market <slug-or-id>` |
| Are the endpoints healthy? | `doctor` |

### Step 2 — run the engine
```bash
python3 scripts/polymtrx.py scan "fed rate cut" --limit 12
python3 scripts/polymtrx.py trending --emit markdown
python3 scripts/polymtrx.py market fed-decision-in-july-181
python3 scripts/polymtrx.py scan "election" --no-clob   # faster, skips order-book depth
```
- `--emit markdown` for a human-readable brief; default `json` for machine consumption / chaining.
- `--no-clob` skips the per-market order-book round-trip (faster; loses live spread/depth refinement).
- `--limit N` caps how many ranked markets come back (default 12).

The `market` command resolves a **market slug**, a **numeric id**, or falls back
to an **event slug** (returns all of that event's markets). Slugs come from any
Polymarket URL: `polymarket.com/event/<event-slug>`.

### Step 3 — read the opportunity score
Each market gets an `opportunity` score 0–100, blended from six signals (each
0–1), and a `signals` breakdown so the reasoning is transparent:

| Signal | Weight | Means |
| --- | --- | --- |
| `volume` | 0.30 | real money traded — conviction / it matters |
| `timing` | 0.20 | near resolution — the edge window is concrete (0–45d) |
| `contest` | 0.20 | price near 50/50 on a live binary — genuinely undecided |
| `liquidity` | 0.15 | order-book depth + tight spread — you can actually get filled |
| `movement` | 0.10 | |24h price change| — momentum / news just hit |
| `longshot` | 0.05 | price hugging 0/1 — potential mispriced tail |

Tune weights/thresholds in `scripts/polymtrx.py` (`WEIGHTS` + `score_market`) if
the ranking needs to bias differently (e.g. weight `movement` higher for a
news-reaction lens).

### Step 4 — synthesize
Do not just dump the JSON. Read the top markets and write a short grounded brief:
which markets carry real money, what the current odds imply, where the price
looks contestable vs. where it's a longshot, and **always cite the market URL**.
Flag when a top-scorer resolves in `0d` (score is inflated by imminent timing —
the edge may already be priced in).

## When to use / not use
- **Use** for: "what's Polymarket saying about X", "prediction-market odds on Y",
  "where's the edge", "trending markets", a specific market's price/liquidity,
  `/polymtrx`, or any mention of MTRX / Polymtrx / PolyMatrix.
- **Do not use** for: placing trades, wallet/key operations, non-Polymarket
  markets (Kalshi → the `Ken` project), or evergreen facts.

## Resources
- `scripts/polymtrx.py` — the zero-dependency engine (fetch → normalize → score
  → rank → emit). Runnable standalone; also readable/patchable for tuning.
- `references/api.md` — the public Polymarket endpoints used, their shapes, and
  the field-coercion gotchas (JSON-encoded price arrays, string volumes).