skills-ws 1.5.5 → 1.6.1

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.1",
+  "description": "85 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,495 @@
+#!/usr/bin/env node
+import os from 'os';
+/**
+ * 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 ${os.userInfo().username} -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);
+});

package/skills/reddit-community-engagement/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: reddit-community-engagement
+description: Safer Reddit community engagement for researching subreddits, scanning relevant threads, checking rules, drafting helpful replies, deciding when to skip, and documenting outcomes. Use when work involves Reddit outreach, community participation, response drafting, moderation-risk checks, or planning brand-safe participation in subreddit discussions. Trigger on requests about Reddit growth, Reddit engagement, subreddit outreach, thread scanning, reply drafting, or posting guidance.
+---
+
+# Reddit Community Engagement
+
+Use Reddit to be useful first. Prefer **read** and **draft** modes. Use **post** mode only when the user explicitly wants it and subreddit rules allow it.
+
+## Operating modes
+
+- **Read mode**: research subreddits, find relevant threads, summarize themes, capture rules, recommend whether to engage.
+- **Draft mode**: prepare reply options for human review. This is the default for anything external-facing.
+- **Post mode**: only after explicit user approval when rules, disclosure needs, and tone are all clear.
+
+If anything is ambiguous, stay in read/draft mode.
+
+## Non-negotiables
+
+- Do not pretend to be an ordinary user if you are acting for a company, client, or product.
+- Do not invent personal experience, results, customers, or usage.
+- Do not hide affiliation when disclosure is appropriate or required.
+- Do not mass-post, reuse near-identical comments, or force product mentions into weak-fit threads.
+- Do not argue with moderators. If content is removed or warned on, pause and reassess.
+
+## Before engaging
+
+Capture these basics:
+
+- Product / client:
+- What it does in one sentence:
+- Who it helps:
+- Allowed disclosure language:
+- Target subreddits or themes:
+- Keywords / pain points to scan:
+- Current mode: read / draft / post
+
+If representing a brand, state it plainly in drafts when relevant, e.g. “I work on X” or “I’m with X.”
+
+## Account readiness
+
+Warm up accounts through normal participation, not manipulation:
+
+- Build a history of on-topic, non-promotional participation before any outreach.
+- Prefer genuine comments in communities you expect to revisit.
+- Keep early activity light and human-paced.
+- Avoid links or product mentions until the account has normal-looking participation and you understand each subreddit’s norms.
+- If the account is new, low-karma, or has removals, favor read mode or draft mode.
+
+## Rule and risk check
+
+Before drafting any reply for a subreddit, verify:
+
+1. Sidebar / about / pinned rules
+2. Whether self-promotion, links, surveys, or company participation are restricted
+3. Whether user flair, account age, or karma minimums are required
+4. Whether the thread is asking for recommendations, troubleshooting help, comparison advice, or something unrelated
+5. Whether a reply from a brand rep would feel additive or intrusive
+
+## Decide: reply, value-only, or skip
+
+### Strong candidates
+
+- The post clearly matches the product’s use case or expertise
+- The user is asking for help, recommendations, or tool comparisons
+- The subreddit allows this kind of participation
+- You can answer the actual question even without mentioning the product
+
+### Value-only candidates
+
+- The thread is relevant but promo rules are strict
+- A direct answer helps, but mentioning the product adds risk
+- Disclosure is still needed if speaking as a representative
+
+### Skip immediately
+
+- Rules ban self-promo, brand accounts, or links and the reply would clearly be promotional
+- The thread is grief-heavy, legal/medical/high-risk, hostile, or moderation-sensitive
+- The product is only loosely relevant
+- Another reply would be repetitive, opportunistic, or defensive
+- You cannot be honest about affiliation without hurting trust or breaking norms
+
+When in doubt, skip.
+
+## Drafting guidance
+
+Write like a helpful participant, not an ad.
+
+- Answer the question first
+- Keep it specific to the post
+- Use plain language; avoid slogans, hype, or CTA-heavy phrasing
+- Mention the product only if it is genuinely useful and allowed
+- Prefer no link unless the thread, rules, and user intent clearly support it
+- If affiliated, disclose briefly and naturally
+- Offer next-step help without pressure
+
+## Simple reply pattern
+
+1. Acknowledge the exact problem
+2. Give 1–3 practical points that help on their own
+3. If appropriate, add a brief disclosed mention of the product
+4. End with a low-pressure offer or clarifying question
+
+## Draft output format
+
+For each candidate thread, produce:
+
+- **Thread**: title + URL
+- **Subreddit**:
+- **Intent**: what the user seems to need
+- **Rules / risk**: short note
+- **Recommendation**: reply / value-only / skip
+- **Why**: one or two sentences
+- **Draft reply**: only for reply or value-only
+- **Disclosure note**: exact wording if needed
+
+## Posting checklist
+
+Only in explicit post mode:
+
+- User approved the draft
+- Rules were checked in this session
+- Disclosure wording is appropriate
+- No copied text from another thread
+- Pace is conservative; avoid bursts
+- Log the outcome after posting or attempted posting
+
+## Outcome logging
+
+After a session, record a short summary with:
+
+- Date
+- Mode used
+- Subreddits reviewed
+- Threads scanned
+- Drafts prepared
+- Posts actually made
+- Skips and why
+- Any removals, warnings, or rule changes noticed
+- Recommended next step
+
+## Good defaults
+
+- Default to draft mode
+- Default to no link
+- Default to skip over borderline cases
+- Default to transparency over cleverness