# Polymarket MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with the ability to interact with Polymarket.

## Features

- **Market Discovery**: Browse and search current prediction markets
- **Real-time Data**: Get detailed market information, prices, and statistics
- **Trading**: Place market orders (FOK/FAK) and limit orders (GTC/GTD)
- **Portfolio Management**: View balances, positions, and P&L
- **Order Management**: Track and manage your active orders
- **Multi-format Support**: Works with market slugs or direct token IDs

## Installation

### 1. Clone and Install

```bash
git clone https://github.com/yourusername/polymarket-mcp-server.git
cd <folder-name>
pnpm install
```

### 2. Install Required Dependencies

```bash
pnpm install @modelcontextprotocol/sdk zod @polymarket/clob-client ethers
```

### 3. Environment Configuration

Create a `.env` file in the project root:

```env
# Required: Your Polygon wallet private key
PRIVATE_KEY=your_private_key_here

# Optional: Custom CLOB API URL (defaults to https://clob.polymarket.com)
CLOB_API_URL=https://clob.polymarket.com

# Optional: Signature type (defaults to 0)
SIGNATURE_TYPE=0

# Optional: Existing API credentials (will be auto-generated if not provided)
CLOB_API_KEY=your_api_key
CLOB_SECRET=your_secret
CLOB_PASS_PHRASE=your_passphrase
```

### 4. MCP Configuration

Add the server to your MCP settings file:

```json
{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/path/to/your/index.js"],
      "env": {
        "PRIVATE_KEY": "your_private_key_here"
      }
    }
  }
}
```

## Available Tools

### 1. Market Discovery

#### `getAllMarkets`
Get current prediction markets with optional filtering.

```
Get me today's trending markets
```

#### `getMarketDetails`  
Get detailed information about a specific market using its slug.

```
Get details for the market "will-donald-trump-win-the-2024-us-presidential-election"
Show me info about "bitcoin-above-100k-by-end-of-2024"
```

### 2. Trading Operations

#### `placeMarketOrder`
Execute immediate market orders (Fill or Kill / Fill and Kill).

```
Buy $100 of YES on "bitcoin-above-100k-by-end-of-2024" using FOK order
Sell $50 of NO on the Trump election market with FAK
```

**Parameters:**
- `marketSlug` or `tokenID`: Market identifier
- `outcome`: YES or NO (if using marketSlug)
- `amount`: USD amount to trade
- `side`: BUY or SELL
- `orderType`: FOK (Fill or Kill) or FAK (Fill and Kill)

#### `placeLimitOrder`
Place limit orders at specific prices (Good Till Cancelled / Good Till Date).

```
Place a limit buy order for 100 shares at $0.65 on the Bitcoin market
Set a GTC sell order for 50 shares at $0.80 on Trump election
```

**Parameters:**
- `marketSlug` or `tokenID`: Market identifier  
- `outcome`: YES or NO (if using marketSlug)
- `price`: Price per share (0-1)
- `size`: Number of shares
- `side`: BUY or SELL
- `orderType`: GTC (Good Till Cancelled) or GTD (Good Till Date)
- `expirationMinutes`: Expiration time (GTD only)

### 3. Portfolio Management

#### `getPortfolio`
View complete portfolio including balances and positions.

```
Show me my portfolio
What's my current P&L?
Check my USDC balance
```

#### `getOrder`
Get details of a specific order by ID.

```
Check order status for 0x831680cb77da95792af5a052c87c8abf9d2ae5cb21f275670bc0ff58f2823c5c
```

## Usage Examples

### Starting the Server
## Important: Always run the server using Node.js directly to ensure proper initialization:

```bash
node <path-to-index.js>
```

This will:

Initialize your wallet connection
Set up required token allowances (USDC approvals for CTF and Exchange contracts)
Generate or use existing API credentials
Start the MCP server

### Basic Market Research

```
"Get details about the market 'ai-will-achieve-agi-by-2025'"

```

### Simple Trading

```
"Buy $20 of YES on 'will-spacex-reach-mars-by-2030' using a market order"
```

### Portfolio Monitoring

```
"Show me my current portfolio and P&L"

"Check my USDC balance on Polymarket"
```

### Advanced Trading

```
"Set a GTC limit sell order for 100 shares at $0.85 on token ID 123456"

"Place a FOK buy order for $500 on the climate change market"

"Check the status of my order 0x831680..."
```

## Market Slug Examples

Market slugs are found in Polymarket URLs:

- `https://polymarket.com/event/will-donald-trump-win-the-2024-us-presidential-election`
  - Slug: `will-donald-trump-win-the-2024-us-presidential-election`

- `https://polymarket.com/event/bitcoin-above-100k-by-end-of-2024`  
  - Slug: `bitcoin-above-100k-by-end-of-2024`


### API Limits
- Polymarket may have rate limits on API calls
- Large orders may have slippage on smaller markets
- Some markets may have low liquidity

## Troubleshooting

### Common Issues

**"Client not initialized"**
- Check your `PRIVATE_KEY` is set correctly
- Ensure you have USDC balance for gas fees
- Verify Polygon network connectivity

**"Market not found"**
- Double-check the market slug spelling
- Ensure the market is still active
- Try using direct token ID instead

**"Insufficient balance"**
- Add USDC to your Polygon wallet
- Check if allowances were set properly
- Verify you're on Polygon Mainnet

**"Order failed"**
- Check if market is still open for trading
- Verify price is within valid range (0-1)
- Ensure sufficient balance for the trade

## API Reference

### Market Data Endpoints
- **Gamma API**: `https://gamma-api.polymarket.com/markets`
- **Data API**: `https://data-api.polymarket.com/positions`
- **CLOB API**: `https://clob.polymarket.com`

### Contract Addresses (Polygon)
- **USDC**: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
- **CTF**: `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045`  
- **Exchange**: `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E`

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Support

- **Issues**: [GitHub Issues](https://github.com/PlayAINetwork/Polymarket-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/PlayAINetwork/Polymarket-mcp/discussions)