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.

~/.aurehub/.wdk_vault

~/.aurehub/.wdk_password

~/.aurehub/.env

cp <skill-dir>/.env.example ~/.aurehub/.env

~/.aurehub/.env

POLYGON_RPC_URL

POLYGON_RPC_URL=https://polygon.drpc.org

~/.aurehub/.env

~/.aurehub/polymarket.yaml

cp <skill-dir>/config.example.yaml ~/.aurehub/polymarket.yaml

node_modules

<skill-dir>/scripts/

npm install

<skill-dir>/scripts/

~/.aurehub/.polymarket_clob

node <skill-dir>/scripts/setup.js

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>

Resolving POLY_SCRIPTS_DIR

Use

<skill-dir>/scripts

# 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

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

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=<value>

         )
       • 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:

   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

.registered

Intent Detection

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

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" <market>

   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 <slug> --side YES|NO --amount <usd>

4. The script handles approval and order submission; report the result

Pass

--dry-run

Sell Flow

1. Run

   node "$POLY_SCRIPTS_DIR/browse.js" <market>

   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 <slug> --side YES|NO --amount <shares>

4. The script handles setApprovalForAll and order submission; report the result

Pass

--dry-run

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 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