| name | polymarket-trade |
| description | Trade on Polymarket prediction markets on Polygon. Supports browsing markets, checking wallet/CLOB balance, and buying or selling YES/NO shares with safety gates. Wallet: WDK vault (~/.aurehub/.wdk_vault). Config: ~/.aurehub/polymarket.yaml. Triggers: buy YES, buy NO, sell shares, browse markets, check Polymarket balance, Polymarket trade, prediction market, what are the odds, redeem winnings, claim resolved positions.
|
| license | MIT |
| compatibility | Requires Node.js >= 18, Polygon RPC (HTTPS), and Polymarket CLOB API credentials. |
| metadata | {"author":"aurehub","version":"1.0.0"} |
polymarket-trade
Trade on Polymarket prediction markets. Non-custodial — private key stays in your WDK vault.
Prerequisites
Before any action, check prerequisites for the current flow and auto-fix what you can.
Browse flow (no wallet, no RPC, no CLOB needed): check step 4 only.
Redeem flow (no CLOB needed): check steps 1–5 in order.
Balance / Trade / Setup flow: check all steps 1–6 in order.
Step types:
- HARD STOP — cannot proceed; inform user and stop (these require prior xaut-trade setup).
- AUTO-FIX — run the command automatically, then continue.
- INTERACTIVE — run the script; it will print the wallet address and save credentials; report the result to the user.
| Step | Missing item | Type | Agent action |
|---|
| 1 | ~/.aurehub/.wdk_vault | HARD STOP | Inform: xaut-trade must be installed and its wallet setup completed first. Stop. |
| 2 | ~/.aurehub/.wdk_password | HARD STOP | Inform: xaut-trade must be installed and its wallet setup completed first. Stop. |
| 3 | ~/.aurehub/.env missing | AUTO-FIX | Run: cp <skill-dir>/.env.example ~/.aurehub/.env |
| 3 | ~/.aurehub/.env exists, POLYGON_RPC_URL absent | AUTO-FIX | Append POLYGON_RPC_URL=https://polygon.drpc.org to ~/.aurehub/.env |
| 4 | ~/.aurehub/polymarket.yaml missing | AUTO-FIX | Run: cp <skill-dir>/config.example.yaml ~/.aurehub/polymarket.yaml |
| 5 | node_modules missing in <skill-dir>/scripts/ | AUTO-FIX | Run: npm install in <skill-dir>/scripts/ |
| 6 | ~/.aurehub/.polymarket_clob missing | INTERACTIVE | Run: node <skill-dir>/scripts/setup.js (only after steps 3–5 pass) |
On any auto-fix failure: stop and report the error with the manual remediation command.
After all fixes succeed, re-run the relevant checks and proceed.
After prerequisites pass: if the user's message matches browse flow (contains "browse", "what markets", "what are the odds"), skip registration and proceed directly to intent detection. Otherwise run Wallet-Ready Registration (below) before proceeding to intent detection.
<skill-dir> is the directory containing this SKILL.md file.
Resolving POLY_SCRIPTS_DIR
Use <skill-dir>/scripts as the scripts directory. To find it at runtime:
GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
[ -n "$GIT_ROOT" ] && [ -d "$GIT_ROOT/skills/polymarket-trade/scripts" ] && POLY_SCRIPTS_DIR="$GIT_ROOT/skills/polymarket-trade/scripts"
[ -z "$POLY_SCRIPTS_DIR" ] && POLY_SCRIPTS_DIR=$(dirname "$(find -L "$HOME" -maxdepth 6 -type f -path "*/polymarket-trade/scripts/browse.js" 2>/dev/null | head -1)")
Wallet-Ready Registration
Run after prerequisites pass for any wallet-requiring flow (not browse). Derive WALLET_ADDRESS using xaut-trade's swap.js (required by prerequisites):
XAUT_SWAP=$(find -L "$HOME" -maxdepth 6 -type f -path "*/xaut-trade/scripts/swap.js" 2>/dev/null | head -1)
source ~/.aurehub/.env
WALLET_ADDRESS=$(node "$XAUT_SWAP" address | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).address")
If XAUT_SWAP is empty or the command fails, skip registration silently and continue.
REGISTERED=$(cat ~/.aurehub/.registered 2>/dev/null)- If
"$REGISTERED" starts with "$WALLET_ADDRESS:" → already registered, silent skip; return immediately
- If
RANKINGS_OPT_IN != "true":
- Check marker:
PROMPTED=$(cat ~/.aurehub/.rankings_prompted 2>/dev/null)
- If marker starts with
"$WALLET_ADDRESS:" → skip; return immediately
- Otherwise ask once: "Join XAUT activity rankings now? (yes/no)"
- If user says
no: echo "$WALLET_ADDRESS:declined" > ~/.aurehub/.rankings_prompted; return
- If user says
yes:
- If
NICKNAME is empty: ask user for nickname
- Persist opt-in in
~/.aurehub/.env (RANKINGS_OPT_IN=true, NICKNAME=<value>)
- Re-source env:
source ~/.aurehub/.env
- Continue to step 4
- If
RANKINGS_OPT_IN == "true":
- If
NICKNAME is empty: ask "You're opted in to XAUT activity rankings — what nickname would you like to appear as?", then persist to ~/.aurehub/.env and re-source
- Register:
NICKNAME_ESC=$(printf '%s' "$NICKNAME" | sed 's/\\/\\\\/g; s/"/\\"/g')
REGISTER_RESP=$(curl -s -o /dev/null -w "%{http_code}" -X POST \
https://xaue.com/api/rankings/participants \
-H 'Content-Type: application/json' \
-d "{\"wallet_address\":\"$WALLET_ADDRESS\",\"nickname\":\"$NICKNAME_ESC\",\"source\":\"agent\"}")
- HTTP 200 or 201:
echo "$WALLET_ADDRESS:$NICKNAME" > ~/.aurehub/.registered; inform: "Registered with nickname: $NICKNAME"
- Any other status: silent continue, do not write marker file
Only prompt once per wallet. The .rankings_prompted and .registered markers ensure idempotency across sessions.
Intent Detection
| User says | Action |
|---|
| "buy YES on X market", "buy X at Y price", "buy shares" | buy flow |
| "sell my YES shares", "sell X shares" | sell flow |
| "browse X", "what markets", "what are the odds on X" | browse flow |
| "my polymarket balance", "how much USDC" | balance flow |
| "redeem", "claim winnings", "collect" | redeem flow |
Browse Flow
Run environment check (no wallet, no RPC, no CLOB credentials needed):
node "$POLY_SCRIPTS_DIR/browse.js" "<keyword or market slug>"
Show the output to the user. The output includes:
- Slug and ConditionId — either can be passed as
--market to trade.js
- Token IDs — for reference
Prefer passing ConditionId to --market when trading (more reliable than slug).
Balance Flow
Run environment check:
node "$POLY_SCRIPTS_DIR/balance.js"
Redeem Flow
Run environment check (no CLOB credentials needed), then:
node "$POLY_SCRIPTS_DIR/redeem.js"
Show output. If negRisk positions are skipped, tell the user to visit polymarket.com.
Buy Flow
- Run
node "$POLY_SCRIPTS_DIR/browse.js" <market> to show current prices
- Ask user: market slug, side (YES/NO), amount in USD
- Run:
node "$POLY_SCRIPTS_DIR/trade.js" --buy --market <slug> --side YES|NO --amount <usd>
- The script handles approval and order submission; report the result
Pass --dry-run to simulate the full flow (balance checks, hard stops, order construction) without submitting any transactions.
Sell Flow
- Run
node "$POLY_SCRIPTS_DIR/browse.js" <market> to confirm token IDs and current bids
- Ask user: market slug, side (YES/NO to sell), number of shares
- Run:
node "$POLY_SCRIPTS_DIR/trade.js" --sell --market <slug> --side YES|NO --amount <shares>
- The script handles setApprovalForAll and order submission; report the result
Pass --dry-run to simulate the full flow (balance checks, hard stops, order construction) without submitting any transactions.
Safety Gates (handled by trade.js)
- Amount < $50: proceeds automatically
- $50 ≤ amount < $500: shows risk summary, prompts once
- Amount ≥ $500: double confirmation required
- Insufficient USDC.e (buy): auto-swap POL→USDC.e offered; swap targets 110% of needed amount (buffer), 2% slippage protection; hard-stop only if POL also insufficient
- Hard-stops: insufficient POL gas (<0.01), market CLOSED, amount < min_order_size, CTF balance insufficient (sell)
Geo-restriction
Polymarket API blocks US and some other regions. If you see a 403 error, tell the user to enable a VPN and retry.
Polymarket Knowledge Base
- Chain: Polygon mainnet (chain_id: 137)
- Settlement currency: USDC.e (bridged USDC,
0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)
- Share price scale: 0.00–1.00, where price = implied probability (e.g. $0.70 YES = 70% market probability of YES outcome)
- Minimum share price: $0.01; maximum: $0.99
- Settlement: winning shares redeem for $1.00 USDC.e each; losing shares expire worthless
- Order type: FOK (Fill-Or-Kill) — market orders fill immediately or cancel atomically; no partial fills left open
- Restricted regions: United States, United Kingdom, Singapore, and others — use a VPN with a supported country node if blocked
Answer knowledge queries directly using the data above — no API calls needed.
References
Load these on demand:
references/setup.md — first-time setup guidereferences/buy.md — detailed buy flowreferences/sell.md — detailed sell flowreferences/balance.md — balance interpretationreferences/browse.md — browse output formatreferences/contracts.md — Polygon contract addressesreferences/safety.md — safety gate details
