World Cup Head to Head Fixture Trader

Overview

Use this skill as a reusable playbook for World Cup fixture trading in ClawHub-compatible agents. It bundles two layers:

• a research layer that estimates win / draw / loss probabilities for matchup-style markets and can enrich them with FotMob-style pre-match context when match ids are available
• an execution layer that discovers the live market, validates the fixture, and decides whether to trade or pass

Supporting notes live in references/session-notes.md.

It turns a market idea into a disciplined bet-or-pass decision:

1. discover the current market at runtime
2. resolve a fresh market id
3. fetch market context
4. compare fair value to market price
5. trade only if the fixture mapping is trustworthy and the edge is meaningful
6. otherwise pass cleanly with a reason

The research and discovery layers share one team-normalization module, so alias fixes land once and apply everywhere.

The workflow is intentionally conservative. A stale market, wrong fixture, or unresolved context is more dangerous than missing a marginal edge.

Supporting files

• references/session-notes.md — bundled research/execution split, SDK compatibility fallback, and publishing lessons from this session.
• references/team-name-normalization.md — canonical aliases, regression examples, and the shared normalization rule.
• references/world-cup-market-discovery.md — live-slate discovery recipe, matchup parsing, and query caveats.
• references/automated-slate-scan.md — when to scan the slate automatically, how to filter by date, and the common alias pitfalls.
• references/clawhub-publishing.md — ClawHub publish checklist and verification steps.
• references/stake-sizing-guidance.md — when to size down moderate underdogs versus passing extreme longshots.
• scripts/team_names.py — single source of truth for canonical team names and query expansion.
• scripts/team_name_smoke_test.py — quick regression check for alias/canonicalization drift.

How to use this skill

Start with the fixture, not the venue:

• identify the teams or outcome being traded
• discover the current market fresh
• normalize team names before comparing the model and market labels
• verify that the market question matches the intended event
• price the market against your own fair value
• only enter when the edge is strong enough to survive slippage and live-state changes

When the user asks for "today's games", "tomorrow's games", or "all games in the slate", use the automated slate scan first instead of waiting for them to name the teams. This is especially important when the relevant fixture is hidden behind a multilingual alias.

When the market or model uses different team names, canonicalize both through scripts/team_names.py first; do not maintain separate alias rules in the research and execution scripts.

If anything looks stale, mismatched, or ambiguous, skip the trade and report the blocker.

When to use

Use this skill when you need to:

• keep trades conservative and explainable
• normalize multilingual team aliases and accented variants before pricing/discovery
• scan markets at runtime instead of hardcoding IDs
• decide whether to place a trade or return no bet
• include pre-match context like xG, injuries, lineups, and suspensions when the market context exposes a usable event or match id

Core principles

1. Use SimmerClient for trades. Do not call Polymarket CLOB directly from the skill.

2. Default to paper trading on sim. Paper and live share the same trade/pass decision gates; --live only changes whether the executed order is real-money or paper on sim.

3. Tag every trade. Include source and skill_slug so P&L and rebuy protection work correctly.

4. Report both sides. Include model_yes/model_no and market_yes/market_no in summaries so the report is readable without manual subtraction.

5. Paper trade on sim by default. Use the same edge threshold and pass/trade logic for paper and live; if the venue is simulated, submit the paper trade and include the simulated fill result. Reserve --live for real-money execution only. Moderate underdog or draw-leaning plays can size down when the model is near the market and the side is not a true longshot. Do not downsize into extreme underdogs or 80/20-vs-90/10 style flips; those should usually pass unless the model truly supports the upset.

6. Read secrets from env. Never hardcode API keys or private credentials.

7. Keep skill_slug aligned. The slug in clawhub.json, SKILL.md, and runtime tags should match.

8. Pass on uncertain mappings. If the market lookup or fixture validation is fragile, do not force a bet.

Suggested operating sequence

Step 1: Discover

Find the active market using runtime search or tags.

Step 2: Validate

Check the market page, question text, and event identity.

Step 3: Price

Estimate fair probability and compare it to market price.

Step 4: Gate

Require:

• trustworthy fixture mapping
• meaningful edge
• liquidity/slippage that still works
• live state that does not contradict the thesis
• the same pass/trade rule for paper and live; only the execution mode changes

Step 5: Act or pass

If all gates pass, trade. If any gate fails, return pass with a concrete reason.

Reporting template

Use this format when summarizing a decision:

• Market: <question or id>
• Model yes/no: <model_yes> / <model_no>
• Market yes/no: <market_yes> / <market_no>
• Edge: <edge>
• Confidence: <low/medium/high>
• Decision: <paper-trade / trade / pass>
• Reason: <exact blocker or thesis>

Common blockers

• stale or wrong market ID
• unresolved market context
• unparseable market question
• fixture mismatch
• team-name alias mismatch, including multilingual equivalents and accent variants (for example South Korea vs Korea Republic, Bosnia vs Bosnia and Herzegovina, Ivory Coast vs Côte d'Ivoire, or Cape Verde vs Cabo Verde)
• moderate underdogs or draw-leaning spots can size down
• extreme underdogs and 80/20-vs-90/10 style flips should usually pass unless the model truly supports the upset
• fragile underdog setup
• live state no longer supports the thesis
• execution blocked because the venue was not sim/live as requested

Regression guardrails

• Keep canonical names and alias expansion in one shared module.
• Prefer multilingual alias groups and accent-stripped normalization for country names that are identical by locale rather than meaning.
• Add a smoke test whenever a new alias is discovered or a market search misroutes to the wrong team.
• If discovery returns multiple candidates, score the question text and pick the best match instead of taking the first hit.
• For slate requests, run the automated slate scan and keep only fixture-style questions with a parsed team pair.
• Use the raw market label in reports, but the canonical form for pricing/lookup.

Publishing note

A ClawHub-ready skill folder should include:

• SKILL.md
• clawhub.json
• a main Python script
• DISCLAIMER.md

See references/publishing-flow.md for the repeatable login/logout/publish sequence, device-flow auth, and account-switching notes. See references/simmer-sdk-compat.md for the runtime-safe discovery and trade-call pattern that works across older and newer simmer-sdk installs.

Use the official ClawHub publish command from inside the folder:

npx clawhub@latest publish . --slug market-trading-workflow --version 1.0.20

If publishing is blocked by an account policy, switch to a qualifying account and repeat the device-login flow before retrying publish. If a device code expires, restart clawhub login --device --no-browser to get a fresh code.