Market Trading Workflow

SKILL.md

---
name: market-trading-workflow
description: "Conservative World Cup fixture-trading workflow for ClawHub: discover a market, validate the matchup, price the edge, and trade only when safe."
version: 1.0.10
author: Hermes Agent
license: MIT
metadata:
  author: Hermes Agent
  version: "1.0.10"
  displayName: World Cup Head to Head Fixture Trader
  difficulty: intermediate
---

# 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
- 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/clawhub-publishing.md` — ClawHub publish checklist and verification steps.
- `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 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
- scan markets at runtime instead of hardcoding IDs
- decide whether to place a trade or return no bet

## Core principles

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

2. **Default to paper trading on sim.**
   Simulated venue trades should submit by default; require `--live` for any real-money action.

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

4. **Paper trade on sim by default.**
   If the venue is simulated, submit the paper trade and include the simulated fill result. Reserve `--live` for real-money execution only.

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

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

6. **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

### 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 (for example `South Korea` vs `Korea Republic`, or `Bosnia` vs `Bosnia and Herzegovina`)
- thin edge
- fragile underdog setup
- live state no longer supports the thesis
- paper trade not submitted because the venue was not sim or the trade was blocked by warnings/edge rules

## Regression guardrails

- Keep canonical names and alias expansion in one shared module.
- 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.
- 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:

```bash
npx clawhub@latest publish . --slug market-trading-workflow --version 1.0.10
```

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.