# Polymarket Trade

> >

- **Type:** Skill
- **Install:** `agentstack add skill-aurehub-skills-polymarket-trade`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aurehub](https://agentstack.voostack.com/s/aurehub)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aurehub](https://github.com/aurehub)
- **Source:** https://github.com/aurehub/skills/tree/main/skills/polymarket-trade

## Install

```sh
agentstack add skill-aurehub-skills-polymarket-trade
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 /.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 /config.example.yaml ~/.aurehub/polymarket.yaml` |
| 5 | `node_modules` missing in `/scripts/` | AUTO-FIX | Run: `npm install` in `/scripts/` |
| 6 | `~/.aurehub/.polymarket_clob` missing | INTERACTIVE | Run: `node /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.

### Optional environment variables (in `~/.aurehub/.env`)

| Variable | Purpose | Default |
|----------|---------|---------|
| `WDK_ACCOUNT_INDEX` | HD derivation index (0-based) for wallet address | `0` |

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 **Account Selection**, then **Wallet-Ready Registration** (below) before proceeding to intent detection.

## Account Selection

If the user specifies a wallet index (e.g. "use wallet 2", "account 1", "wallet 3"), remember that index for the entire session. Append `--account N` to **every** `node trade.js`, `node balance.js`, `node setup.js`, and `node redeem.js` command in this session.

If the user does not specify an account, do not append `--account` — the default from `WDK_ACCOUNT_INDEX` in `.env` (or `0`) is used automatically.

`` is the directory containing this SKILL.md file.

## Resolving POLY_SCRIPTS_DIR

Use `/scripts` as the scripts directory. To find it at runtime:

```bash
# 1. Git repo fallback
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"
# 2. Bounded home search
[ -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):

```bash
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.

1. `REGISTERED=$(cat ~/.aurehub/.registered 2>/dev/null)`
2. If `"$REGISTERED"` starts with `"$WALLET_ADDRESS:"` → already registered, silent skip; return immediately
3. 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=`)
       - Re-source env: `source ~/.aurehub/.env`
       - Continue to step 4
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:
   ```bash
   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" ""
```
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

1. Run `node "$POLY_SCRIPTS_DIR/browse.js" ` to show current prices
2. Ask user: market slug, side (YES/NO), amount in USD
3. Run: `node "$POLY_SCRIPTS_DIR/trade.js" --buy --market  --side YES|NO --amount `
4. 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

1. Run `node "$POLY_SCRIPTS_DIR/browse.js" ` to confirm token IDs and current bids
2. Ask user: market slug, side (YES/NO to sell), number of shares
3. Run: `node "$POLY_SCRIPTS_DIR/trade.js" --sell --market  --side YES|NO --amount `
4. 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](https://docs.polymarket.com/polymarket-learn/FAQ/geoblocking) — 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 guide
- `references/buy.md` — detailed buy flow
- `references/sell.md` — detailed sell flow
- `references/balance.md` — balance interpretation
- `references/browse.md` — browse output format
- `references/contracts.md` — Polygon contract addresses
- `references/safety.md` — safety gate details

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aurehub](https://github.com/aurehub)
- **Source:** [aurehub/skills](https://github.com/aurehub/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aurehub-skills-polymarket-trade
- Seller: https://agentstack.voostack.com/s/aurehub
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.