MCP Polymarket

Package: @iqai/mcp-polymarket
Purpose: Interacting with the Polymarket prediction market for trading and market analysis.

Usage with ADK TypeScript

import {McpPolymarket} from "@iqai/adk";

const toolset = McpPolymarket({
  env: {
    FUNDER_ADDRESS: process.env.FUNDER_ADDRESS,
    POLYMARKET_PRIVATE_KEY: process.env.POLYMARKET_PRIVATE_KEY,
  },
})

const tools = await toolset.getTools()

import {McpToolset} from "@iqai/adk";

const toolset = new McpToolset({
  name: "Polymarket MCP Client",
  description: "Client for Polymarket prediction market operations",
  transport: {
    mode: "stdio",
    command: "pnpm",
    args: ["dlx", "@iqai/mcp-polymarket"],
    env: {
      FUNDER_ADDRESS: process.env.FUNDER_ADDRESS,
      POLYMARKET_PRIVATE_KEY: process.env.POLYMARKET_PRIVATE_KEY,
      PATH: process.env.PATH || "",
    },
  },
})

const tools = await toolset.getTools()

{
  "mcpServers": {
    "polymarket-mcp-server": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-polymarket"],
      "env": {
        "FUNDER_ADDRESS": "your_funder_address_here",
        "POLYMARKET_PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}

Features

Interact with Polymarket prediction markets
Trade prediction market positions
Access market data and analytics
Manage positions and orders

Available Tools

get_market_by_slug

slug:string

Description

Get detailed information about a specific market by its slug identifier. The slug can be extracted from the Polymarket URL.

get_event_by_slug

slug:string

Description

Get detailed information about a specific event by its slug identifier. Events group multiple related markets.

list_active_markets

limit:numberoffset:number

Description

List all currently active markets with pagination. Returns markets that are not yet closed.

search_markets

query:string

Description

Search for markets, events, and profiles using text search.

get_markets_by_tag

tag_id:stringlimit:numberclosed:boolean

Description

Get markets filtered by a specific tag ID. Useful for finding markets in specific categories.

get_all_tags

No parameters

Description

Get a list of all available tags for categorizing markets.

get_order_book

token_id:string

Description

Get the current order book for a specific market token. Shows all active buy and sell orders.

approve_allowances

waitForConfirmations:integer

Description

Grant the USDC and Conditional Tokens approvals required to trade on Polymarket. Automatically approves only the contracts that don't already have approvals set. Includes both regular and NegRisk markets. These approvals are standard ERC20/ERC1155 approvals, revocable at any time in your wallet.

place_order

tokenId:stringprice:numbersize:numberside:stringorderType:string

Description

Place a limit order on Polymarket at a specific price. Specify the number of shares (size) and price (0-1). For both BUY and SELL, you specify the number of shares you want to trade. Example: size=10, price=0.6 means buy/sell 10 shares at $0.60 per share (total: $6).

place_market_order

tokenId:stringamount:numberside:stringorderType:string

Description

Place a market order that executes immediately at current market price. IMPORTANT: For BUY orders, amount is the dollar amount ($USD) you want to spend. For SELL orders, amount is the number of shares to sell. Example: amount=5, side=BUY means 'spend $5 to buy shares at market price'. Minimum $1 for BUY orders.

get_open_orders

market:string

Description

Get all open orders for the authenticated account. Can optionally filter by market.

get_order

orderId:string

Description

Get details of a specific order by its ID.

cancel_order

orderId:string

Description

Cancel a specific order by its ID.

cancel_all_orders

No parameters

Description

Cancel all open orders for the authenticated account.

get_trade_history

market:stringmaker_address:string

Description

Get trade history for the authenticated account. Can optionally filter by market or maker address.

get_balance_allowance

assetType:stringtokenID:string

Description

Get balance and allowance information for the authenticated account. Can check COLLATERAL or CONDITIONAL tokens.

update_balance_allowance

assetType:stringtokenID:string

Description

Update balance and allowance for the authenticated account. Required before trading.

redeem_positions

conditionId:stringtokenId:stringoutcomeIndex:numbernegRisk:boolean

Description

Redeem (claim) winnings from a resolved Polymarket prediction market. Use this to collect USDC from positions in markets that have been settled. For regular markets, you need the conditionId. For negative risk markets, you also need the tokenId and should set negRisk=true. The market must be resolved before redemption is possible.

get_positions

user:stringlimit:number

Description

Get all positions for a wallet address with current values. Returns position details including size, current price, current value, and P&L. Uses the Polymarket Data API for accurate position valuation.

Environment Variables

Security

Private keys are used for trading operations. Handle with care and never commit them to version control.

FUNDER_ADDRESS: Required. Available to copy from the user menu dropdown on the Polymarket website (different from the wallet address used to log in).
POLYMARKET_PRIVATE_KEY: Required. Private key of the wallet that interacts with Polymarket.

Usage Examples

Here's a complete example of using MCP Polymarket with an ADK agent:

import { McpPolymarket, AgentBuilder } from "@iqai/adk";
import dotenv from "dotenv";

dotenv.config();

async function main() {
  // Initialize Polymarket MCP toolset
  const toolset = McpPolymarket({
    env: {
      FUNDER_ADDRESS: process.env.FUNDER_ADDRESS,
      POLYMARKET_PRIVATE_KEY: process.env.POLYMARKET_PRIVATE_KEY,
    },
    debug: false,
    retryOptions: {
      maxRetries: 3,
      initialDelay: 500,
    },
  });

  // Get available tools
  const polymarketTools = await toolset.getTools();

  // Create agent with Polymarket tools
  const { runner } = await AgentBuilder.create("polymarket_agent")
    .withModel("gemini-2.5-flash")
    .withDescription(
      "An agent that interacts with Polymarket prediction markets",
    )
    .withTools(...polymarketTools)
    .build();

  try {
    // Example queries
    const response = await runner.ask(
      "Show me available markets on Polymarket",
    );
    console.log(response);
  } finally {
    // Clean up resources
    await toolset.close();
  }
}

main().catch(console.error);

Getting Your Credentials

Funder Address

Log in to Polymarket
Click on your user menu (dropdown)
Copy the Funder Address (this is different from your wallet address)

Private Key

The POLYMARKET_PRIVATE_KEY is the private key of the wallet you use to interact with Polymarket. Ensure this wallet has sufficient funds for trading operations.

Important

Never share your private key or commit it to version control. Always use environment variables or secure secret management systems.

Best Practices

Security: Store private keys in environment variables, never hardcode them
Resource Cleanup: Always call await toolset.close() when done to properly close connections
Error Handling: Implement proper error handling for trading operations
Rate Limits: Be aware of Polymarket API rate limits and implement appropriate retry logic

Error Handling

Error Scenarios

The server handles various error scenarios gracefully.

🚨 Missing credentials: Ensure both FUNDER_ADDRESS and POLYMARKET_PRIVATE_KEY are set 💸 Insufficient balance: Ensure your wallet has sufficient funds for trading operations 🔄 Invalid market identifiers: Verify market IDs are correct 🌐 Network issues: Check your internet connection and Polymarket API status 🛑 Transaction failures: Review transaction details and ensure proper gas settings

Resources

Polymarket - Polymarket prediction market platform
Model Context Protocol - MCP specification and standards

MCP Polymarket

On this page