@catalyst-team/poly-sdk 0.1.0

package/src/mcp/README.md

@@ -0,0 +1,380 @@
+# Polymarket MCP Server
+
+A Model Context Protocol (MCP) server that exposes Polymarket functionality to AI agents.
+
+## Quick Start
+
+### Run with npx (after build)
+
+```bash
+# Build the package
+pnpm -F @prediction-router/poly-sdk build
+
+# Run the MCP server
+pnpm -F @prediction-router/poly-sdk mcp
+```
+
+### Development mode
+
+```bash
+pnpm -F @prediction-router/poly-sdk mcp:dev
+```
+
+## Claude Desktop Configuration
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+### Read-only mode (market data, orderbook, trader analysis)
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "node",
+      "args": ["/path/to/PerdictionRouter/packages/poly-sdk/dist/mcp/server.js"]
+    }
+  }
+}
+```
+
+### Trading mode (with private key)
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "node",
+      "args": ["/path/to/PerdictionRouter/packages/poly-sdk/dist/mcp/server.js"],
+      "env": {
+        "POLY_PRIVATE_KEY": "your-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+### Development mode
+
+```json
+{
+  "mcpServers": {
+    "polymarket": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/PerdictionRouter/packages/poly-sdk/src/mcp/server.ts"],
+      "env": {
+        "POLY_PRIVATE_KEY": "your-wallet-private-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `POLY_PRIVATE_KEY` | Wallet private key (with or without 0x prefix) | For trading |
+| `POLY_CHAIN_ID` | Chain ID (137=mainnet, 80002=testnet) | Optional (default: 137) |
+
+**Note**: API credentials are automatically derived from the private key using Polymarket's `createOrDeriveApiKey()`. You only need to provide the wallet private key to enable trading.
+
+## Available Tools
+
+### Trader Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_trader_positions` | Get current positions for a wallet address |
+| `get_trader_trades` | Get trade history for a wallet |
+| `get_trader_profile` | Get trader profile with PnL and stats |
+| `get_leaderboard` | Get top traders from leaderboard |
+
+### Market Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_market` | Get market details by slug or conditionId |
+| `search_markets` | Search markets by keyword |
+| `get_trending_markets` | Get trending markets by volume/liquidity |
+| `get_market_trades` | Get recent trades for a market |
+
+### Order Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_orderbook` | Get orderbook depth for a market outcome |
+| `get_best_prices` | Get best bid/ask prices for both outcomes |
+| `estimate_execution` | Estimate execution price and slippage |
+
+### Trade Tools (requires API credentials)
+
+| Tool | Description |
+|------|-------------|
+| `place_limit_order` | Place a limit order |
+| `place_market_order` | Place a market order |
+| `cancel_order` | Cancel an existing order |
+| `get_my_orders` | Get your open orders |
+
+### Wallet Tools (requires private key)
+
+| Tool | Description |
+|------|-------------|
+| `get_supported_deposit_assets` | Get all supported assets and chains for deposits |
+| `get_deposit_addresses` | Get deposit addresses (EVM, Solana, Bitcoin) |
+| `check_allowances` | Check ERC20 and ERC1155 allowances for trading |
+| `approve_trading` | Set up all required approvals for trading |
+
+## Tool Examples
+
+### Get Market
+
+```json
+{
+  "name": "get_market",
+  "arguments": {
+    "identifier": "will-bitcoin-hit-100k-in-2024"
+  }
+}
+```
+
+Response:
+```json
+{
+  "market": {
+    "conditionId": "0x...",
+    "question": "Will Bitcoin hit $100k in 2024?",
+    "slug": "will-bitcoin-hit-100k-in-2024"
+  },
+  "prices": {
+    "yes": 0.65,
+    "no": 0.35
+  },
+  "stats": {
+    "volume": 1500000,
+    "liquidity": 250000
+  }
+}
+```
+
+### Get Trader Positions
+
+```json
+{
+  "name": "get_trader_positions",
+  "arguments": {
+    "address": "0x1234..."
+  }
+}
+```
+
+Response:
+```json
+{
+  "trader": {
+    "address": "0x1234...",
+    "name": "TopTrader"
+  },
+  "positions": [
+    {
+      "market": "Will Bitcoin hit $100k?",
+      "outcome": "Yes",
+      "size": 1000,
+      "avgPrice": 0.55,
+      "currentPrice": 0.65,
+      "pnl": 100,
+      "pnlPercent": 18.18
+    }
+  ],
+  "summary": {
+    "totalPositions": 5,
+    "totalValue": 5000,
+    "unrealizedPnl": 500
+  }
+}
+```
+
+### Get Orderbook
+
+```json
+{
+  "name": "get_orderbook",
+  "arguments": {
+    "conditionId": "0x...",
+    "outcome": "Yes",
+    "depth": 10
+  }
+}
+```
+
+Response:
+```json
+{
+  "market": {
+    "conditionId": "0x...",
+    "title": "Will Bitcoin hit $100k?"
+  },
+  "outcome": "Yes",
+  "orderbook": {
+    "bids": [
+      { "price": 0.64, "size": 1000, "total": 640 },
+      { "price": 0.63, "size": 2000, "total": 1900 }
+    ],
+    "asks": [
+      { "price": 0.66, "size": 500, "total": 330 },
+      { "price": 0.67, "size": 1500, "total": 1335 }
+    ]
+  },
+  "summary": {
+    "bestBid": 0.64,
+    "bestAsk": 0.66,
+    "spread": 0.02,
+    "spreadPercent": 3.12
+  }
+}
+```
+
+### Estimate Execution
+
+```json
+{
+  "name": "estimate_execution",
+  "arguments": {
+    "conditionId": "0x...",
+    "outcome": "Yes",
+    "side": "BUY",
+    "amount": 1000
+  }
+}
+```
+
+Response:
+```json
+{
+  "market": "Will Bitcoin hit $100k?",
+  "order": {
+    "side": "BUY",
+    "outcome": "Yes",
+    "usdcAmount": 1000
+  },
+  "estimate": {
+    "avgPrice": 0.658,
+    "sharesReceived": 1519.76,
+    "priceImpact": 0.012,
+    "worstPrice": 0.67
+  },
+  "warning": null
+}
+```
+
+### Check Allowances
+
+```json
+{
+  "name": "check_allowances",
+  "arguments": {}
+}
+```
+
+Response:
+```json
+{
+  "wallet": "0x1234...",
+  "erc20": {
+    "usdc": {
+      "balance": "1000.00",
+      "allowances": [
+        { "contract": "CTF Exchange", "approved": true, "allowance": "unlimited" },
+        { "contract": "Neg Risk CTF Exchange", "approved": true, "allowance": "unlimited" }
+      ]
+    }
+  },
+  "erc1155": {
+    "conditionalTokens": {
+      "approvals": [
+        { "contract": "CTF Exchange", "approved": true },
+        { "contract": "Neg Risk CTF Exchange", "approved": true }
+      ]
+    }
+  },
+  "tradingReady": true,
+  "issues": []
+}
+```
+
+### Get Deposit Addresses
+
+```json
+{
+  "name": "get_deposit_addresses",
+  "arguments": {}
+}
+```
+
+Response:
+```json
+{
+  "wallet": "0x1234...",
+  "addresses": {
+    "evm": "0xabc...",
+    "solana": "ABC123...",
+    "bitcoin": "bc1q..."
+  },
+  "evmChains": ["Ethereum", "Polygon", "Arbitrum", "Base", "Optimism"],
+  "instructions": "Send assets to these addresses to deposit to your Polymarket account..."
+}
+```
+
+## Programmatic Usage
+
+You can also use the MCP tools programmatically:
+
+```typescript
+import { PolymarketSDK, createMcpHandler } from '@prediction-router/poly-sdk';
+
+const sdk = new PolymarketSDK();
+const handler = createMcpHandler(sdk);
+
+// Call any tool
+const result = await handler('get_market', {
+  identifier: 'btc-100k',
+});
+
+console.log(result);
+```
+
+Or register with an MCP server instance:
+
+```typescript
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { PolymarketSDK, registerMcpTools } from '@prediction-router/poly-sdk';
+
+const server = new Server(
+  { name: 'my-server', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+const sdk = new PolymarketSDK();
+registerMcpTools(server, sdk);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+## Architecture
+
+```
+src/mcp/
+├── index.ts          # Main exports and handler factory
+├── server.ts         # Standalone MCP server (CLI entry point)
+├── types.ts          # TypeScript type definitions
+├── errors.ts         # Error handling utilities
+├── tools/
+│   ├── index.ts      # Tool exports
+│   ├── trader.ts     # Trader analysis tools
+│   ├── market.ts     # Market discovery tools
+│   ├── order.ts      # Orderbook analysis tools
+│   ├── trade.ts      # Trading execution tools
+│   └── wallet.ts     # Deposit and authorization tools
+└── README.md         # This file
+```

package/src/mcp/errors.ts

@@ -0,0 +1,124 @@
+/**
+ * MCP Error Handling for Polymarket Tools
+ */
+
+export enum ErrorCode {
+  INVALID_ADDRESS = 'INVALID_ADDRESS',
+  MARKET_NOT_FOUND = 'MARKET_NOT_FOUND',
+  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
+  ORDER_REJECTED = 'ORDER_REJECTED',
+  RATE_LIMITED = 'RATE_LIMITED',
+  AUTH_REQUIRED = 'AUTH_REQUIRED',
+  INVALID_INPUT = 'INVALID_INPUT',
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+}
+
+export class McpToolError extends Error {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'McpToolError';
+  }
+
+  toResponse() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        details: this.details,
+      },
+    };
+  }
+}
+
+export function validateAddress(address: string): void {
+  if (!address || typeof address !== 'string') {
+    throw new McpToolError(
+      ErrorCode.INVALID_ADDRESS,
+      'Address is required'
+    );
+  }
+  if (!address.startsWith('0x') || address.length !== 42) {
+    throw new McpToolError(
+      ErrorCode.INVALID_ADDRESS,
+      'Address must be a valid Ethereum address (0x...)',
+      { address }
+    );
+  }
+}
+
+export function validateConditionId(conditionId: string): void {
+  if (!conditionId || typeof conditionId !== 'string') {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Condition ID is required'
+    );
+  }
+  if (!conditionId.startsWith('0x')) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Condition ID must start with 0x',
+      { conditionId }
+    );
+  }
+}
+
+export function validateOutcome(outcome: string): void {
+  if (!['Yes', 'No'].includes(outcome)) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Outcome must be "Yes" or "No"',
+      { outcome }
+    );
+  }
+}
+
+export function validateSide(side: string): void {
+  if (!['BUY', 'SELL'].includes(side)) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Side must be "BUY" or "SELL"',
+      { side }
+    );
+  }
+}
+
+export function validatePrice(price: number): void {
+  if (typeof price !== 'number' || price < 0.001 || price > 0.999) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      'Price must be between 0.001 and 0.999',
+      { price }
+    );
+  }
+}
+
+export function validatePositiveNumber(value: number, name: string): void {
+  if (typeof value !== 'number' || value <= 0) {
+    throw new McpToolError(
+      ErrorCode.INVALID_INPUT,
+      `${name} must be a positive number`,
+      { [name]: value }
+    );
+  }
+}
+
+export function wrapError(err: unknown): McpToolError {
+  if (err instanceof McpToolError) {
+    return err;
+  }
+  if (err instanceof Error) {
+    // Check for known error types
+    if (err.message.includes('rate limit')) {
+      return new McpToolError(ErrorCode.RATE_LIMITED, 'Rate limit exceeded');
+    }
+    if (err.message.includes('not found')) {
+      return new McpToolError(ErrorCode.MARKET_NOT_FOUND, err.message);
+    }
+    return new McpToolError(ErrorCode.INTERNAL_ERROR, err.message);
+  }
+  return new McpToolError(ErrorCode.INTERNAL_ERROR, 'An unexpected error occurred');
+}