@catalyst-team/poly-sdk 0.1.0 → 0.2.0

package/src/mcp/README.md

@@ -1,380 +0,0 @@
-# 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

@@ -1,124 +0,0 @@
-/**
- * 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');
-}