@catalyst-team/poly-mcp 0.1.1 → 0.1.2

package/docs/01-mcp.md

@@ -195,9 +195,12 @@ GET https://data-api.polymarket.com/trades?market={conditionId}
 | Tool | 用户问题 | 返回 |
 |------|----------|------|
 | `get_trader_positions` | "他持有什么仓位？" | 持仓列表 + PnL |
-| `get_trader_trades` | "他最近交易了什么？" | 交易历史 |
+| `get_trader_closed_positions` | "他已平仓位怎么样？" | 已结算持仓 + 已实现 PnL |
+| `get_trader_trades` | "他最近交易了什么？" | 仅交易记录 (BUY/SELL) |
+| `get_trader_activity` | "他完整活动历史？" | 全部活动 (TRADE/SPLIT/MERGE/REDEEM...) |
 | `get_trader_profile` | "他是什么水平？" | 综合分析 |
 | `get_leaderboard` | "谁是顶级交易者？" | 排行榜 |
+| `get_account_value` | "他账户值多少钱？" | 账户总价值 |
 
 ### 4.1 `get_trader_positions`
 
@@ -269,7 +272,84 @@ GET https://data-api.polymarket.com/trades?market={conditionId}
 }
 ```
 
-### 4.2 `get_trader_trades`
+### 4.2 `get_trader_closed_positions`
+
+**用户场景**: "他已经平掉的仓位表现如何？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_trader_closed_positions",
+  "description": "Get closed/settled positions for a trader with realized PnL",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "address": {
+        "type": "string",
+        "description": "Trader wallet address (0x...)"
+      },
+      "limit": {
+        "type": "number",
+        "description": "Maximum positions to return (max 50)",
+        "default": 20
+      },
+      "sortBy": {
+        "type": "string",
+        "enum": ["REALIZEDPNL", "TIMESTAMP", "TITLE"],
+        "description": "Sort by field",
+        "default": "REALIZEDPNL"
+      }
+    },
+    "required": ["address"]
+  }
+}
+```
+
+**Input**:
+```json
+{
+  "address": "0xc2e7800b...",
+  "limit": 10,
+  "sortBy": "REALIZEDPNL"
+}
+```
+
+**Output**:
+```json
+{
+  "trader": {
+    "address": "0xc2e7800b...",
+    "displayName": "beachboy4"
+  },
+  "closedPositions": [
+    {
+      "market": {
+        "conditionId": "0x39e493c3...",
+        "title": "Spread: Grizzlies (-12.5)",
+        "slug": "nba-was-mem-2025-12-20"
+      },
+      "holding": {
+        "outcome": "Wizards",
+        "avgPrice": 0.52,
+        "settlementPrice": 1.00
+      },
+      "pnl": {
+        "realized": 646022.34,
+        "totalBought": 700803.12
+      },
+      "settledAt": "2025-12-21T00:00:00Z"
+    }
+  ],
+  "summary": {
+    "totalClosed": 10,
+    "totalRealizedPnl": 802943.86,
+    "winningPositions": 8,
+    "losingPositions": 2
+  }
+}
+```
+
+### 4.3 `get_trader_trades`
 
 **用户场景**: "他最近买了什么？卖了什么？"
 
@@ -345,7 +425,103 @@ GET https://data-api.polymarket.com/trades?market={conditionId}
 }
 ```
 
-### 4.3 `get_trader_profile`
+### 4.4 `get_trader_activity`
+
+**用户场景**: "他的完整活动历史是什么？有没有 SPLIT/MERGE 操作（可能是 Bot）？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_trader_activity",
+  "description": "Get complete activity history for a trader including TRADE, SPLIT, MERGE, REDEEM, REWARD, CONVERSION",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "address": {
+        "type": "string",
+        "description": "Trader wallet address (0x...)"
+      },
+      "limit": {
+        "type": "number",
+        "description": "Maximum number of activities to return",
+        "default": 50
+      },
+      "type": {
+        "type": "string",
+        "enum": ["TRADE", "SPLIT", "MERGE", "REDEEM", "REWARD", "CONVERSION"],
+        "description": "Filter by activity type"
+      },
+      "market": {
+        "type": "string",
+        "description": "Filter by market conditionId"
+      }
+    },
+    "required": ["address"]
+  }
+}
+```
+
+**Input 示例 1** - 获取全部活动:
+```json
+{
+  "address": "0xc2e7800b...",
+  "limit": 100
+}
+```
+
+**Input 示例 2** - 检测 Bot（过滤 SPLIT/MERGE）:
+```json
+{
+  "address": "0xc2e7800b...",
+  "type": "SPLIT"
+}
+```
+
+**Input 示例 3** - 分析特定市场的活动:
+```json
+{
+  "address": "0xc2e7800b...",
+  "market": "0x39e493c3...",
+  "limit": 100
+}
+```
+
+**Output**:
+```json
+{
+  "trader": {
+    "address": "0xc2e7800b...",
+    "displayName": null
+  },
+  "activities": [
+    {
+      "type": "SPLIT",
+      "market": {
+        "conditionId": "0x39e493c3...",
+        "title": "Trump 2024"
+      },
+      "size": 1000,
+      "usdcValue": 1000,
+      "timestamp": "2025-12-20T15:30:45Z",
+      "txHash": "0x5fd43582..."
+    }
+  ],
+  "summary": {
+    "total": 50,
+    "byType": {
+      "TRADE": 40,
+      "SPLIT": 5,
+      "MERGE": 3,
+      "REDEEM": 2
+    },
+    "totalVolume": 50000
+  }
+}
+```
+
+**Note**: 如果 `byType` 中有大量 SPLIT/MERGE，可能是套利 Bot 或做市商。
+
+### 4.5 `get_trader_profile`
 
 **用户场景**: "这个人厉害吗？值得跟单吗？"
 
@@ -407,7 +583,7 @@ GET https://data-api.polymarket.com/trades?market={conditionId}
 }
 ```
 
-### 4.4 `get_leaderboard`
+### 4.6 `get_leaderboard`
 
 **用户场景**: "谁是最赚钱的交易者？"
 
@@ -463,6 +639,49 @@ GET https://data-api.polymarket.com/trades?market={conditionId}
 }
 ```
 
+### 4.7 `get_account_value`
+
+**用户场景**: "这个钱包账户值多少钱？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_account_value",
+  "description": "Get total value of a user's positions",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "address": {
+        "type": "string",
+        "description": "User wallet address (0x...)"
+      },
+      "market": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Optional: filter by specific market conditionIds"
+      }
+    },
+    "required": ["address"]
+  }
+}
+```
+
+**Input**:
+```json
+{
+  "address": "0xc2e7800b..."
+}
+```
+
+**Output**:
+```json
+{
+  "address": "0xc2e7800b...",
+  "value": 1346825.46,
+  "currency": "USDC"
+}
+```
+
 ---
 
 ## 5. Market Tools（市场查询）
@@ -1834,6 +2053,301 @@ export function registerTraderTools(server: Server, sdk: PolymarketSDK) {
 
 ---
 
+## 9. On-Chain Tools（链上数据 - Subgraph）
+
+> 基于 Goldsky 托管的 Polymarket Subgraph，提供链上数据查询
+
+### 工具列表
+
+| Tool | 用户问题 | 数据来源 |
+|------|----------|----------|
+| `get_market_open_interest` | "这个市场有多少 OI？" | OI Subgraph |
+| `get_global_open_interest` | "Polymarket 总 OI 是多少？" | OI Subgraph |
+| `get_condition_status` | "这个市场结算了吗？" | PnL Subgraph |
+| `get_onchain_activity` | "这个用户链上做了什么？" | Activity Subgraph |
+| `get_order_fills` | "最近有什么成交？" | Orderbook Subgraph |
+
+### 9.1 `get_market_open_interest`
+
+**用户场景**: "0xfa48a993 这个市场有多少资金在里面？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_market_open_interest",
+  "description": "Get open interest for a specific market from on-chain data",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "conditionId": {
+        "type": "string",
+        "description": "Market condition ID (0x...)"
+      }
+    },
+    "required": ["conditionId"]
+  }
+}
+```
+
+**Input**:
+```json
+{
+  "conditionId": "0xfa48a993..."
+}
+```
+
+**Output** (基于真实 Subgraph):
+```json
+{
+  "market": {
+    "conditionId": "0xfa48a993...",
+    "question": "US recession in 2025?"
+  },
+  "openInterest": {
+    "raw": "11010561190000",
+    "formatted": "11,010,561.19",
+    "currency": "USDC"
+  },
+  "rank": 15,
+  "percentOfTotal": 3.31
+}
+```
+
+### 9.2 `get_global_open_interest`
+
+**用户场景**: "Polymarket 现在总共有多少资金？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_global_open_interest",
+  "description": "Get total open interest across all Polymarket markets",
+  "inputSchema": {
+    "type": "object",
+    "properties": {}
+  }
+}
+```
+
+**Output** (基于真实 Subgraph - 已验证):
+```json
+{
+  "globalOpenInterest": {
+    "raw": "332425854000000",
+    "formatted": "332,425,854",
+    "currency": "USDC"
+  },
+  "topMarkets": [
+    {
+      "conditionId": "0xc6485bb7...",
+      "openInterest": "71,147,696",
+      "percentOfTotal": 21.41
+    },
+    {
+      "conditionId": "0x95534417...",
+      "openInterest": "60,486,105",
+      "percentOfTotal": 18.20
+    }
+  ]
+}
+```
+
+### 9.3 `get_condition_status`
+
+**用户场景**: "这个市场结算了吗？谁赢了？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_condition_status",
+  "description": "Check if a market condition is resolved and get payout information",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "conditionId": {
+        "type": "string",
+        "description": "Market condition ID (0x...)"
+      }
+    },
+    "required": ["conditionId"]
+  }
+}
+```
+
+**Input**:
+```json
+{
+  "conditionId": "0xfa48a993..."
+}
+```
+
+**Output** (基于真实 Subgraph):
+```json
+{
+  "conditionId": "0xfa48a993...",
+  "resolved": true,
+  "payout": {
+    "numerators": ["1", "0"],
+    "denominator": "1",
+    "winningOutcome": "Yes",
+    "winningIndex": 0
+  },
+  "positionIds": [
+    "10417...yes_token_id",
+    "44528...no_token_id"
+  ]
+}
+```
+
+**未结算市场**:
+```json
+{
+  "conditionId": "0x00000977...",
+  "resolved": false,
+  "payout": null,
+  "positionIds": ["44554...", "56914..."]
+}
+```
+
+### 9.4 `get_onchain_activity`
+
+**用户场景**: "这个用户在链上做过什么操作？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_onchain_activity",
+  "description": "Get user's on-chain CTF activity (splits, merges, redemptions)",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "address": {
+        "type": "string",
+        "description": "User wallet address (0x...)"
+      },
+      "limit": {
+        "type": "number",
+        "description": "Maximum events per type",
+        "default": 20
+      }
+    },
+    "required": ["address"]
+  }
+}
+```
+
+**Input**:
+```json
+{
+  "address": "0xc2e7800b...",
+  "limit": 10
+}
+```
+
+**Output** (基于真实 Subgraph):
+```json
+{
+  "address": "0xc2e7800b...",
+  "activity": {
+    "splits": [
+      {
+        "id": "0xbff75087...",
+        "timestamp": "2025-12-20T15:30:00Z",
+        "condition": "0x2506d9db...",
+        "amount": "5000000"
+      }
+    ],
+    "merges": [],
+    "redemptions": [
+      {
+        "id": "0xff097248...",
+        "timestamp": "2025-12-20T15:35:00Z",
+        "condition": "0x76f39bb0...",
+        "payout": "10000000"
+      }
+    ]
+  },
+  "summary": {
+    "totalSplits": 5,
+    "totalMerges": 0,
+    "totalRedemptions": 12,
+    "totalPayoutReceived": "50000000"
+  }
+}
+```
+
+### 9.5 `get_order_fills`
+
+**用户场景**: "最近有什么大单成交？" / "这个用户成交了什么？"
+
+**MCP Tool Definition**:
+```json
+{
+  "name": "get_order_fills",
+  "description": "Get recent order fill events from on-chain data",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "maker": {
+        "type": "string",
+        "description": "Filter by maker address (optional)"
+      },
+      "taker": {
+        "type": "string",
+        "description": "Filter by taker address (optional)"
+      },
+      "limit": {
+        "type": "number",
+        "description": "Maximum number of fills",
+        "default": 20
+      }
+    }
+  }
+}
+```
+
+**Input (最近成交)**:
+```json
+{
+  "limit": 10
+}
+```
+
+**Input (特定用户)**:
+```json
+{
+  "maker": "0xbbaa9ffc...",
+  "limit": 10
+}
+```
+
+**Output** (基于真实 Subgraph - 已验证):
+```json
+{
+  "fills": [
+    {
+      "id": "0xf4dd79c7...",
+      "orderHash": "0x25e7d399...",
+      "maker": "0xd0d6053c...",
+      "taker": "0x4bfb41d5...",
+      "makerAssetId": "59975245897...",
+      "takerAssetId": "0",
+      "makerAmountFilled": "13600000",
+      "takerAmountFilled": "8024000",
+      "fee": "0",
+      "timestamp": "2025-12-20T16:00:00Z",
+      "txHash": "0xf4dd79c7..."
+    }
+  ],
+  "summary": {
+    "totalFills": 10,
+    "totalVolume": "135000000"
+  }
+}
+```
+
+---
+
 ## 10. 配置与认证
 
 ### 10.1 环境变量
@@ -2022,34 +2536,42 @@ echo '{"method":"tools/call","params":{"name":"get_trader_positions","arguments"
 | # | Tool | 类别 | 优先级 | 需要私钥 |
 |---|------|------|--------|----------|
 | 1 | `get_trader_positions` | Trader | P0 | ❌ |
-| 2 | `get_trader_trades` | Trader | P1 | ❌ |
-| 3 | `get_trader_profile` | Trader | P1 | ❌ |
-| 4 | `get_leaderboard` | Trader | P1 | ❌ |
-| 5 | `get_market` | Market | P0 | ❌ |
-| 6 | `search_markets` | Market | P1 | ❌ |
-| 7 | `get_trending_markets` | Market | P3 | ❌ |
-| 8 | `get_market_trades` | Market | P1 | ❌ |
-| 9 | `get_orderbook` | Order | P0 | ❌ |
-| 10 | `get_best_prices` | Order | P1 | ❌ |
-| 11 | `estimate_execution` | Order | P3 | ❌ |
-| 12 | `place_limit_order` | Trade | P2 | ✅ |
-| 13 | `place_market_order` | Trade | P2 | ✅ |
-| 14 | `cancel_order` | Trade | P2 | ✅ |
-| 15 | `get_my_orders` | Trade | P2 | ✅ |
-| 16 | `get_supported_deposit_assets` | Wallet | P1 | ❌ |
-| 17 | `get_deposit_addresses` | Wallet | P1 | ✅ |
-| 18 | `deposit_usdc` | Wallet | P2 | ✅ |
-| 19 | `check_allowances` | Wallet | P1 | ✅ |
-| 20 | `approve_trading` | Wallet | P2 | ✅ |
-| 21 | `swap` | Wallet | P2 | ✅ |
-| 22 | `swap_and_deposit` | Wallet | P2 | ✅ |
-| 23 | `get_token_balances` | Wallet | P1 | ✅ |
-| 24 | `get_wallet_balances` | Wallet | P1 | ❌ |
-| 25 | `get_swap_quote` | Wallet | P1 | ❌ |
-| 26 | `get_available_pools` | Wallet | P1 | ❌ |
-| 27 | `get_usage_guide` | Guide | P0 | ❌ |
-
-**Total: 27 Tools**
+| 2 | `get_trader_closed_positions` | Trader | P1 | ❌ |
+| 3 | `get_trader_trades` | Trader | P1 | ❌ |
+| 4 | `get_trader_activity` | Trader | P1 | ❌ |
+| 5 | `get_trader_profile` | Trader | P1 | ❌ |
+| 6 | `get_leaderboard` | Trader | P1 | ❌ |
+| 7 | `get_account_value` | Trader | P1 | ❌ |
+| 7 | `get_market` | Market | P0 | ❌ |
+| 8 | `search_markets` | Market | P1 | ❌ |
+| 9 | `get_trending_markets` | Market | P3 | ❌ |
+| 10 | `get_market_trades` | Market | P1 | ❌ |
+| 11 | `get_orderbook` | Order | P0 | ❌ |
+| 12 | `get_best_prices` | Order | P1 | ❌ |
+| 13 | `estimate_execution` | Order | P3 | ❌ |
+| 14 | `place_limit_order` | Trade | P2 | ✅ |
+| 15 | `place_market_order` | Trade | P2 | ✅ |
+| 16 | `cancel_order` | Trade | P2 | ✅ |
+| 17 | `get_my_orders` | Trade | P2 | ✅ |
+| 18 | `get_supported_deposit_assets` | Wallet | P1 | ❌ |
+| 19 | `get_deposit_addresses` | Wallet | P1 | ✅ |
+| 20 | `deposit_usdc` | Wallet | P2 | ✅ |
+| 21 | `check_allowances` | Wallet | P1 | ✅ |
+| 22 | `approve_trading` | Wallet | P2 | ✅ |
+| 23 | `swap` | Wallet | P2 | ✅ |
+| 24 | `swap_and_deposit` | Wallet | P2 | ✅ |
+| 25 | `get_token_balances` | Wallet | P1 | ✅ |
+| 26 | `get_wallet_balances` | Wallet | P1 | ❌ |
+| 27 | `get_swap_quote` | Wallet | P1 | ❌ |
+| 28 | `get_available_pools` | Wallet | P1 | ❌ |
+| 29 | `get_usage_guide` | Guide | P0 | ❌ |
+| 30 | `get_market_open_interest` | On-Chain | P1 | ❌ |
+| 31 | `get_global_open_interest` | On-Chain | P1 | ❌ |
+| 32 | `get_condition_status` | On-Chain | P1 | ❌ |
+| 33 | `get_onchain_activity` | On-Chain | P1 | ❌ |
+| 34 | `get_order_fills` | On-Chain | P1 | ❌ |
+
+**Total: 34 Tools**
 
 ---