Polymarket Skill (CLOB V2)

Session Initialization

Before any polymarket command, verify the Polymarket key is set:

agent polymarket proxy-wallet

If this returns ok: true with an eoaAddress and proxyWalletAddress, the key is configured and you can proceed directly to trading. If it errors, the user needs to run set-key (see Onboarding below).

Understanding the 3 Addresses

Every Polymarket user has three addresses. Do not confuse them:

For trading: USDC.e flows from the OMS smart wallet → proxy wallet → auto-wrapped to pUSD → CLOB orders. The proxy wallet is the trading identity.

Pre-Trade Checklist

Before placing a trade, verify these four things in order:

1. EOA key is configured

agent polymarket proxy-wallet
# → must return ok: true with eoaAddress and proxyWalletAddress

2. ToS accepted on Polymarket ← one-time per EOA, permanent

• Visit https://polymarket.com, connect with the EOA address, accept Terms of Service
• If ToS is not accepted, CLOB order posting will fail with not authorized
• If the user has previously traded on Polymarket with this EOA, ToS is already accepted — skip this

3. Proxy wallet approvals set for V2 exchange ← required for all users after V2 migration

• Approvals allow the proxy wallet to interact with the V2 CTF exchange contracts and CollateralOnramp
• All users must run approve --broadcast after the V2 migration (April 28 2026) — V1 approvals on old exchange contracts do not carry over
• After running V2 approvals once, they are permanent on-chain for that EOA

4. Smart wallet has USDC.e ← required per trade, minimum $1

agent balances
# → check USDC.e balance (0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174)
# → must have at least $1 USDC.e to place any order
# → USDC.e is auto-wrapped to pUSD during the buy flow

Onboarding: First-Time Setup

Option A — Using email login (existing Polymarket account)

Step 1: Get the private key from Polymarket

1. Go to: https://reveal.magic.link/polymarket
2. Connect/authenticate with the same email used for Polymarket
3. Copy the exported private key (0x...)

Step 2: Import the key into the CLI

agent polymarket set-key <privateKey>

Output confirms the eoaAddress and proxyWalletAddress.

Step 3: Show the user their addresses

agent polymarket proxy-wallet

Tell the user: "Your EOA is <eoaAddress> — this needs a small amount of POL for the one-time approval step. Your Polymarket trading address (proxy wallet) is <proxyWalletAddress> — this is where your pUSD and outcome tokens live."

Step 4: Fund EOA with POL for gas (approval step only)

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

The EOA only needs POL for the one-time approve transaction. After that, trading requires no gas from the EOA.

Step 5: Accept Terms of Service

1. Go to https://polymarket.com
2. Connect with the EOA address
3. Accept Terms of Service when prompted

Step 6: Set proxy wallet approvals for V2 (one-time, permanent)

agent polymarket approve --broadcast

This sets approvals for the V2 exchange contracts and CollateralOnramp. Permanent on-chain — never needs to be run again for this EOA.

Option B — Using the builder EOA (no Polymarket account)

Step 1: Confirm addresses

agent polymarket proxy-wallet

Step 2: Accept Terms of Service (required)

1. Go to https://polymarket.com
2. Connect with the EOA address shown above
3. Accept Terms of Service when prompted

Step 3: Fund EOA with POL for gas

agent send-native --to <eoaAddress> --amount 0.1 --broadcast

Step 4: Set proxy wallet approvals for V2 (one-time)

agent polymarket approve --broadcast

Commands

Browse Markets

# List top markets by volume
agent polymarket markets

# Search by keyword
agent polymarket markets --search "bitcoin" --limit 10

# Paginate
agent polymarket markets --limit 20 --offset 20

Key output fields per market:

• conditionId — the ID needed for all trading commands
• question — what the market is asking
• yesPrice / noPrice — current probability (0 to 1, e.g. 0.65 = 65%)
• negRisk — if true, set neg-risk approvals before trading this market
• endDate — when the market resolves

Get a Single Market

agent polymarket market <conditionId>

Use this to confirm prices and token IDs before placing an order.

Show Proxy Wallet Address

agent polymarket proxy-wallet

Confirms which EOA and proxy wallet are active. The proxy wallet is where pUSD and tokens are held.

Set Approvals (Required After V2 Migration)

# Standard markets
agent polymarket approve --broadcast

# Neg-risk markets (only if you see negRisk: true on a market you want to trade)
agent polymarket approve --neg-risk --broadcast

All users must run this after the V2 migration — previous V1 approvals on old exchange contracts do not carry over. V2 approvals cover: pUSD → V2 exchange, CTF → V2 exchange, and USDC.e → CollateralOnramp (for wrapping). Once set, they are permanent on-chain.

Buy a Position

# Dry-run first — always check before executing
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount>

# Execute — funds proxy wallet, wraps USDC.e → pUSD, then places order
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --broadcast

# If proxy wallet already has pUSD from a previous failed order (skip the funding step)
agent polymarket clob-buy <conditionId> YES|NO <usdcAmount> --skip-fund --broadcast

# Limit order — fill only at this price or better
agent polymarket clob-buy <conditionId> YES <usdcAmount> --price 0.45 --broadcast

How it works:

1. Smart wallet transfers usdcAmount USDC.e to the proxy wallet (OMS tx)
2. Proxy wallet wraps USDC.e → pUSD via CollateralOnramp (on-chain, EOA gas)
3. Posts CLOB BUY order: maker=proxy wallet, signer=EOA (off-chain, no gas)
4. Tokens arrive in proxy wallet on fill

Order types:

• No --price: FOK market order (fill entirely or cancel)
• --fak: FAK market order (partial fills allowed)
• --price 0.x: GTC limit order (stays open until filled or cancelled)

Minimum order size: $1. The CLOB rejects orders below $1. If the fund+wrap step runs but the order is rejected, the pUSD stays in the proxy wallet — use --skip-fund on the retry.

Sell a Position

# Dry-run first
agent polymarket sell <conditionId> YES|NO <shares>

# Execute
agent polymarket sell <conditionId> YES|NO <shares> --broadcast

# Limit sell
agent polymarket sell <conditionId> YES <shares> --price 0.80 --broadcast

<shares> is the number of outcome tokens (not USD). Get share count from positions. Selling is pure off-chain — no gas, no on-chain tx. Proceeds are received as pUSD in the proxy wallet.

Check Positions

agent polymarket positions

Shows all open positions in the proxy wallet with current value, P&L, and outcome.

Check Open Orders

agent polymarket orders

Lists GTC limit orders that are still open (FOK/FAK orders are never "open" — they fill or cancel immediately).

Cancel an Order

agent polymarket cancel <orderId>

Get orderId from the orders command or from the orderId field in clob-buy output.

Full Autonomous Trading Flow

# ── FIRST TIME (run once per EOA) ──────────────────────────────────────

# 1. Import Polymarket private key
agent polymarket set-key 0x<yourPrivateKey>
# → save eoaAddress and proxyWalletAddress

# 2. Accept ToS at https://polymarket.com (connect EOA, accept when prompted)

# 3. Fund EOA with POL for the one-time approval tx
agent send-native --to <eoaAddress> --amount 0.1 --broadcast

# 4. Set V2 approvals (one-time, permanent — covers pUSD, CTF, and CollateralOnramp)
agent polymarket approve --broadcast

# ── RETURNING USER ──────────────────────────────────────────────────────
# If V2 approvals were already set: skip steps 1-4, go straight to trading.
# NOTE: V1 approvals (pre-April 28 2026) do NOT carry over — re-run approve once.

# ── FIND A MARKET ────────────────────────────────────────────────────────

# 5. Search for markets
agent polymarket markets --search "bitcoin" --limit 10

# 6. Get details on a specific market
agent polymarket market 0x<conditionId>
# → check: yesPrice, noPrice, negRisk, endDate
# → if negRisk: true → run approve --neg-risk --broadcast first

# ── ENTER A POSITION ────────────────────────────────────────────────────

# 7. Dry-run to confirm
agent polymarket clob-buy 0x<conditionId> YES 5
# → review: currentPrice, proxyWalletAddress, flow (includes pUSD wrapping)

# 8. Execute
agent polymarket clob-buy 0x<conditionId> YES 5 --broadcast
# → check: orderStatus === "matched"

# ── MANAGE ──────────────────────────────────────────────────────────────

# 9. Check positions
agent polymarket positions
# → review: size (shares), curPrice, cashPnl

# 10. Sell when ready
agent polymarket sell 0x<conditionId> YES <shares> --broadcast
# → orderStatus === "matched" means pUSD is back in proxy wallet

Decision Logic for an Autonomous Agent

When deciding whether to buy:

1. Run proxy-wallet — confirm EOA and proxy wallet addresses
2. Run balances — confirm smart wallet has at least $1 USDC.e
3. Check positions — avoid doubling up on already-held positions
4. Check markets — use yesPrice/noPrice as probability inputs
5. Check negRisk on the target market — if true, verify neg-risk approvals were set
6. Use --skip-fund if the proxy wallet already has enough pUSD from a previous attempt
7. Always dry-run first, then broadcast

When deciding whether to sell:

1. Get current size (shares) from positions
2. Use curPrice vs avgPrice to assess profit/loss
3. Market sell (sell --broadcast) for immediate exit
4. Limit sell (--price 0.x --broadcast) to wait for a better price

Troubleshooting

Key Facts for Agents

• CLOB V2 is active (since April 28, 2026). Collateral is pUSD, not USDC.e.
• All commands are dry-run by default. approve, clob-buy, sell do nothing without --broadcast.
• V2 approvals are required for all users. V1 approvals on old exchange contracts do not carry over. Run approve --broadcast once after migration.
• clob-buy handles the full flow automatically: transfers USDC.e from smart wallet → proxy wallet, wraps USDC.e → pUSD, then places the CLOB order (unless --skip-fund).
• Positions live in the proxy wallet, not the OMS smart wallet. positions queries the proxy wallet.
• Sell is free. No gas, no on-chain tx. Selling via CLOB is a signed off-chain message only. Proceeds are pUSD.
• orderStatus: "matched" means the trade filled. "unmatched" means FOK failed (no liquidity).
• Fees are protocol-determined at match time. Makers never pay fees — only takers. No feeRateBps on orders.
• The proxy wallet address never changes. It is deterministic from the EOA via CREATE2.
• Could not create api key in stderr is non-fatal. The CLI handles this automatically.