@catalyst-team/poly-sdk 0.1.0

package/scripts/truth.md

@@ -0,0 +1,440 @@
+# Polymarket 下单真相 (Truth About Order Placement)
+
+本文档记录了从部署到下单过程中的所有发现和真相。
+
+## 1. Polymarket 合约架构
+
+Polymarket 使用多个智能合约来处理不同类型的市场：
+
+### 1.1 合约地址 (Polygon Mainnet)
+
+| 合约名称 | 地址 | 用途 |
+|---------|------|------|
+| **USDC.e** | `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174` | 交易代币 (桥接的 USDC) |
+| **CTF Exchange** | `0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E` | 普通条件代币交易所 |
+| **Neg Risk CTF Exchange** | `0xC5d563A36AE78145C45a50134d48A1215220f80a` | 负风险市场交易所 |
+| **Neg Risk Adapter** | `0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296` | 负风险市场适配器 |
+| **Conditional Tokens** | `0x4D97DCd97eC945f40cF65F87097ACe5EA0476045` | 条件代币合约 |
+
+### 1.2 市场类型
+
+1. **普通市场 (Regular Markets)**
+   - 使用 CTF Exchange
+   - 两个结果: YES/NO
+   - 只需要 CTF Exchange 的 allowance
+
+2. **负风险市场 (Neg Risk Markets)**
+   - 使用 Neg Risk CTF Exchange + Neg Risk Adapter
+   - 例如: "NVIDIA 会成为市值最大的公司吗?"
+   - **需要额外授权 Neg Risk Adapter 合约！**
+
+### 1.3 如何判断市场类型?
+
+查看 token ID 的结构或通过 CLOB API 检查 `negRisk` 字段：
+
+```typescript
+const isNegRisk = await tradingClient.isNegRisk(tokenId);
+```
+
+## 2. Allowance 授权要求
+
+### 2.1 必须授权的合约
+
+要在 Polymarket 上交易，USDC.e 必须授权给以下合约：
+
+```
+✅ CTF Exchange              - 普通市场必需
+✅ Neg Risk CTF Exchange     - 负风险市场必需
+✅ Neg Risk Adapter          - 负风险市场必需 (容易遗漏！)
+✅ Conditional Tokens        - Split/Merge 操作必需
+```
+
+### 2.2 常见错误
+
+**错误信息**: `"not enough balance / allowance"`
+
+**可能原因**:
+1. ❌ USDC.e 余额不足
+2. ❌ 某个合约没有 allowance
+3. ❌ **Neg Risk Adapter 没有授权** (最容易遗漏)
+
+### 2.3 检查脚本
+
+```bash
+# 检查所有 allowance
+npx tsx scripts/check-all-allowances.ts
+
+# 授权所有缺失的合约
+npx tsx scripts/check-all-allowances.ts --approve
+```
+
+### 2.4 手动授权
+
+如果脚本失败，可以在 Polygonscan 上手动授权：
+
+1. 访问 https://polygonscan.com/token/0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174#writeContract
+2. 连接钱包
+3. 调用 `approve(spender, amount)`:
+   - spender: 合约地址 (如 `0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296`)
+   - amount: `115792089237316195423570985008687907853269984665640564039457584007913129639935` (MaxUint256)
+
+## 3. 订单类型差异
+
+### 3.1 GTC vs FOK
+
+| 订单类型 | 全称 | 用途 | API 方法 |
+|---------|------|------|----------|
+| **GTC** | Good Till Cancelled | 限价单，挂单等待成交 | `createAndPostOrder()` |
+| **GTD** | Good Till Date | 限价单，有过期时间 | `createAndPostOrder()` |
+| **FOK** | Fill or Kill | 市价单，立即成交或取消 | `createAndPostMarketOrder()` |
+| **FAK** | Fill and Kill | 市价单，部分成交也可以 | `createAndPostMarketOrder()` |
+
+### 3.2 代码区别
+
+```typescript
+// GTC 限价单 (Earning Engine 使用)
+const limitOrder = await trading.createOrder({
+  tokenId: '...',
+  side: 'BUY',
+  price: 0.50,  // 限价
+  size: 10,     // 份数
+  orderType: 'GTC',
+});
+
+// FOK 市价单 (套利脚本使用)
+const marketOrder = await trading.createMarketOrder({
+  tokenId: '...',
+  side: 'BUY',
+  amount: 10,   // USDC 金额
+  orderType: 'FOK',
+});
+```
+
+### 3.3 重要发现
+
+两种订单类型都需要相同的 allowance！
+
+- 如果 Neg Risk Adapter 没有授权，**两种订单都会失败**
+- 错误信息一样: `"not enough balance / allowance"`
+
+## 4. API Key 问题
+
+### 4.1 错误信息
+
+```json
+{"error": "Could not create api key"}
+```
+
+### 4.2 原因和解决
+
+- Polymarket CLOB 客户端在每次初始化时尝试创建新的 API Key
+- 如果账户已有 API Key，可能会失败
+- **但这通常不影响下单**，因为会使用缓存的 API Key
+
+如果确实需要新的 API Key:
+1. 访问 Polymarket 网站
+2. 断开连接，重新连接钱包
+3. 系统会创建新的 API Key
+
+## 5. 部署到下单完整流程
+
+### 5.1 准备工作
+
+1. **获取私钥**
+   ```bash
+   # 确保 .env 中有 PRIVATE_KEY
+   PRIVATE_KEY=0x...
+   ```
+
+2. **获取 USDC.e**
+   - 钱包需要在 Polygon 上有 USDC.e
+   - 不是普通 USDC，是桥接的 USDC.e
+   - 可以从 Ethereum 通过 Polygon Bridge 桥接
+
+3. **设置所有 Allowance**
+   ```bash
+   cd packages/poly-sdk
+   npx tsx scripts/check-all-allowances.ts --approve
+   ```
+
+### 5.2 验证设置
+
+```bash
+npx tsx scripts/check-all-allowances.ts
+
+# 预期输出:
+# CTF Exchange: ✅ Unlimited
+# Neg Risk CTF Exchange: ✅ Unlimited
+# Neg Risk Adapter: ✅ Unlimited
+# Conditional Tokens: ✅ Unlimited
+```
+
+### 5.3 测试下单
+
+```bash
+npx tsx scripts/test-order.ts
+```
+
+## 6. 调试 Checklist
+
+当下单失败时，按以下顺序检查：
+
+- [ ] 1. USDC.e 余额是否足够?
+- [ ] 2. CTF Exchange allowance 是否设置?
+- [ ] 3. Neg Risk CTF Exchange allowance 是否设置?
+- [ ] 4. **Neg Risk Adapter allowance 是否设置?** (最常遗漏)
+- [ ] 5. Conditional Tokens allowance 是否设置?
+- [ ] 6. Token ID 是否正确?
+- [ ] 7. 价格是否在 0.01-0.99 范围内?
+- [ ] 8. 市场是否活跃?
+- [ ] 9. RPC 节点是否正常?
+
+## 7. 已知问题
+
+### 7.1 Gas 价格问题
+
+Polygon 网络有时需要较高的 gas 价格：
+
+```
+Error: transaction gas price below minimum:
+gas tip cap 1500000000, minimum needed 25000000000
+```
+
+**解决方案**:
+```typescript
+const gasPrice = await provider.getGasPrice();
+const adjustedGasPrice = gasPrice.mul(150).div(100); // 1.5x 当前价格
+await contract.approve(spender, amount, { gasPrice: adjustedGasPrice });
+```
+
+### 7.2 RPC 不稳定
+
+某些公共 RPC 节点不稳定：
+
+```
+Error: could not detect network
+```
+
+**推荐 RPC**:
+- `https://polygon-rpc.com` (官方)
+- `https://polygon.llamarpc.com` (LlamaNodes)
+- Alchemy/Infura (需要 API Key，更稳定)
+
+### 7.3 交易不广播
+
+有时交易提交后没有被广播：
+
+```
+Transaction not found
+```
+
+**原因**:
+- RPC 节点问题
+- Gas 价格太低
+- Nonce 冲突
+
+**解决方案**:
+- 使用不同的 RPC
+- 提高 gas 价格
+- 等待一段时间后重试
+
+## 8. 套利脚本 vs Earning Engine
+
+### 8.1 为什么套利脚本能工作?
+
+套利脚本 (`scripts/v2/faze-bo3-arb.ts`) 使用 **FOK 市价单**:
+
+```typescript
+tradingClient.createMarketOrder({
+  tokenId: MARKET_CONFIG.yesTokenId,
+  side: 'BUY',
+  amount: size * buyYesPrice,
+  orderType: 'FOK',
+});
+```
+
+### 8.2 Earning Engine 的方式
+
+Earning Engine 使用 **GTC 限价单**:
+
+```typescript
+client.createOrder({
+  tokenId: action.tokenId,
+  side: action.side,
+  price: action.price,
+  size: action.size,
+  orderType: 'GTC',
+});
+```
+
+### 8.3 关键结论
+
+**两者都需要相同的 allowance**！
+
+如果 Neg Risk Adapter 没有授权:
+- ❌ 套利脚本会失败
+- ❌ Earning Engine 也会失败
+
+## 9. 本次调试发现
+
+日期: 2025-12-21
+
+### 发现的问题
+
+1. **Neg Risk Adapter 缺少 Allowance** ← **根本原因！**
+   ```
+   CTF Exchange: ✅ Unlimited
+   Neg Risk CTF Exchange: ✅ Unlimited
+   Neg Risk Adapter: ❌ None      <-- 这是问题！
+   Conditional Tokens: ✅ Unlimited
+   ```
+
+2. **Gas 价格问题**
+   - ethers.js 默认 1.5 Gwei 太低
+   - Polygon 当前需要 25+ Gwei
+   - 需要在交易中手动设置更高的 gas 价格
+
+3. **RPC 不稳定**
+   - `polygon-rpc.com` 有时不广播交易
+   - 建议使用 `https://polygon-bor-rpc.publicnode.com`
+
+4. **最小订单量**
+   - Polymarket 最小订单量是 **5 份**
+   - 如果订单小于 5 份会报错
+
+### 解决方案
+
+1. 运行 `npx tsx scripts/approve-neg-risk.ts` 授权 Neg Risk Adapter
+2. 或者运行 `npx tsx scripts/check-all-allowances.ts --approve`
+3. 确保所有 4 个合约都有 Unlimited allowance
+
+### 验证结果
+
+授权后测试成功：
+```
+✅ GTC Order SUCCESS!
+   Order ID: 0x1fb3e5aaff045f5efbf4645e949cd9b573e6d063c4f0a365b4d827b239aae7cd
+
+✅ FOK Order SUCCESS!
+   Order ID: 0xea82673eee20bcf96de64c750ef74c540b183b51a596082ddd49aff8e8ae77bb
+```
+
+### 授权交易
+
+- TX Hash: `0xf24a89ee18459a0acb003ad3f773318cc65290f196031f0d8f334c095a89e849`
+- Block: 80602210
+
+## 10. ERC1155 授权 (卖出 YES/NO 代币)
+
+### 10.1 两种授权类型
+
+Polymarket 需要两种不同的授权：
+
+| 类型 | 标准 | 用途 | 合约 |
+|------|------|------|------|
+| **ERC20 Approve** | ERC20 | 授权 USDC.e 给交易所 | USDC.e → 各交易所 |
+| **ERC1155 setApprovalForAll** | ERC1155 | 授权交易所转移 YES/NO 代币 | Conditional Tokens → 交易所 |
+
+### 10.2 为什么需要 ERC1155 授权?
+
+- **买入 (BUY)**: 只需要 USDC.e 的 ERC20 授权
+- **卖出 (SELL)**: 需要 Conditional Tokens 的 ERC1155 授权
+
+如果没有 ERC1155 授权，卖出订单会失败：
+```
+"not enough balance / allowance"
+```
+
+### 10.3 如何设置 ERC1155 授权
+
+```typescript
+const conditionalTokens = new ethers.Contract(
+  '0x4D97DCd97eC945f40cF65F87097ACe5EA0476045',
+  ['function setApprovalForAll(address operator, bool approved)'],
+  wallet
+);
+
+// 授权 CTF Exchange
+await conditionalTokens.setApprovalForAll(CTF_EXCHANGE, true);
+
+// 授权 Neg Risk CTF Exchange
+await conditionalTokens.setApprovalForAll(NEG_RISK_CTF_EXCHANGE, true);
+```
+
+### 10.4 完整授权列表 (2025-12-22 更新)
+
+```
+ERC20 授权 (USDC.e → 合约):
+✅ CTF Exchange              - 普通市场 BUY
+✅ Neg Risk CTF Exchange     - Neg Risk 市场 BUY
+✅ Neg Risk Adapter          - Neg Risk 市场必需
+✅ Conditional Tokens        - Split/Merge 操作
+
+ERC1155 授权 (Conditional Tokens → 合约):
+✅ CTF Exchange              - 普通市场 SELL
+✅ Neg Risk CTF Exchange     - Neg Risk 市场 SELL
+✅ Neg Risk Adapter          - ⚠️ Neg Risk 市场 SELL 必需！(容易遗漏)
+```
+
+### 10.5 授权脚本
+
+```bash
+# 检查并设置所有 ERC20 授权
+npx tsx scripts/check-all-allowances.ts --approve
+
+# 检查并设置所有 ERC1155 授权 (包括 Neg Risk Adapter)
+npx tsx scripts/approve-neg-risk-erc1155.ts
+```
+
+### 10.6 授权验证交易记录
+
+**Neg Risk Adapter ERC1155 授权**:
+- TX: `0x1fcb671978b300266b04e305432b81b76a9c3f499cdfeb4798009c5ce7708f4e`
+- Block: 80609070
+- Date: 2025-12-22
+
+## 11. Earning Engine Live 测试结果
+
+### 11.1 测试时间
+2025-12-21 21:42
+
+### 11.2 测试结果
+
+**成功的订单**:
+```
+✅ BUY YES 10@0.93 [mm] → open
+   Polymarket ID: 0x09bbeb...
+
+✅ SELL NO 5@0.07 [mm] → open
+   Polymarket ID: 0x111a25...
+```
+
+**失败的订单**:
+```
+❌ SELL YES - "not enough balance / allowance"
+   原因: 需要 ERC1155 授权
+
+❌ BUY NO $0.53 - "invalid amount... min size: $1"
+   原因: 订单金额太小
+```
+
+### 11.3 结论
+
+1. **核心问题已解决**: Neg Risk Adapter ERC20 授权修复了主要下单问题
+2. **BUY 订单正常工作**: 使用 USDC.e 买入代币无问题
+3. **SELL 订单需要额外授权**: 需要设置 ERC1155 setApprovalForAll
+4. **最小订单金额**: 市价单最小 $1，限价单最小 5 份
+
+## 12. 相关脚本
+
+| 脚本 | 用途 |
+|------|------|
+| `check-all-allowances.ts` | 检查和设置所有 ERC20 allowance |
+| `approve-neg-risk.ts` | 单独授权 Neg Risk Adapter |
+| `test-order.ts` | 测试下单功能 |
+| `check-allowance.ts` | 检查单个 allowance (旧版) |
+
+---
+
+**最后更新**: 2025-12-21 21:45
+**作者**: Claude (AI Assistant)

package/scripts/verify/test-approve-trading.ts

@@ -0,0 +1,98 @@
+/**
+ * Test Approve Trading
+ *
+ * Approve all required contracts for trading on Polymarket.
+ * This will send real transactions!
+ *
+ * Usage:
+ *   PRIVATE_KEY=0x... npx tsx scripts/test-approve-trading.ts
+ */
+
+import { ethers } from 'ethers';
+import dotenv from 'dotenv';
+import { AuthorizationService } from '../src/index.js';
+
+dotenv.config();
+
+const PRIVATE_KEY = process.env.POLY_PRIVATE_KEY || process.env.PRIVATE_KEY;
+
+if (!PRIVATE_KEY) {
+  console.error('❌ Error: No private key found.');
+  process.exit(1);
+}
+
+const POLYGON_RPC = 'https://polygon-rpc.com';
+
+async function main() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║           APPROVE TRADING TEST                             ║');
+  console.log('╚════════════════════════════════════════════════════════════╝\n');
+
+  const provider = new ethers.providers.JsonRpcProvider(POLYGON_RPC);
+  const signer = new ethers.Wallet(PRIVATE_KEY, provider);
+
+  console.log(`Wallet: ${signer.address}`);
+
+  // Check current balance for gas
+  const balance = await provider.getBalance(signer.address);
+  const maticBalance = ethers.utils.formatEther(balance);
+  console.log(`MATIC Balance: ${maticBalance}\n`);
+
+  if (parseFloat(maticBalance) < 0.1) {
+    console.error('❌ Insufficient MATIC for gas. Need at least 0.1 MATIC');
+    process.exit(1);
+  }
+
+  const authService = new AuthorizationService(signer);
+
+  // Check current state
+  console.log('Checking current allowances...');
+  const before = await authService.checkAllowances();
+  console.log(`Trading Ready: ${before.tradingReady ? '✅' : '❌'}\n`);
+
+  if (before.tradingReady) {
+    console.log('✅ Already ready for trading. No approvals needed.');
+    return;
+  }
+
+  // Approve all
+  console.log('Approving all contracts...\n');
+
+  try {
+    const result = await authService.approveAll();
+
+    console.log('Results:');
+    console.log(`  Wallet: ${result.wallet}`);
+    console.log(`  All Approved: ${result.allApproved ? '✅' : '❌'}`);
+
+    console.log('\n  ERC20 Approvals:');
+    for (const approval of result.erc20Approvals) {
+      const status = approval.success ? '✅' : '❌';
+      console.log(`    ${status} ${approval.contract}`);
+      if (approval.txHash) {
+        console.log(`       TX: https://polygonscan.com/tx/${approval.txHash}`);
+      }
+      if (approval.error) {
+        console.log(`       Error: ${approval.error}`);
+      }
+    }
+
+    console.log('\n  ERC1155 Approvals:');
+    for (const approval of result.erc1155Approvals) {
+      const status = approval.success ? '✅' : '❌';
+      console.log(`    ${status} ${approval.contract}`);
+      if (approval.txHash) {
+        console.log(`       TX: https://polygonscan.com/tx/${approval.txHash}`);
+      }
+      if (approval.error) {
+        console.log(`       Error: ${approval.error}`);
+      }
+    }
+
+    console.log(`\n${result.summary}`);
+  } catch (err) {
+    console.error(`\n❌ Error: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+main().catch(console.error);

package/scripts/verify/test-provider-fix.ts

@@ -0,0 +1,43 @@
+/**
+ * Verify provider fix for SwapService
+ * This script tests that the provider initialization works correctly
+ */
+
+import { ethers } from 'ethers';
+
+// Test that signer without provider works after fix
+async function testProviderFix() {
+  console.log('Testing provider fix...\n');
+
+  // Simulate a signer without provider (like what SDK returns)
+  const privateKey = process.env.POLY_PRIVATE_KEY;
+  if (!privateKey) {
+    console.error('POLY_PRIVATE_KEY not set');
+    process.exit(1);
+  }
+
+  // Create signer WITHOUT provider (simulates SDK issue)
+  const signerNoProvider = new ethers.Wallet(privateKey);
+  console.log('1. Created signer without provider:');
+  console.log('   - Address:', signerNoProvider.address);
+  console.log('   - Has provider:', !!signerNoProvider.provider);
+
+  // Apply the fix: connect to provider if missing
+  const provider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com');
+  const signer = signerNoProvider.provider ? signerNoProvider : signerNoProvider.connect(provider);
+  
+  console.log('\n2. After fix:');
+  console.log('   - Has provider:', !!signer.provider);
+
+  // Test that provider works
+  try {
+    const balance = await signer.provider!.getBalance(signer.address);
+    console.log('   - MATIC balance:', ethers.utils.formatEther(balance));
+    console.log('\n✅ Provider fix working correctly!');
+  } catch (err) {
+    console.error('\n❌ Provider still not working:', err);
+    process.exit(1);
+  }
+}
+
+testProviderFix().catch(console.error);

package/scripts/verify/test-search-mcp.ts

@@ -0,0 +1,113 @@
+/**
+ * Test Search Markets MCP Tool
+ *
+ * Verify the improved search functionality.
+ */
+
+import { PolymarketSDK } from '../src/index.js';
+import { createMcpHandler } from '../src/mcp/index.js';
+
+async function main() {
+  console.log('╔════════════════════════════════════════════════════════════╗');
+  console.log('║           TEST: search_markets MCP TOOL                    ║');
+  console.log('╚════════════════════════════════════════════════════════════╝\n');
+
+  const sdk = new PolymarketSDK();
+  const handler = createMcpHandler(sdk);
+
+  // Test 1: Search for "bitcoin"
+  console.log('--- Test 1: Search for "bitcoin" ---');
+  try {
+    const result = await handler('search_markets', {
+      query: 'bitcoin',
+      limit: 5,
+    });
+
+    console.log('Results:');
+    const data = result as { markets: Array<{ question: string; volume24h: number }>; total: number };
+    data.markets.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.question}`);
+      console.log(`     24h Volume: $${m.volume24h?.toLocaleString() || 'N/A'}`);
+    });
+    console.log(`\nTotal matches: ${data.total}`);
+  } catch (err) {
+    console.log(`Error: ${err}`);
+  }
+
+  // Test 2: Search for "trump"
+  console.log('\n--- Test 2: Search for "trump" ---');
+  try {
+    const result = await handler('search_markets', {
+      query: 'trump',
+      limit: 5,
+    });
+
+    const data = result as { markets: Array<{ question: string; volume24h: number }>; total: number };
+    data.markets.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.question}`);
+      console.log(`     24h Volume: $${m.volume24h?.toLocaleString() || 'N/A'}`);
+    });
+    console.log(`\nTotal matches: ${data.total}`);
+  } catch (err) {
+    console.log(`Error: ${err}`);
+  }
+
+  // Test 3: Search with category filter
+  console.log('\n--- Test 3: Search "price" with Crypto category ---');
+  try {
+    const result = await handler('search_markets', {
+      query: 'price',
+      category: 'Crypto',
+      limit: 5,
+    });
+
+    const data = result as { markets: Array<{ question: string; volume24h: number }>; total: number };
+    data.markets.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.question}`);
+    });
+    console.log(`\nTotal matches: ${data.total}`);
+  } catch (err) {
+    console.log(`Error: ${err}`);
+  }
+
+  // Test 4: Multi-word search
+  console.log('\n--- Test 4: Multi-word search "fed interest rate" ---');
+  try {
+    const result = await handler('search_markets', {
+      query: 'fed interest rate',
+      limit: 5,
+    });
+
+    const data = result as { markets: Array<{ question: string; volume24h: number }>; total: number };
+    data.markets.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.question}`);
+      console.log(`     24h Volume: $${m.volume24h?.toLocaleString() || 'N/A'}`);
+    });
+    console.log(`\nTotal matches: ${data.total}`);
+  } catch (err) {
+    console.log(`Error: ${err}`);
+  }
+
+  // Test 5: Trending markets
+  console.log('\n--- Test 5: Trending markets (for comparison) ---');
+  try {
+    const result = await handler('get_trending_markets', {
+      limit: 5,
+      sortBy: 'volume',
+    });
+
+    const data = result as { markets: Array<{ question: string; volume24h: number }> };
+    data.markets.forEach((m, i) => {
+      console.log(`  ${i + 1}. ${m.question}`);
+      console.log(`     24h Volume: $${m.volume24h?.toLocaleString() || 'N/A'}`);
+    });
+  } catch (err) {
+    console.log(`Error: ${err}`);
+  }
+
+  console.log('\n' + '═'.repeat(60));
+  console.log('TEST COMPLETE');
+  console.log('═'.repeat(60));
+}
+
+main().catch(console.error);