Polymarket Trading

Polymarket Trading Skill

Complete guide to trading on Polymarket through the Quantish MCP server.

Prerequisites

Run /quantish-mcp-setup first to connect to the MCP servers.

Trading Workflow

1. Check Wallet Status

mcp__quantish__get_wallet_status

Response fields:

• safeAddress: Your trading wallet (Polygon)
• safeDeployed: Must be true
• approvals: All should be true (usdc, ctf, negRisk)
• isReady: Must be true to trade

2. Check Balances

mcp__quantish__get_balances

Response:

{
  "safe": {
    "address": "0x...",
    "usdc": "10.0",      // Available to trade
    "nativeUsdc": "0.0"  // Circle USDC (different token)
  }
}

3. Find Markets via Discovery

Use the Discovery MCP to search for markets across all platforms.

mcp__quantish-discovery__search_markets
  query: "government shutdown"
  platform: "polymarket"
  limit: 5

Response includes:

{
  "markets": [{
    "platform": "polymarket",
    "conditionId": "0xd5a91c9ee50ba80385283714f2a66b1e16d544a682af2af06a8f57fcf1d0233d",
    "title": "Will the government shutdown last 5 days or more?",
    "prices": [
      {"outcome": "Yes", "price": 0.45, "tokenId": "8008742846..."},
      {"outcome": "No", "price": 0.55, "tokenId": "1122334455..."}
    ]
  }]
}

Key fields:

• conditionId: Market identifier (0x...) - needed for place_order
• tokenId: Outcome token ID (long number) - needed for place_order
• prices[].outcome: "Yes" or "No"
• prices[].price: Current price (0.01-0.99)

4. Check Orderbook (IMPORTANT - DO THIS FIRST)

mcp__quantish__get_orderbook
  tokenId: "8008742846391096366381429238657491392199916771102623264605530168655505543184"

Response shows:

• bids: Buy orders (sorted low to high)
• asks: Sell orders (sorted high to low)
• Best bid = highest bid price
• Best ask = lowest ask price

ALWAYS check orderbook before placing orders to get best price.

5. Get Current Price

mcp__quantish__get_price
  tokenId: "8008742846391096366381429238657491392199916771102623264605530168655505543184"

Returns midpointPrice between best bid/ask.

6. Place Order

mcp__quantish__place_order
  conditionId: "0xd5a91c9ee50ba80385283714f2a66b1e16d544a682af2af06a8f57fcf1d0233d"
  tokenId: "8008742846391096366381429238657491392199916771102623264605530168655505543184"
  side: "BUY"
  price: 0.45
  size: 4

Parameters: | Param | Type | Description | |-------|------|-------------| | conditionId | string | Market ID (from search) | | tokenId | string | YES or NO token ID | | side | "BUY" or "SELL" | Direction | | price | number | Limit price 0.01-0.99 | | size | number | Number of shares | | orderType | string | "GTC" (default), "FOK", "FAK", "GTD" |

Order Types:

• GTC: Good Till Cancelled - rests on book, crosses spread if price allows
• FOK: Fill Or Kill - must fill entirely or fails
• FAK: Fill And Kill - fills what it can, cancels rest
• GTD: Good Till Date - requires expiration timestamp

Cost calculation: price × size = USDC cost

Response:

{
  "success": true,
  "orderId": "f3a665c9-...",
  "status": "LIVE",  // or "FILLED"
  "message": "Order is live: BUY 4 shares at $0.45"
}

7. Check Positions

mcp__quantish__get_positions

Response:

{
  "positions": [{
    "outcome": "Yes",
    "size": 4,
    "avgPrice": 0.45,
    "currentPrice": 0.43,
    "currentValue": 1.72,
    "pnl": -0.08,
    "marketTitle": "Will the government shutdown last 5 days or more?"
  }]
}

8. Check Orders

mcp__quantish__get_orders
  status: "LIVE"  // optional: PENDING, LIVE, FILLED, CANCELLED, FAILED

9. Cancel Order

mcp__quantish__cancel_order
  orderId: "f3a665c9-..."

10. Sync Order Status

mcp__quantish__sync_order_status
  orderId: "f3a665c9-..."

Note: May show sizeMatched: 0 due to API lag even if filled. Use get_positions to confirm.

11. Claim Winnings (After Market Resolves)

mcp__quantish__get_claimable_winnings

mcp__quantish__claim_winnings
  positionId: "..."  // optional, claims all if omitted

Advanced Operations

Merge Tokens (Exit Position at $1)

If you hold both YES and NO tokens, merge them back to USDC:

mcp__quantish__merge_tokens
  conditionId: "0x..."

Transfer USDC

mcp__quantish__transfer_usdc
  toAddress: "0x..."
  amount: 5.0

Get Deposit Addresses

mcp__quantish__get_deposit_addresses

Supports deposits from Ethereum, Polygon, Arbitrum, Optimism, Base, Solana, and Bitcoin.

Best Practices

1. Always check orderbook first - Know the spread before placing orders
2. Use limit orders - GTC orders get price improvement
3. Start small - $1-2 trades until comfortable
4. Verify fills - Use get_positions not just order status
5. Check balances - Ensure sufficient USDC before trading

Error Handling

| Error | Cause | Fix | |-------|-------|-----| | "not enough balance" | Insufficient USDC | Deposit more or reduce size | | "order failed" | Price moved | Check orderbook, adjust price | | "invalid token" | Wrong tokenId | Get fresh market data |

Example: Complete Trade Flow

1. get_wallet_status → Confirm ready
2. get_balances → Check USDC
3. search_markets → Find market
4. get_orderbook → See bid/ask spread
5. place_order → Execute trade
6. get_positions → Verify fill

Source & license

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

• Author: joinQuantish
• Source: joinQuantish/skills
• License: MIT

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