guzus/dr-manhattan

Dr. Manhattan - 预测市场交易

Dr. Manhattan 是一个统一的预测市场 API，类似于 CCXT 对加密货币交易所的封装方式。它通过单一接口支持 Polymarket、Kalshi、Opinion、Limitless 和 Predict.fun。

设置

使用 uv 安装依赖：

uv venv && uv pip install -e .

对于 MCP 服务器（Claude 集成）：

uv sync --extra mcp

支持的交易所

交易所	链/类型	认证方式
Polymarket	Polygon	私钥 + funder 地址
Kalshi	受监管的 CEX	API 密钥 + RSA 私钥
Opinion	BNB Chain	API 密钥 + 私钥 + 多签地址
Limitless	Base	私钥
Predict.fun	BNB Chain	API 密钥 + 私钥（EOA 或智能钱包）

以 Python 库方式使用

只读模式（无需认证）

import dr_manhattan

polymarket = dr_manhattan.Polymarket({'timeout': 30})
markets = polymarket.fetch_markets()
for market in markets:
    print(f"{market.question}: {market.prices}")

带认证

import dr_manhattan

polymarket = dr_manhattan.Polymarket({
    'private_key': '0x...',
    'funder': '0x...',
})

order = polymarket.create_order(
    market_id="market_123",
    outcome="Yes",
    side=dr_manhattan.OrderSide.BUY,
    price=0.65,
    size=100,
    params={'token_id': 'token_id'}
)

交易所工厂

from dr_manhattan import create_exchange, list_exchanges

print(list_exchanges())  # ['polymarket', 'opinion', 'limitless', 'predictfun', 'kalshi']
exchange = create_exchange('polymarket', {'timeout': 30})

通过 MCP 服务器使用

Dr. Manhattan 将所有交易功能以 MCP 工具的形式暴露。在 Claude Code 中配置（~/.claude/settings.json 或 .mcp.json）：

{
  "mcpServers": {
    "dr-manhattan": {
      "command": "/path/to/dr-manhattan/.venv/bin/python",
      "args": ["-m", "dr_manhattan.mcp.server"],
      "cwd": "/path/to/dr-manhattan"
    }
  }
}

MCP 工具参考

交易所工具：

• list_exchanges - 列出所有可用的预测市场交易所。
• get_exchange_info(exchange) - 获取某个交易所的元数据和能力。
• validate_credentials(exchange) - 在不进行交易的情况下检查凭证是否有效。

市场发现：

• search_markets(exchange, query) - 通过关键词搜索市场。这是按主题查找市场最快的方式。
• fetch_markets(exchange, limit?, offset?) - 分页获取所有市场。
• fetch_market(exchange, market_id) - 根据 ID 获取特定市场。
• fetch_markets_by_slug(exchange, slug) - 根据 slug 或 URL 获取市场（Polymarket、Limitless）。
• find_tradeable_market(exchange, binary?, limit?, min_liquidity?) - 找适合交易的市场。
• find_crypto_hourly_market(exchange, token_symbol?) - 查找加密货币每小时价格市场（Polymarket）。
• fetch_token_ids(exchange, market_id) - 获取某个市场的代币 ID。
• parse_market_identifier(identifier) - 从 Polymarket URL 提取 slug。
• get_tag_by_slug(slug) - 获取 Polymarket 标签信息。

订单簿：

• get_orderbook(exchange, token_id) - 获取完整订单簿（买单和卖单）。
• get_best_bid_ask(exchange, token_id) - 获取最优买价和卖价。

交易：

• create_order(exchange, market_id, outcome, side, price, size) - 下买单或卖单。价格范围为 0-1（概率）。side 为 "buy" 或 "sell"。
• cancel_order(exchange, order_id, market_id?) - 取消特定订单。
• cancel_all_orders(exchange, market_id?) - 取消所有未成交订单。
• fetch_order(exchange, order_id, market_id?) - 获取订单详情和成交状态。
• fetch_open_orders(exchange, market_id?) - 列出所有未成交订单。

账户：

• fetch_balance(exchange) - 获取账户余额（USDC）。
• fetch_positions(exchange, market_id?) - 获取当前持仓及盈亏。
• fetch_positions_for_market(exchange, market_id) - 获取特定市场的持仓。
• calculate_nav(exchange, market_id?) - 计算净资产价值（现金 + 持仓）。

策略管理：

• create_strategy_session(strategy_type, exchange, market_id, ...) - 在后台启动一个做市策略。
• get_strategy_status(session_id) - 获取策略实时状态（NAV、持仓、Delta）。
• get_strategy_metrics(session_id) - 获取性能指标（运行时间、成交次数）。
• pause_strategy(session_id) - 暂停正在运行的策略。
• resume_strategy(session_id) - 恢复已暂停的策略。
• stop_strategy(session_id, cleanup?) - 停止策略并可选取消订单。
• list_strategy_sessions - 列出所有活跃的策略会话。

常见工作流程

查找并分析市场

1. 使用 search_markets 配合关键词找到相关市场。
2. 从结果中选取一个市场，记下它的 id 和 metadata.clobTokenIds。
3. 使用 get_orderbook 并传入 token ID 查看当前买单和卖单。
4. 使用 get_best_bid_ask 快速查看价差。

下单交易

1. 使用 search_markets 或 fetch_markets_by_slug 找到市场。
2. 查看 fetch_balance 确认可用资金。
3. 使用 get_orderbook 获取订单簿查看当前价格。
4. 使用 create_order 并传入市场 ID、结果（"Yes" 或 "No"）、方向（"buy" 或 "sell"）、价格（0-1）和数量。
5. 使用 fetch_order 或 fetch_open_orders 进行监控。

运行做市策略

1. 使用 search_markets 或 find_tradeable_market 找到市场。
2. 使用 create_strategy_session(strategy_type="market_making", exchange, market_id) 启动。
3. 使用 get_strategy_status 和 get_strategy_metrics 进行监控。
4. 使用 pause_strategy、resume_strategy 或 stop_strategy 进行控制。

查看投资组合

1. 使用 fetch_balance 查看现金。
2. 使用 fetch_positions 查看所有持仓及未实现盈亏。
3. 使用 calculate_nav 计算投资组合总价值（现金 + 持仓）。

关键概念

• 价格是概率，范围在 0 到 1（不含）之间。价格为 0.65 意味着市场隐含 65% 的概率。
• 结果通常为 "Yes" 和 "No"（二元市场）。它们的价格之和约等于 1。
• Token IDs 是每个市场结果对应的交易所特定标识符，用于查询订单簿。
• Slugs 是人类可读的 URL 标识符（例如 "trump-2024"），Polymarket 和 Limitless 使用。
• 支持的订单类型：GTC（长期有效）、FOK（全部成交或取消）、IOC（立即成交或取消）。

运行示例

uv run python examples/list_all_markets.py polymarket
uv run python examples/spread_strategy.py --exchange polymarket --slug fed-decision
uv run python examples/spike_strategy.py -e opinion -m 813 --spike-threshold 0.02

数据模型

Market 字段：id、question、outcomes、prices、volume、liquidity、close_time、tick_size、description、metadata（包含 slug、clobTokenIds）。

Order 字段：id、market_id、outcome、side（BUY/SELL）、price、size、filled、status（PENDING/OPEN/FILLED/CANCELLED）、time_in_force。

Position 字段：market_id、outcome、size、average_price、current_price。属性：cost_basis、current_value、unrealized_pnl。

Orderbook 字段：bids（价格、数量降序）、asks（价格、数量升序）。属性：best_bid、best_ask、mid_price、spread。