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	私鑰 + 資金提供者地址
Kalshi	監管交易所	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'}
)

Exchange Factory（交易所工廠）

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 或網址取得市場（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 網址中提取 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 搭配代幣 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。
• 代幣 ID 是每個交易所對市場中各個結果的專用識別碼，查詢訂單簿時需要。
• Slug 是人類可讀的網址識別碼（例如 "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。