Dr. Manhattan - Trading en Mercados de Predicción

¿Qué hace Dr. Manhattan - Trading en Mercados de Predicción?

Dr. Manhattan es una API unificada para mercados de predicción, similar a cómo CCXT funciona para exchanges de criptomonedas. Soporta Polymarket, Kalshi, Opinion, Limitless y Predict.fun a través de una sola interfaz.

Configuración

Instala las dependencias con uv:

uv venv && uv pip install -e .

Para el servidor MCP (integración con Claude):

uv sync --extra mcp

Exchanges Soportados

Exchange	Chain/Tipo	Autenticación
Polymarket	Polygon	Clave privada + dirección del fundador
Kalshi	CEX regulado	Clave API + clave privada RSA
Opinion	BNB Chain	Clave API + clave privada + dirección multi-sig
Limitless	Base	Clave privada
Predict.fun	BNB Chain	Clave API + clave privada (EOA o smart wallet)

Uso como Biblioteca Python

Solo Lectura (Sin Credenciales)

import dr_manhattan

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

Con Autenticación

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'}
)

Fábrica de Exchanges

from dr_manhattan import create_exchange, list_exchanges

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

Uso a través del Servidor MCP

Dr. Manhattan expone todas las capacidades de trading como herramientas MCP. Configúralo en Claude Code (~/.claude/settings.json o .mcp.json):

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

Referencia de Herramientas MCP

Herramientas de Exchange:

• list_exchanges - Lista todos los exchanges de mercados de predicción disponibles.
• get_exchange_info(exchange) - Obtiene metadatos y capacidades de un exchange.
• validate_credentials(exchange) - Verifica si las credenciales son válidas sin hacer trading.

Descubrimiento de Mercados:

• search_markets(exchange, query) - Busca mercados por palabra clave. Es la forma más rápida de encontrar mercados sobre un tema.
• fetch_markets(exchange, limit?, offset?) - Obtiene todos los mercados con paginación.
• fetch_market(exchange, market_id) - Obtiene un mercado específico por su ID.
• fetch_markets_by_slug(exchange, slug) - Obtiene mercados por slug o URL (Polymarket, Limitless).
• find_tradeable_market(exchange, binary?, limit?, min_liquidity?) - Encuentra un mercado adecuado para trading.
• find_crypto_hourly_market(exchange, token_symbol?) - Encuentra mercados cripto de precios por hora (Polymarket).
• fetch_token_ids(exchange, market_id) - Obtiene los token IDs de un mercado.
• parse_market_identifier(identifier) - Extrae el slug de una URL de Polymarket.
• get_tag_by_slug(slug) - Obtiene información de etiqueta de Polymarket.

Libro de Órdenes:

• get_orderbook(exchange, token_id) - Obtiene el libro de órdenes completo (ofertas y demandas).
• get_best_bid_ask(exchange, token_id) - Obtiene el mejor precio de compra y venta.

Trading:

• create_order(exchange, market_id, outcome, side, price, size) - Coloca una orden de compra o venta. El precio es 0-1 (probabilidad). El lado es "buy" o "sell".
• cancel_order(exchange, order_id, market_id?) - Cancela una orden específica.
• cancel_all_orders(exchange, market_id?) - Cancela todas las órdenes abiertas.
• fetch_order(exchange, order_id, market_id?) - Obtiene detalles de la orden y estado de llenado.
• fetch_open_orders(exchange, market_id?) - Lista todas las órdenes abiertas.

Cuenta:

• fetch_balance(exchange) - Obtiene el saldo de la cuenta (USDC).
• fetch_positions(exchange, market_id?) - Obtiene las posiciones actuales con PnL.
• fetch_positions_for_market(exchange, market_id) - Obtiene posiciones de un mercado específico.
• calculate_nav(exchange, market_id?) - Calcula el valor neto del activo (efectivo + posiciones).

Gestión de Estrategias:

• create_strategy_session(strategy_type, exchange, market_id, ...) - Inicia una estrategia de market-making en segundo plano.
• get_strategy_status(session_id) - Obtiene el estado en tiempo real de la estrategia (NAV, posiciones, delta).
• get_strategy_metrics(session_id) - Obtiene métricas de rendimiento (tiempo de actividad, llenados).
• pause_strategy(session_id) - Pausa una estrategia en ejecución.
• resume_strategy(session_id) - Reanuda una estrategia pausada.
• stop_strategy(session_id, cleanup?) - Detiene una estrategia y opcionalmente cancela órdenes.
• list_strategy_sessions - Lista todas las sesiones de estrategia activas.

Flujos de Trabajo Comunes

Encontrar y Analizar un Mercado

1. Usa search_markets con una palabra clave para encontrar mercados relevantes.
2. Elige un mercado de los resultados y anota su id y metadata.clobTokenIds.
3. Usa get_orderbook con un token ID para ver las ofertas y demandas actuales.
4. Usa get_best_bid_ask para una comprobación rápida del spread.

Realizar una Operación

1. Encuentra el mercado usando search_markets o fetch_markets_by_slug.
2. Verifica fetch_balance para confirmar los fondos disponibles.
3. Obtén el libro de órdenes con get_orderbook para ver los precios actuales.
4. Usa create_order con el ID del mercado, resultado ("Yes" o "No"), lado ("buy" o "sell"), precio (0-1) y tamaño.
5. Monitorea con fetch_order o fetch_open_orders.

Ejecutar una Estrategia de Market-Making

1. Encuentra un mercado con search_markets o find_tradeable_market.
2. Inicia con create_strategy_session(strategy_type="market_making", exchange, market_id).
3. Monitorea con get_strategy_status y get_strategy_metrics.
4. Controla con pause_strategy, resume_strategy o stop_strategy.

Consultar el Portafolio

1. fetch_balance para ver el efectivo.
2. fetch_positions para ver todas las posiciones abiertas con PnL no realizado.
3. calculate_nav para el valor total del portafolio (efectivo + posiciones).

Conceptos Clave

• Los precios son probabilidades que van de 0 a 1 (exclusivo). Un precio de 0.65 significa que el mercado implica un 65% de probabilidad.
• Los resultados son típicamente "Yes" y "No" para mercados binarios. Sus precios suman aproximadamente 1.
• Los token IDs son identificadores específicos de cada exchange para cada resultado de un mercado. Son necesarios para consultar el libro de órdenes.
• Los slugs son identificadores legibles para humanos (ej., "trump-2024") usados por Polymarket y Limitless.
• Tipos de órdenes soportadas: GTC (Good-Til-Cancel), FOK (Fill-Or-Kill), IOC (Immediate-Or-Cancel).

Ejemplos de Ejecución

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

Modelos de Datos

Campos de Mercado: id, question, outcomes, prices, volume, liquidity, close_time, tick_size, description, metadata (contiene slug, clobTokenIds).

Campos de Orden: id, market_id, outcome, side (BUY/SELL), price, size, filled, status (PENDING/OPEN/FILLED/CANCELLED), time_in_force.

Campos de Posición: market_id, outcome, size, average_price, current_price. Propiedades: cost_basis, current_value, unrealized_pnl.

Campos del Libro de Órdenes: bids (precio, tamaño descendente), asks (precio, tamaño ascendente). Propiedades: best_bid, best_ask, mid_price, spread.