skills-ws 1.5.5 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "skills-ws",
-  "version": "1.5.5",
-  "description": "83 agent skills for AI coding assistants \u2014 marketing, growth, web3, dev, design & operations. Built for OpenClaw, Claude Code, Cursor, and Codex.",
+  "version": "1.6.0",
+  "description": "84 agent skills for AI coding assistants \u2014 marketing, growth, web3, dev, design & operations. Built for OpenClaw, Claude Code, Cursor, and Codex.",
   "scripts": {
     "test": "node test/cli.test.mjs"
   },

package/skills/polymarket-trading/SKILL.md

@@ -1,411 +1,244 @@
 ---
-name: polymarket-trading
-description: Polymarket prediction market trading — market analysis, edge calculation, bookmaker cross-referencing, order placement via CLOB API, position management, and redemption. Covers sports betting strategy, risk management, and the full Polymarket SDK workflow.
-version: 1.0.0
+name: polymarket
+description: >
+  Sports betting on Polymarket prediction markets. Scan bookmaker odds via The Odds API,
+  find high-conviction favorites (>70% implied probability), match to Polymarket markets,
+  and execute trades for better payouts than traditional bookmakers. Use when asked about
+  "polymarket", "sports betting", "place a bet", "scan for bets", "check my positions",
+  "redeem bets", "NBA odds", "football odds", "betting picks", or "what should I bet on".
 ---
 
-# Polymarket Trading
+# Polymarket Sports Betting
 
-Complete framework for analyzing, trading, and managing positions on Polymarket — the world's largest prediction market.
+## ⚠️ CRITICAL RULES (Non-Negotiable)
 
-## Table of Contents
+1. **SPORTS ONLY** — Never bet on crypto, politics, or geopolitics. Crypto markets are manipulated by insiders.
+2. **Favorites only** — Minimum **70% implied probability on bookmakers** (averaged across 20+ books via The Odds API).
+3. **No long shots** — Ever. Long shots = money pit.
+4. **The best trade is sometimes no trade** — If nothing qualifies, say so.
+5. **Every bet must be high conviction** — Target 70%+ win rate across all bets.
+6. **Verify Polymarket availability** — Many matches aren't listed on PM. Never recommend a bet without confirming the PM market exists and resolving the token ID.
+7. **Football 3-way markets are harder** — PM splits win/draw/lose probability differently than bookmakers. Flag this to the user.
 
-1. [Market Analysis Framework](#market-analysis-framework)
-2. [Edge Calculation](#edge-calculation)
-3. [Bookmaker Cross-Referencing](#bookmaker-cross-referencing)
-4. [Risk Management Rules](#risk-management-rules)
-5. [APIs & Data Sources](#apis--data-sources)
-6. [Trading via CLOB](#trading-via-clob)
-7. [Position Management & Redemption](#position-management--redemption)
-8. [Understanding Polymarket Mechanics](#understanding-polymarket-mechanics)
-9. [Common Pitfalls](#common-pitfalls)
+## Wallet & Keys
 
----
-
-## Market Analysis Framework
+- **Address:** `0xCa5e2a326DE9544EAe2810E3f0E4e1d4Cef1847b`
+- **Chain:** Polygon (USDC.e)
+- **Positions API:** `https://data-api.polymarket.com/positions?user=0xCa5e2a326DE9544EAe2810E3f0E4e1d4Cef1847b`
+- **Keys:** macOS Keychain, account `stuart`:
+  - `polymarket-wallet-key`, `polymarket-api-key`, `polymarket-api-secret`, `polymarket-api-passphrase`
+  - `odds-api-key` (The Odds API)
 
-### The Scan Pipeline
+## Supported Sports
 
-For every potential bet, follow this pipeline in order:
-
-```
-1. Polymarket prices → identify markets with volume > $10K
-2. Filter → bookmaker favorites > 65% implied probability
-3. Injury/news check → any material changes not priced in?
-4. Form & H2H analysis → recent performance, matchup history
-5. Cross-reference 3+ bookmaker sources → calculate true probability
-6. Calculate edge → only bet if edge > 10% vs Polymarket price
-7. Size the bet → based on edge magnitude and bankroll
-```
+| The Odds API Key | Sport |
+|---|---|
+| `basketball_nba` | NBA |
+| `soccer_epl` | English Premier League |
+| `soccer_spain_la_liga` | La Liga |
+| `soccer_italy_serie_a` | Serie A |
+| `soccer_germany_bundesliga` | Bundesliga |
+| `soccer_france_ligue_one` | Ligue 1 |
+| `soccer_efl_champ` | EFL Championship |
 
-### Market Selection Criteria
+## Scripts
 
-**Good markets:**
-- High volume (> $10K) — ensures liquidity for entry and exit
-- Near-term resolution (days, not months) — capital efficiency
-- Binary outcomes with clear resolution criteria
-- Markets where bookmaker odds exist for cross-referencing
+All scripts are in the skill directory: `~/.agents/skills/polymarket/`
 
-**Bad markets:**
-- Low liquidity (< $5K volume) — wide spreads eat your edge
-- Subjective resolution criteria — dispute risk
-- Markets with insider information advantage (crypto governance, company decisions)
-- Long-dated futures that tie up capital for months
+| Script | Purpose | Auth Required |
+|---|---|---|
+| `scripts/scan.mjs` | Scan odds → filter → match PM → present picks | No (read-only) |
+| `polymarket.mjs` | Query PM markets (search, price, book, spread) | No |
+| `trade.mjs` | Place buy/sell orders on PM | Yes |
+| `redeem.mjs` | Redeem resolved winning positions | Yes |
 
 ---
 
-## Edge Calculation
+## Workflow
 
-### The Math
+### Step 1: SCAN — Fetch Bookmaker Odds
 
-```
-Bookmaker Implied Probability = 1 / Decimal Odds
-Edge = (True Probability - Polymarket Price) / Polymarket Price × 100
+Run the scan script to find qualifying bets:
 
-Example:
-  Bookmaker odds: -225 (decimal 1.44) → Implied probability: 69.4%
-  Polymarket price: $0.645 (64.5%)
-  Edge = (69.4 - 64.5) / 64.5 × 100 = 7.6%
-```
+```bash
+# Scan all sports
+node ~/.agents/skills/polymarket/scripts/scan.mjs --all-sports
 
-### American Odds to Probability
+# Single sport
+node ~/.agents/skills/polymarket/scripts/scan.mjs --sport=basketball_nba
 
+# Custom probability threshold
+node ~/.agents/skills/polymarket/scripts/scan.mjs --all-sports --min-prob=0.75
 ```
-Negative odds (favorites):  Probability = |odds| / (|odds| + 100)
-  -225 → 225 / 325 = 69.2%
 
-Positive odds (underdogs):  Probability = 100 / (odds + 100)
-  +150 → 100 / 250 = 40.0%
-```
+The script:
+1. Fetches odds from The Odds API (h2h market, EU region, decimal format)
+2. Calculates implied probability per team (average of `1/decimal_odds` across all bookmakers)
+3. Filters to favorites above the threshold (default 70%)
+4. Searches Polymarket for matching moneyline markets
+5. Resolves the correct token ID for each favorite outcome
+6. Fetches current PM price
+7. Outputs a table with: Game, Favorite, Book Prob, PM Price, Edge, Token ID, Kickoff
 
-### Removing the Vig
+**Validation gate:** If the script returns no picks, stop. Tell the user "No qualifying bets today." Do not lower the threshold.
 
-Bookmaker odds include a margin (vig). To get true probabilities:
-
-```
-1. Convert both sides to implied probabilities
-2. Sum them (will be > 100%, e.g., 105%)
-3. Divide each by the sum to normalize to 100%
-
-Example:
-  Team A: -200 → 66.7%    Team B: +170 → 37.0%
-  Sum: 103.7%
-  True A: 66.7 / 103.7 = 64.3%
-  True B: 37.0 / 103.7 = 35.7%
-```
-
-### Edge Thresholds
-
-| Edge | Action |
-|------|--------|
-| < 5% | Skip — too thin, transaction costs eat it |
-| 5-10% | Marginal — only if very high conviction + multiple sources agree |
-| **> 10%** | **Target zone — place the bet** |
-| > 20% | Strong edge — size up, but verify it's not a trap (news you missed?) |
-
----
+### Step 2: REVIEW — Validate Picks
 
-## Bookmaker Cross-Referencing
+Before presenting to the user, validate each pick:
 
-### Why Cross-Reference?
+1. **Book probability ≥ 70%** — Reconfirm the threshold is met
+2. **PM market exists** — Token ID was resolved (not `N/A`)
+3. **Edge is reasonable** — `Edge = Book Probability - PM Price`. Positive edge means PM is cheaper than books. Near-zero or negative edge is still fine (PM has better payouts than bookmakers regardless).
+4. **Game hasn't started** — Check kickoff time vs current time
+5. **Football 3-way caveat** — If it's a football match, note that draw probability affects the moneyline odds
 
-Polymarket prices are set by traders, not oddsmakers. They systematically:
-- **Overvalue favorites** by 3-7% in major sports markets
-- **Undervalue underdogs/draws** in 3-way football markets
-- **Lag behind** sharp bookmaker lines by hours
+**Validation gate:** Remove any picks where token ID is `N/A` or the game has already started.
 
-### Sources to Cross-Reference
+### Step 3: PRESENT — Show Picks to User
 
-| Source | Use | Notes |
-|--------|-----|-------|
-| **Pinnacle** | Sharpest lines globally | Gold standard, lowest vig |
-| **Bet365** | Popular, liquid markets | Good for mainstream sports |
-| **DraftKings/FanDuel** | US sports | NFL, NBA, MLB, NHL |
-| **Betfair Exchange** | True market prices | No vig, just commission |
-| **OddsPortal/OddsChecker** | Aggregators | Compare across 20+ books |
-| **Action Network** | Analysis + odds | Good injury/form context |
+Present qualifying picks in a clean format:
 
-### The 3-Source Rule
-
-Never bet based on a single bookmaker. Always confirm with **3+ independent sources**:
-
-```
-✅ Good: Pinnacle -220, Bet365 -225, DraftKings -215 → consensus ~69%
-   Polymarket at 60¢ → 15% edge → BET
-
-❌ Bad: Only one bookmaker has odds, others don't list the market
-   → Information asymmetry, you might be wrong
 ```
+🏀 NBA Picks — March 8, 2026
 
----
-
-## Risk Management Rules
-
-### Bankroll Management
+| Game | Pick | Book Prob | PM Price | Edge | Kickoff |
+|------|------|-----------|----------|------|---------|
+| BOS vs WAS | Boston Celtics | 88.2% | 0.87 | +1.2% | 19:00 ET |
+| LAL vs DET | LA Lakers | 74.5% | 0.73 | +1.5% | 21:30 ET |
 
-```
-Max single bet:     10% of bankroll
-Typical bet size:   2-5% of bankroll
-Max daily exposure: 25% of bankroll
+Token IDs:
+- Boston Celtics: 123456789...
+- LA Lakers: 987654321...
 ```
 
-### Hard Rules
+Include:
+- The sport and date
+- Clear table of picks
+- Token IDs for execution
+- Any caveats (football 3-way, low liquidity)
+- **Ask for explicit approval before executing any trade**
 
-1. **Sport only** — No crypto, politics, or geopolitics bets. Crypto markets are manipulated by insiders.
-2. **Only heavy favorites** — Bookmaker implied probability > 65%
-3. **Edge > 10%** — No exceptions for "gut feelings"
-4. **3+ sources minimum** — Cross-reference before every bet
-5. **No long shots** — Underdogs and parlays are money pits
-6. **The best trade is sometimes no trade** — Don't force action
+### Step 4: EXECUTE — Place Trades
 
-### When NOT to Bet
+After user approval, execute trades using `trade.mjs`:
 
-- Market is illiquid (< $5K volume, wide spreads)
-- News is breaking and odds haven't settled
-- You can't find 3 bookmakers listing the event
-- The edge comes from a single outlier source
-- You're chasing losses from a previous bet
-- Resolution criteria are ambiguous
+```bash
+# Buy $50 on Boston Celtics at 0.87
+node ~/.agents/skills/polymarket/trade.mjs buy <token_id> 0.87 50
+```
 
-### Track Record Requirements
+**Parameters:**
+- `token_id` — From the scan output
+- `price` — The PM price (or slightly above for guaranteed fill)
+- `size` — Dollar amount to bet
 
-- Target **80%+ win rate** on individual bets
-- If below 60% over 10+ bets, stop and re-evaluate strategy
-- Log every bet: market, entry price, bookmaker consensus, edge, result
+**Validation gate:** Always confirm with the user before executing. Show the exact command that will run.
 
----
+**Post-execution:** Show the order response. If the order is rejected, explain why (insufficient balance, price moved, etc.).
 
-## APIs & Data Sources
+### Step 5: TRACK — Monitor Positions
 
-### Gamma API (Public, No Auth)
+Check current positions:
 
-Market discovery and search. Base: `https://gamma-api.polymarket.com`
+```bash
+# Via Data API
+curl "https://data-api.polymarket.com/positions?user=0xCa5e2a326DE9544EAe2810E3f0E4e1d4Cef1847b"
 
-```
-GET /public-search?q=<query>             — Search markets/events
-GET /events?active=true&closed=false      — List active events
-GET /events?tag_slug=<slug>               — Events by category (sports, politics, crypto)
-GET /markets?slug=<slug>                  — Market details by slug
-GET /tags                                  — All available categories
+# Or via trade.mjs
+node ~/.agents/skills/polymarket/trade.mjs balances
 ```
 
-**Key response fields:**
-- `outcomePrices` — Current Yes/No prices (JSON string, parse it)
-- `clobTokenIds` — Token IDs needed for CLOB trading (JSON string)
-- `volume` — Total dollar volume traded
-- `negRisk` — If true, uses negRisk contract (multi-outcome markets)
-- `groupItemTitle` — The outcome name in grouped markets
+Check open orders:
 
-### CLOB API (Public reads, Auth for trading)
-
-Order book and trading. Base: `https://clob.polymarket.com`
-
-```
-# Public (no auth)
-GET /midpoint?token_id=<id>              — Midpoint price
-GET /book?token_id=<id>                  — Full order book
-GET /spread?token_id=<id>               — Bid-ask spread
-GET /price?token_id=<id>&side=buy|sell  — Best available price
-GET /tick-size?token_id=<id>            — Min price increment
-
-# Authenticated (requires L2 API key)
-POST /order                              — Place order
-DELETE /order/<id>                       — Cancel order
-GET /orders                              — Open orders
-GET /balances                            — CLOB balances
+```bash
+node ~/.agents/skills/polymarket/trade.mjs orders
 ```
 
-### Data API (Public, No Auth)
+### Step 6: REDEEM — Collect Winnings
 
-Positions and history. Base: `https://data-api.polymarket.com`
+After markets resolve, redeem winning positions:
 
+```bash
+node ~/.agents/skills/polymarket/redeem.mjs
 ```
-GET /positions?user=<wallet_address>     — All positions for a wallet
-GET /trades?user=<wallet_address>        — Trade history
-```
-
-### Authentication Model
 
-Two-layer auth system:
-- **L1 (Wallet Signature)**: EIP-712 signature from your Polygon wallet — used to derive API credentials
-- **L2 (API Key)**: HMAC-SHA256 headers for all trading operations
-
-**Headers for authenticated requests:**
-```
-POLY_ADDRESS      — Wallet address
-POLY_SIGNATURE    — HMAC signature of request
-POLY_TIMESTAMP    — Unix timestamp
-POLY_NONCE        — Request nonce
-POLY_API_KEY      — Your API key
-POLY_PASSPHRASE   — Your passphrase
-POLY_SECRET       — Your API secret (used for HMAC)
-```
+The script automatically:
+- Finds all redeemable positions
+- Handles both standard and negativeRisk markets
+- Redeems via CTF contract on Polygon
+- Reports the new USDC.e balance
 
 ---
 
-## Trading via CLOB
-
-### Using the TypeScript SDK
+## Error Handling
 
-```javascript
-const { ClobClient, Side } = require('@polymarket/clob-client');
-const { Wallet } = require('ethers');
+### Common Issues
 
-// Initialize client
-const wallet = new Wallet(PRIVATE_KEY);
-const client = new ClobClient(
-  'https://clob.polymarket.com',
-  137, // Polygon chainId
-  wallet,
-  creds // { apiKey, secret, passphrase }
-);
+| Error | Cause | Fix |
+|---|---|---|
+| `security: SecItemCopyMatching` | Keychain access denied | Run in terminal with Keychain access, or unlock Keychain |
+| `HTTP 401` from Odds API | Invalid/expired API key | Check `security find-generic-password -s odds-api-key -a stuart -w` |
+| `HTTP 429` from Odds API | Rate limited (500 req/month free tier) | Wait, or check remaining quota in response headers |
+| Token ID `N/A` | PM doesn't have this market | Skip this pick — common for smaller football matches |
+| `No results` from PM search | Team name mismatch | Try alternate team names or search manually via `polymarket.mjs search` |
+| Order rejected | Price moved or insufficient USDC.e | Check balance, adjust price, retry |
+| `NONCE_TOO_LOW` | Transaction nonce conflict | Wait 30s, retry |
+| Redeem fails | Gas price spike on Polygon | Retry with higher gas — script uses 500 gwei max fee |
 
-// Derive API credentials (first time)
-const creds = await client.createOrDeriveApiKey();
+### The Odds API Quota
 
-// Place a limit buy order
-const order = await client.createAndPostOrder({
-  tokenID: '<token_id>',  // From Gamma API clobTokenIds
-  price: 0.65,            // Max price willing to pay
-  size: 10,               // Dollar amount
-  side: Side.BUY,
-}, { tickSize: '0.01' });  // Check tick-size endpoint first
+The free tier has 500 requests/month. Each scan of one sport = 1 request. A full `--all-sports` scan = 7 requests. Be mindful:
+- Don't scan repeatedly in the same hour
+- Check `x-requests-remaining` header in responses
+- If close to limit, scan only the sport the user asks about
 
-// Cancel an order
-await client.cancelOrder(orderId);
+---
 
-// Get open orders
-const orders = await client.getOpenOrders();
-```
+## Examples
 
-### Order Flow
+### "Scan for bets today"
 
 ```
-1. Search market on Gamma → get slug
-2. Get market details → extract clobTokenIds and outcomePrices
-3. Identify the outcome you want (Yes token ID vs No token ID)
-4. Check tick-size for that token
-5. Check current best price: GET /price?token_id=X&side=buy
-6. Place limit order at your target price
-7. Monitor: GET /orders to check if filled
+1. Run: node ~/.agents/skills/polymarket/scripts/scan.mjs --all-sports
+2. Review output for qualifying picks
+3. Present picks table to user
+4. Wait for approval before trading
 ```
 
-### Token ID Selection
-
-Grouped markets (like "Who wins UFC 326?") have multiple outcomes. Each outcome has a Yes and No token:
+### "Bet $100 on the Celtics"
 
 ```
-Market: "UFC 326 Main Event"
-  Outcome: "Max Holloway"
-    → Yes Token ID: 7068099725...  (buy this if you think Holloway wins)
-    → No Token ID:  1293847561...  (buy this if you think Holloway loses)
-  Outcome: "Charles Oliveira"
-    → Yes Token ID: 8843920183...
-    → No Token ID:  5567382910...
+1. Search PM for the Celtics game: node ~/.agents/skills/polymarket/polymarket.mjs search "Celtics"
+2. Find the moneyline market and resolve the token ID for the Celtics outcome
+3. Get current price: node ~/.agents/skills/polymarket/polymarket.mjs price <token_id>
+4. Cross-check bookmaker odds to confirm >70% implied probability
+5. Present the trade: "Buy $100 on Celtics at 0.XX (PM), books have them at YY%"
+6. After approval: node ~/.agents/skills/polymarket/trade.mjs buy <token_id> <price> 100
 ```
 
-The Gamma API returns `clobTokenIds` as a JSON string with `[NoTokenId, YesTokenId]` — **index 1 is Yes**.
-
----
-
-## Position Management & Redemption
-
-### Checking Positions
+### "Check my positions"
 
 ```
-GET https://data-api.polymarket.com/positions?user=<wallet_address>
+1. Fetch: curl "https://data-api.polymarket.com/positions?user=0xCa5e2a326DE9544EAe2810E3f0E4e1d4Cef1847b"
+2. Show open positions with current value
+3. If any are redeemable: node ~/.agents/skills/polymarket/redeem.mjs
 ```
 
-Returns all current positions with:
-- `asset` — Token ID
-- `size` — Number of shares
-- `avgPrice` — Average entry price
-- `currentPrice` — Current market price
-- `pnl` — Unrealized P&L
-
-### Redeeming Resolved Positions
+### "What are the odds on Real Madrid?"
 
-When a market resolves, winning shares are worth $1.00. You need to call the contract to redeem:
-
-**Standard markets** (2-outcome, `negRisk: false`):
-```javascript
-// Call ConditionalTokens contract: redeemPositions()
-const CTF_ADDRESS = '0x4D97DCd97eC945f40cF65F87097ACe5EA0476045';
 ```
-
-**NegRisk markets** (multi-outcome, `negRisk: true`):
-```javascript
-// Call NegRiskAdapter: redeemPositions()
-const NEG_RISK_ADAPTER = '0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296';
-// Also call NegRiskCTFExchange for conversion
-const NEG_RISK_EXCHANGE = '0xC5d563A36AE78145C45a50134d48A1215220f80a';
+1. Scan La Liga: node ~/.agents/skills/polymarket/scripts/scan.mjs --sport=soccer_spain_la_liga
+2. Find Real Madrid in results
+3. If they qualify (>70%), present as a pick
+4. If they don't qualify, show the odds but warn it's below threshold
 ```
 
-### Exit Strategies
-
-- **Winner**: Hold until resolution → redeem at $1.00
-- **Cut losses**: Sell on the CLOB if the market moves against you
-- **Take profit**: If price moved significantly in your favor before resolution, consider selling early to lock in gains and free capital
-
 ---
 
-## Understanding Polymarket Mechanics
-
-### How Prices Work
-
-- Prices = probabilities ($0.65 = market says 65% chance of Yes)
-- Markets resolve to $1.00 (correct outcome) or $0.00 (incorrect)
-- Your profit = $1.00 - entry price (per share, if you win)
-- Your loss = entry price (per share, if you lose)
-
-### Where Polymarket Misprices
-
-| Pattern | Why | How to Exploit |
-|---------|-----|----------------|
-| Favorites overvalued by 3-7% | Retail bias toward "safe" bets | Compare vs sharp bookmaker lines |
-| Underdogs/draws undervalued | People avoid complexity | 3-way football markets (win/draw/lose) |
-| Slow to react to news | Traders aren't 24/7 | Fast reaction to injury reports, lineups |
-| Low-volume markets inefficient | Not enough informed traders | Small edges in niche markets |
-
-### Polymarket vs Bookmakers
-
-| Feature | Polymarket | Traditional Bookmaker |
-|---------|-----------|----------------------|
-| Vig/margin | 0% (peer-to-peer) | 3-10% |
-| Liquidity | Variable | Guaranteed |
-| Resolution | Smart contract | Bookmaker decides |
-| Settlement | USDC on Polygon | Fiat |
-| Edge | Retail-driven inefficiencies | Sharp lines, hard to beat |
-
-### Chain Details
-
-- **Chain**: Polygon (MATIC for gas, USDC.e for trading)
-- **USDC.e contract**: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
-- **Note**: Polymarket uses USDC.e (bridged), NOT native USDC
-- **Geo**: Restricted in some countries (US blocked, most of EU is fine)
-
----
+## Key Concepts
 
-## Common Pitfalls
-
-### ❌ Mistakes to Avoid
-
-1. **Betting on crypto/politics markets** — Insider manipulation is rampant (project teams, whale wallets, political operatives)
-2. **Chasing long shots** — A 5¢ token that could pay $1 sounds amazing; it almost never hits
-3. **Ignoring liquidity** — A "great price" means nothing if you can't exit
-4. **Single-source analysis** — One bookmaker can be wrong; always cross-reference
-5. **Overexposure** — Never have > 25% of bankroll in active bets
-6. **Ignoring the vig** — Bookmaker odds include margin; remove it before comparing
-7. **Trading illiquid markets** — Wide spreads (> 5¢) silently destroy your edge
-8. **Holding long-dated positions** — Capital is locked; shorter resolution = better capital efficiency
-9. **Not tracking results** — Without a log, you can't evaluate if your strategy works
-10. **Emotional trading** — If you just lost, don't immediately place another bet
-
-### ✅ Habits of Profitable Traders
-
-1. Systematic scan pipeline for every bet (not ad-hoc)
-2. Spreadsheet tracking all bets with entry, target, result, edge
-3. Walk away when there's no edge — most days have no good bets
-4. Focus on 1-2 sports you know deeply rather than spreading thin
-5. Check injury reports, team news, and lineup confirmations before betting
-6. Review win/loss ratio monthly and adjust thresholds if needed
+- **Implied probability:** `1 / decimal_odds` — averaged across all bookmakers for consensus
+- **Edge:** `Book Probability - PM Price` — positive means PM is cheaper than fair value
+- **Why PM over bookmakers:** Better payouts (no vig baked in the same way), no KYC, instant settlement on Polygon
+- **This isn't arbitrage:** PM tracks fair value closely. The strategy is picking safe winners and benefiting from PM's superior payout structure
+- **Volume:** Bet size is unrestricted, but every bet must meet the conviction threshold

package/skills/polymarket-trading/scripts/scan.mjs

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+/**
+ * Polymarket Sports Betting Scanner
+ *
+ * Fetches bookmaker odds from The Odds API, filters to high-probability favorites,
+ * matches them to Polymarket markets, and outputs actionable picks.
+ *
+ * Usage:
+ *   node scripts/scan.mjs --sport=basketball_nba
+ *   node scripts/scan.mjs --all-sports
+ *   node scripts/scan.mjs --all-sports --min-prob=0.75
+ */
+
+import { execSync } from 'child_process';
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+const ODDS_API = 'https://api.the-odds-api.com/v4/sports';
+const GAMMA    = 'https://gamma-api.polymarket.com';
+const CLOB     = 'https://clob.polymarket.com';
+
+const SPORTS = [
+  'basketball_nba',
+  'soccer_epl',
+  'soccer_spain_la_liga',
+  'soccer_italy_serie_a',
+  'soccer_germany_bundesliga',
+  'soccer_france_ligue_one',
+  'soccer_efl_champ',
+];
+
+// Map Odds API sport keys to PM search tags / keywords
+const SPORT_META = {
+  basketball_nba:           { pmTag: 'nba', label: 'NBA', type: 'basketball' },
+  soccer_epl:               { pmTag: 'epl', label: 'EPL', type: 'soccer' },
+  soccer_spain_la_liga:     { pmTag: 'la-liga', label: 'La Liga', type: 'soccer' },
+  soccer_italy_serie_a:     { pmTag: 'serie-a', label: 'Serie A', type: 'soccer' },
+  soccer_germany_bundesliga:{ pmTag: 'bundesliga', label: 'Bundesliga', type: 'soccer' },
+  soccer_france_ligue_one:  { pmTag: 'ligue-1', label: 'Ligue 1', type: 'soccer' },
+  soccer_efl_champ:         { pmTag: 'efl-championship', label: 'EFL Champ', type: 'soccer' },
+};
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function getOddsApiKey() {
+  // Preferred: explicit env var (portable for Linux/CI/containers)
+  if (process.env.ODDS_API_KEY && process.env.ODDS_API_KEY.trim()) {
+    return process.env.ODDS_API_KEY.trim();
+  }
+
+  // Fallback: macOS Keychain for local developer setup
+  if (process.platform === 'darwin') {
+    try {
+      return execSync('security find-generic-password -s odds-api-key -a stuart -w', {
+        encoding: 'utf8',
+      }).trim();
+    } catch {}
+  }
+
+  throw new Error('Missing ODDS_API_KEY. Set environment variable ODDS_API_KEY (or use macOS keychain fallback).');
+}
+
+async function fetchJSON(url, { timeoutMs = 12000, retries = 2 } = {}) {
+  let lastErr;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const res = await fetch(url, {
+        headers: { Accept: 'application/json' },
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`HTTP ${res.status} from ${url}: ${body.slice(0, 200)}`);
+      }
+      return await res.json();
+    } catch (e) {
+      lastErr = e;
+      if (attempt < retries) {
+        await new Promise(r => setTimeout(r, 400 * (attempt + 1)));
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw lastErr;
+}
+
+function parseArgs() {
+  const opts = { sports: [], minProb: 0.70, allSports: false };
+  for (const a of process.argv.slice(2)) {
+    if (a === '--all-sports') opts.allSports = true;
+    else if (a.startsWith('--sport=')) opts.sports.push(a.split('=')[1]);
+    else if (a.startsWith('--min-prob=')) opts.minProb = parseFloat(a.split('=')[1]);
+    else if (a === '--help' || a === '-h') {
+      console.log(`Usage: scan.mjs [--sport=basketball_nba] [--all-sports] [--min-prob=0.70]`);
+      process.exit(0);
+    }
+  }
+  if (opts.allSports) opts.sports = [...SPORTS];
+  if (opts.sports.length === 0) opts.sports = [...SPORTS]; // default to all
+  return opts;
+}
+
+// ── Odds API ────────────────────────────────────────────────────────────────
+
+async function fetchOdds(sport, apiKey) {
+  // Filter to games starting from now until end of tomorrow (48h window)
+  const now = new Date();
+  const tomorrow = new Date(now);
+  tomorrow.setDate(tomorrow.getDate() + 2);
+  tomorrow.setHours(23, 59, 59, 999);
+
+  const params = new URLSearchParams({
+    apiKey,
+    regions: 'eu',
+    markets: 'h2h',
+    oddsFormat: 'decimal',
+    commenceTimeFrom: now.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+    commenceTimeTo: tomorrow.toISOString().replace(/\.\d{3}Z$/, 'Z'),
+  });
+
+  const url = `${ODDS_API}/${sport}/odds?${params}`;
+  try {
+    return await fetchJSON(url);
+  } catch (e) {
+    if (e.message.includes('429')) {
+      console.error(`⚠️  Rate limited on Odds API. Check your quota.`);
+      return [];
+    }
+    if (e.message.includes('404')) {
+      // Sport may have no upcoming events
+      return [];
+    }
+    throw e;
+  }
+}
+
+/**
+ * Calculate implied probability for each outcome by averaging 1/odds across bookmakers.
+ * Returns array of { team, impliedProb } sorted by probability descending.
+ */
+function calcImpliedProbabilities(game) {
+  const bookmakers = game.bookmakers || [];
+  if (bookmakers.length === 0) return [];
+
+  // Collect all h2h odds per outcome
+  const oddsMap = {}; // team -> [decimal_odds, ...]
+  for (const bm of bookmakers) {
+    const h2h = bm.markets?.find(m => m.key === 'h2h');
+    if (!h2h) continue;
+    for (const outcome of h2h.outcomes) {
+      if (!oddsMap[outcome.name]) oddsMap[outcome.name] = [];
+      oddsMap[outcome.name].push(outcome.price);
+    }
+  }
+
+  // Average implied probability per team
+  const results = [];
+  for (const [team, oddsList] of Object.entries(oddsMap)) {
+    const avgProb = oddsList.reduce((sum, o) => sum + 1 / o, 0) / oddsList.length;
+    results.push({ team, impliedProb: avgProb, numBooks: oddsList.length });
+  }
+
+  return results.sort((a, b) => b.impliedProb - a.impliedProb);
+}
+
+// ── Polymarket Matching ─────────────────────────────────────────────────────
+
+/**
+ * Normalize a team name for fuzzy matching.
+ */
+function normalize(name) {
+  return name
+    .toLowerCase()
+    .replace(/\bfc\b/g, '')
+    .replace(/\bsc\b/g, '')
+    .replace(/\bac\b/g, '')
+    .replace(/\brc\b/g, '')
+    .replace(/\bssc\b/g, '')
+    .replace(/\bas\b/g, '')
+    .replace(/\bcf\b/g, '')
+    .replace(/\bud\b/g, '')
+    .replace(/\brcd\b/g, '')
+    .replace(/\breal\b/g, 'real')
+    .replace(/\bunited\b/g, 'utd')
+    .replace(/\bcity\b/g, 'city')
+    .replace(/[^a-z0-9 ]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Check if two team names are a fuzzy match.
+ */
+function fuzzyMatch(a, b) {
+  const na = normalize(a);
+  const nb = normalize(b);
+  // Exact
+  if (na === nb) return true;
+  // One contains the other
+  if (na.includes(nb) || nb.includes(na)) return true;
+  // Last word match (e.g. "Lens" in "Racing Club de Lens")
+  const wordsA = na.split(' ');
+  const wordsB = nb.split(' ');
+  const lastA = wordsA[wordsA.length - 1];
+  const lastB = wordsB[wordsB.length - 1];
+  if (lastA.length >= 3 && lastA === lastB) return true;
+  // Check if any significant word (4+ chars) matches
+  for (const w of wordsA) {
+    if (w.length >= 4 && wordsB.includes(w)) return true;
+  }
+  return false;
+}
+
+/**
+ * Search Polymarket for a game and try to find a moneyline market.
+ * Returns { found, tokenId, pmPrice, marketQuestion, slug } or { found: false }
+ */
+async function findPMMarket(homeTeam, awayTeam, favoriteTeam, sportMeta) {
+  // Extract short team names (last word = mascot) for better PM search
+  const shortHome = homeTeam.split(' ').pop();
+  const shortAway = awayTeam.split(' ').pop();
+  const shortFav = favoriteTeam.split(' ').pop();
+
+  // Try multiple search strategies — short names first (avoid season-long market noise)
+  const searches = [
+    `${shortAway} ${shortHome}`,
+    `${shortHome} ${shortAway}`,
+    `${homeTeam} ${awayTeam}`,
+    shortFav,
+  ];
+
+  for (const query of searches) {
+    try {
+      const params = new URLSearchParams({ q: query, limit_per_type: '10' });
+      const data = await fetchJSON(`${GAMMA}/public-search?${params}`);
+      const events = data.events || [];
+
+      for (const ev of events) {
+        // Check if event title contains both teams or the favorite
+        const title = (ev.title || '').toLowerCase();
+        const hasHome = fuzzyMatch(ev.title || '', homeTeam);
+        const hasAway = fuzzyMatch(ev.title || '', awayTeam);
+        const hasFav = fuzzyMatch(ev.title || '', favoriteTeam);
+
+        if (!hasFav && !(hasHome && hasAway)) continue;
+
+        // Look through markets for a moneyline / winner market
+        const markets = (ev.markets || []).filter(m => !m.closed);
+        for (const m of markets) {
+          const q = (m.question || '').toLowerCase();
+          // Skip spread, total, player props, 1st half
+          if (/spread|total|over|under|points|1st half|first half|player|assists|rebounds|goals scored/i.test(q)) continue;
+
+          // Check if this is a "Will X win?" or "X vs Y" moneyline
+          if (fuzzyMatch(m.question || '', favoriteTeam) || q.includes('win') || q.includes('winner')) {
+            // Parse outcomes and find the favorite
+            const outcomes = typeof m.outcomes === 'string' ? JSON.parse(m.outcomes) : (m.outcomes || []);
+            const prices = m.outcomePrices ? (typeof m.outcomePrices === 'string' ? JSON.parse(m.outcomePrices) : m.outcomePrices) : [];
+            const clobIds = m.clobTokenIds ? (typeof m.clobTokenIds === 'string' ? JSON.parse(m.clobTokenIds) : m.clobTokenIds) : [];
+
+            // Find the outcome matching the favorite
+            for (let i = 0; i < outcomes.length; i++) {
+              const outcomeName = outcomes[i];
+              if (fuzzyMatch(outcomeName, favoriteTeam) || outcomeName.toLowerCase() === 'yes') {
+                const tokenId = clobIds[i] || null;
+                const price = prices[i] ? parseFloat(prices[i]) : null;
+
+                if (tokenId && price) {
+                  return {
+                    found: true,
+                    tokenId,
+                    pmPrice: price,
+                    marketQuestion: m.question,
+                    slug: m.slug || ev.slug,
+                    outcomeName,
+                  };
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (e) {
+      // Search failed, try next strategy
+      continue;
+    }
+
+    // Small delay between searches to be nice to the API
+    await new Promise(r => setTimeout(r, 300));
+  }
+
+  return { found: false };
+}
+
+/**
+ * Get the live midpoint price from CLOB for a token.
+ */
+async function getLivePrice(tokenId) {
+  try {
+    const data = await fetchJSON(`${CLOB}/midpoint?token_id=${tokenId}`);
+    return parseFloat(data.mid);
+  } catch {
+    return null;
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const opts = parseArgs();
+
+  // 1. Get API key
+  let apiKey;
+  try {
+    apiKey = getOddsApiKey();
+  } catch (e) {
+    console.error('❌ Failed to get Odds API key.');
+    console.error('   Set ODDS_API_KEY env var (or use macOS keychain fallback).');
+    process.exit(1);
+  }
+
+  console.log(`\n🔍 Scanning ${opts.sports.length} sport(s) | Min probability: ${(opts.minProb * 100).toFixed(0)}%\n`);
+
+  const picks = [];
+
+  for (const sport of opts.sports) {
+    const meta = SPORT_META[sport];
+    if (!meta) {
+      console.error(`⚠️  Unknown sport: ${sport}`);
+      continue;
+    }
+
+    process.stdout.write(`  📡 ${meta.label}... `);
+
+    // 2. Fetch odds
+    let games;
+    try {
+      games = await fetchOdds(sport, apiKey);
+    } catch (e) {
+      console.log(`❌ ${e.message}`);
+      continue;
+    }
+
+    if (!games || games.length === 0) {
+      console.log('no upcoming games');
+      continue;
+    }
+
+    console.log(`${games.length} game(s)`);
+
+    // 3. Calculate implied probabilities and filter
+    for (const game of games) {
+      const probs = calcImpliedProbabilities(game);
+      if (probs.length === 0) continue;
+
+      const favorite = probs[0];
+      if (favorite.impliedProb < opts.minProb) continue;
+
+      // This is a qualifying favorite
+      const homeTeam = game.home_team;
+      const awayTeam = game.away_team;
+      const kickoff = new Date(game.commence_time);
+
+      // Skip games that have already started
+      if (kickoff < new Date()) continue;
+
+      // 4. Search Polymarket
+      process.stdout.write(`    🔎 ${favorite.team} (${(favorite.impliedProb * 100).toFixed(1)}%)... `);
+
+      const pm = await findPMMarket(homeTeam, awayTeam, favorite.team, meta);
+
+      if (!pm.found) {
+        console.log('not on PM');
+        picks.push({
+          sport: meta.label,
+          game: `${homeTeam} vs ${awayTeam}`,
+          favorite: favorite.team,
+          bookProb: favorite.impliedProb,
+          numBooks: favorite.numBooks,
+          pmPrice: null,
+          edge: null,
+          tokenId: null,
+          kickoff,
+          isSoccer: meta.type === 'soccer',
+        });
+        continue;
+      }
+
+      // 5. Get live CLOB price (more accurate than Gamma cache)
+      const livePrice = await getLivePrice(pm.tokenId);
+      const pmPrice = livePrice || pm.pmPrice;
+
+      const edge = favorite.impliedProb - pmPrice;
+
+      console.log(`✅ PM: ${(pmPrice * 100).toFixed(1)}¢ | Edge: ${edge >= 0 ? '+' : ''}${(edge * 100).toFixed(1)}%`);
+
+      picks.push({
+        sport: meta.label,
+        game: `${homeTeam} vs ${awayTeam}`,
+        favorite: favorite.team,
+        bookProb: favorite.impliedProb,
+        numBooks: favorite.numBooks,
+        pmPrice,
+        edge,
+        tokenId: pm.tokenId,
+        kickoff,
+        marketQuestion: pm.marketQuestion,
+        isSoccer: meta.type === 'soccer',
+      });
+
+      // Rate limit protection
+      await new Promise(r => setTimeout(r, 200));
+    }
+  }
+
+  // ── Output ──────────────────────────────────────────────────────────────
+
+  console.log('\n' + '═'.repeat(120));
+
+  const matched = picks.filter(p => p.tokenId);
+  const unmatched = picks.filter(p => !p.tokenId);
+
+  if (matched.length === 0 && unmatched.length === 0) {
+    console.log('\n😐 No favorites above threshold found across all sports.');
+    console.log('   The best trade is sometimes no trade.\n');
+    process.exit(0);
+  }
+
+  if (matched.length > 0) {
+    console.log(`\n✅ ACTIONABLE PICKS (${matched.length})\n`);
+    console.log(
+      padR('Game', 40) +
+      padR('Pick', 24) +
+      padR('Books', 10) +
+      padR('PM', 8) +
+      padR('Edge', 8) +
+      padR('Kickoff', 18) +
+      'Token ID'
+    );
+    console.log('─'.repeat(120));
+
+    for (const p of matched) {
+      const kickStr = p.kickoff.toLocaleString('en-GB', {
+        month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
+        timeZone: 'Europe/Luxembourg',
+      });
+      const soccer3way = p.isSoccer ? ' ⚽' : '';
+      console.log(
+        padR(p.game, 40) +
+        padR(p.favorite + soccer3way, 24) +
+        padR(`${(p.bookProb * 100).toFixed(1)}%`, 10) +
+        padR(`${(p.pmPrice * 100).toFixed(1)}¢`, 8) +
+        padR(`${p.edge >= 0 ? '+' : ''}${(p.edge * 100).toFixed(1)}%`, 8) +
+        padR(kickStr, 18) +
+        p.tokenId
+      );
+    }
+
+    if (matched.some(p => p.isSoccer)) {
+      console.log('\n⚽ = Football 3-way market (win/draw/lose) — PM splits probability differently than bookmakers');
+    }
+
+    console.log('\n📋 To execute a trade:');
+    console.log('   node ~/.agents/skills/polymarket/trade.mjs buy <token_id> <price> <size>\n');
+  }
+
+  if (unmatched.length > 0) {
+    console.log(`\n⚠️  NOT ON POLYMARKET (${unmatched.length})\n`);
+    for (const p of unmatched) {
+      const kickStr = p.kickoff.toLocaleString('en-GB', {
+        month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
+        timeZone: 'Europe/Luxembourg',
+      });
+      console.log(`   ${padR(p.game, 40)} ${padR(p.favorite, 20)} ${(p.bookProb * 100).toFixed(1)}%  ${kickStr}`);
+    }
+    console.log('');
+  }
+}
+
+function padR(str, len) {
+  if (str.length >= len) return str.slice(0, len - 1) + ' ';
+  return str + ' '.repeat(len - str.length);
+}
+
+main().catch(e => {
+  console.error(`\n❌ Fatal: ${e.message}`);
+  process.exit(1);
+});