Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
starchild-ai-agent avatar

Polymarket

  • 176 installs
  • 21 repo stars
  • Updated August 3, 2026
  • starchild-ai-agent/official-skills

Use polymarket for development tasks

About

polymarket: A skill for development. This provides functionality for development workflows.

  • polymarket

Polymarket by the numbers

  • 176 all-time installs (skills.sh)
  • +7 installs in the week ending Aug 5, 2026 (Skillselion tracking)
  • Ranked #2,240 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
  • Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/starchild-ai-agent/official-skills --skill polymarket

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs176
repo stars21
Last updatedAugust 3, 2026
Repositorystarchild-ai-agent/official-skills

What it does

Use polymarket for development tasks

Files

SKILL.mdMarkdownGitHub ↗

Polymarket Trading (CLOB V2)

Script-first. Every workflow is one bash call + at most one wallet_sign_typed_data (which can't be scripted because it's a wallet RPC). Verified live: see Changelog v5.1.0.

---

TL;DR — Trade in 3 steps

# 1. One-time setup (idempotent — safe to re-run)
python3 scripts/setup.py --all 10        # wrap 10 USDC.e -> pUSD + all approvals

# 2. Find a market
python3 scripts/search.py "trump" --limit 3   # returns token_ids

# 3. Place order
python3 scripts/prepare_order.py <token_id> BUY <price> <size>
# → sign /tmp/poly_order.json via wallet_sign_typed_data
python3 scripts/post_order.py <signature>

All scripts live in skills/polymarket/scripts/ and assume working dir is the skill folder.

---

Account prerequisites (one-time, on-chain)

CLOB V2 settles in pUSD (an ERC-20 USDC wrapper), NOT raw USDC.e. Before the first order, the EOA must:

1. Hold USDC.e on Polygon (any amount ≥ what you want to trade). 2. Wrap USDC.e → pUSD via CollateralOnramp.wrap(). 3. approve(pUSD, spender, MAX) for the 3 V2 exchange spenders. 4. setApprovalForAll(CTF, spender, true) for the same 3 spenders (needed for SELL/redemption).

scripts/setup.py does all of this and is idempotent: it reads on-chain state and skips anything already done. Gas is sponsored by the Privy/Alchemy paymaster — user pays 0 MATIC.

python3 scripts/setup.py                  # dry-run: show current state + next step
python3 scripts/setup.py --all 10         # wrap 10 USDC.e + approve everything
python3 scripts/setup.py --wrap 50        # wrap more later
python3 scripts/setup.py --approve        # re-issue approvals only

---

Scripts

ScriptPurposeTool calls
setup.pyOne-time wrap + approvals (idempotent)0–8 wallet_transfer
search.pyFind events/markets, returns token_ids + live prices0
status.pyBalance + positions + open orders + recent trades0
prepare_order.pyFetch orderbook + build EIP-712 payload0
post_order.pySubmit signed order, verify fill0
cancel.pyCancel one order (--id) or all (--all)0
close_positions.pyBuild SELL orders for all positions0
auth.pyCheck / derive CLOB API key from wallet0–1 sign

Search

python3 scripts/search.py "ceasefire" --limit 3
  • Use short keywords (trump, btc, ceasefire), not full literal questions — long queries often return empty.
  • Output JSON includes outcomes[i].token_id (YES = index 0, NO = index 1) and current price.

Place an order — full flow

# 1. Prepare: fetches market info + orderbook, writes /tmp/poly_order.json
python3 scripts/prepare_order.py 7892825...50228 BUY 0.65 10

# 2. Sign (Python in agent runtime, ONE tool call)
#    from core.skill_tools import wallet
#    p = json.load(open('/tmp/poly_order.json'))
#    sig = wallet.wallet_sign_typed_data(
#        domain=p['domain'], types=p['types'],
#        primaryType=p['primaryType'], message=p['message']
#    )['signature']

# 3. Post: submits and prints order ID + fill status + tx hash
python3 scripts/post_order.py 0xSIGNATURE

Close one or all positions

python3 scripts/close_positions.py                # all positions
python3 scripts/close_positions.py --token_id X   # one position
# → writes one /tmp/poly_close_N.json per position; sign each + post

---

YES / NO & orderbook

Every binary market has two complementary tokens: YES + NO ≈ $1.00.

BetActionUseBuy price
Event happensBUY YESoutcomes[0].token_idYES price
Event won't happenBUY NOoutcomes[1].token_idNO price

Always check the book for the token you intend to buy:

  • BUY → entry ≈ best_ask
  • SELL → exit ≈ best_bid
  • If you see 0.01 / 0.99, you're looking at the wrong token's book.

---

Order rules (CLOB V2)

  • Minimum order value: $1 (i.e. price × size ≥ 1.0)
  • Minimum size: 5 shares
  • Tick: normalized automatically by prepare_order.py (usually $0.01)
  • `signatureType`: always 0 (EOA) for Privy wallets

V2 wire format is strict — post_order.py already handles this, but if you ever build a payload by hand:

  • salt must be int (not string)
  • Do NOT send taker / nonce / feeRateBps (V1 fields, removed in V2)
  • metadata and builder are bytes32 zeros (0x + 64 zeros)

---

Auth refresh

CLOB credentials (POLY_API_KEY / POLY_SECRET / POLY_PASSPHRASE) are derived from a wallet signature once and persist. If status.py returns 401:

python3 scripts/auth.py --check                   # quick sanity check
python3 scripts/auth.py --prepare 0xWALLET        # build signing payload
# → wallet_sign_typed_data(...)
python3 scripts/auth.py --save 0xSIG 0xWALLET TIMESTAMP

Invariants: TIMESTAMP and 0xWALLET in --save must match the most recent --prepare. If 401 persists, rerun the full prepare→sign→save flow with a fresh timestamp.

---

Geo / VPN

CLOB API is geo-blocked from US IPs. scripts/common.py transparently routes through sc-vpn.internal:8080 and caches the fastest region. No agent action needed. Override with POLY_VPN_REGION=ar or disable with POLY_DISABLE_VPN=true.

---

Errors → fixes

ErrorCauseFix
Invalid order payloadWrong V2 wire format (string salt / extra V1 fields)Use post_order.py (it sends the right shape)
invalid amount for a marketable BUY order ($X), min size: $1Order value < $1Increase price × size to ≥ $1
not enough balance / 0 buying powerpUSD not wrapped yet, OR signature_type mismatch in cachesetup.py --all 10, then status.py
L2_BALANCE_TOO_LOWNo pUSD in EOAWrap more: setup.py --wrap N
order_version_mismatchOld V1 signing schemaRe-run prepare_order.py (uses V2 domain version=2)
401 / Invalid API keyStale CLOB credentialsauth.py refresh flow
403 geo-blockVPN unhealthyRetry; if persists, set POLY_VPN_REGION to another region
Orderbook shows 0.01 / 0.99Looking at the wrong outcome's bookUse the token_id you actually plan to buy

Known transient errors

  • Privy / Alchemy paymaster HTTP 500 may happen during rapid back-to-back on-chain calls.
  • This is typically transient infra jitter, not a permanent wallet/skill issue.
  • Practical fix: wait ~10 seconds and retry the same step.

---

Architecture summary

  • Wallet: Privy EOA, signatureType=0. Agent signs EIP-712 via wallet_sign_typed_data; no private key in agent context.
  • Gas: sponsored (Alchemy paymaster) — every on-chain call routes through wallet_transfer.
  • Collateral: pUSD (0xC011a7E1...DFB), 6 decimals, 1:1 wrap of USDC.e.
  • Exchanges: CTF Exchange V2 (binary), Neg-Risk Adapter, Neg-Risk Exchange V2 — all 3 must be approved for SELL/settlement.
  • CLOB: https://clob.polymarket.com (V2 backend, live since Apr 28 2026). L1 = wallet sig, L2 = HMAC with derived API key.

---

Changelog

  • v6.0.1 — Bugfixes: (1) scripts/common.py::save_env_var() now guards missing trailing newline in .env to prevent key concatenation; (2) scripts/close_positions.py migrated from V1 wire fields to CLOB V2 schema (timestamp/metadata/builder, domain version=2) aligned with prepare_order.py. Added "Known transient errors" note for occasional Privy/Alchemy paymaster HTTP 500 under rapid consecutive calls (retry after ~10s).
  • v6.0.0 — Major: full SKILL rewrite for clarity ("3 steps to trade"), new idempotent setup.py for one-time wrap + approvals, end-to-end live-verified on CLOB V2 (BUY 0x43f20c67...20b653 → SELL 0x19f475e4...fedde1, 5 NO @ 0.989 → @ 0.988, ~$0.005 slippage). Supersedes the V1-era flow entirely.
  • v5.1.0 — Added setup.py (idempotent wrap + approvals). Full SKILL rewrite for clarity. Live-verified: BUY 0x43f20c67...20b653, SELL 0x19f475e4...fedde1 (5 NO @ 0.989 → @ 0.988, ~$0.005 slippage).
  • v5.0.5 — CLOB V2 wire format fix: salt must be int; remove taker/nonce/feeRateBps.
  • v5.0.4 — Migrated to V2 EIP-712 domain (version=2), V2 contracts, V2 order fields.
  • v5.0.0 — Script-first architecture (BUY: 8 calls → 3).

Related skills

Backend & APIsbackendintegrations

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.