Dr. Manhattan - Negociação em Mercados de Previsão

Dr. Manhattan é uma API unificada para mercados de previsão, similar a como CCXT funciona para exchanges de criptomoedas. Ele suporta Polymarket, Kalshi, Opinion, Limitless e Predict.fun por meio de uma única interface.

Configuração

Instale as dependências com uv:

uv venv && uv pip install -e .

Para o servidor MCP (integração com Claude):

uv sync --extra mcp

Exchanges Suportados

Exchange	Chain/Tipo	Autenticação
Polymarket	Polygon	Chave privada + endereço do financiador
Kalshi	CEX regulamentado	Chave API + chave privada RSA
Opinion	BNB Chain	Chave API + chave privada + endereço multi-sig
Limitless	Base	Chave privada
Predict.fun	BNB Chain	Chave API + chave privada (EOA ou carteira inteligente)

Uso como Biblioteca Python

Somente Leitura (Sem Credenciais)

import dr_manhattan

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

Com Autenticação

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 via Servidor MCP

Dr. Manhattan expõe todas as capacidades de negociação como ferramentas MCP. Configure no Claude Code (~/.claude/settings.json ou .mcp.json):

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

Referência de Ferramentas MCP

Ferramentas de Exchange:

list_exchanges - Lista todos os mercados de previsão disponíveis.
get_exchange_info(exchange) - Obtém metadados e capacidades de uma exchange.
validate_credentials(exchange) - Verifica se as credenciais são válidas sem negociar.

Descoberta de Mercados:

search_markets(exchange, query) - Busca mercados por palavra-chave. Esta é a maneira mais rápida de encontrar mercados sobre um tópico.
fetch_markets(exchange, limit?, offset?) - Obtém todos os mercados com paginação.
fetch_market(exchange, market_id) - Obtém um mercado específico pelo ID.
fetch_markets_by_slug(exchange, slug) - Obtém mercados por slug ou URL (Polymarket, Limitless).
find_tradeable_market(exchange, binary?, limit?, min_liquidity?) - Encontra um mercado adequado para negociação.
find_crypto_hourly_market(exchange, token_symbol?) - Encontra mercados de preço horário de criptomoedas (Polymarket).
fetch_token_ids(exchange, market_id) - Obtém IDs de token para um mercado.
parse_market_identifier(identifier) - Extrai slug de uma URL do Polymarket.
get_tag_by_slug(slug) - Obtém informações de tag do Polymarket.

Order Book:

get_orderbook(exchange, token_id) - Obtém o order book completo (ofertas de compra e venda).
get_best_bid_ask(exchange, token_id) - Obtém os melhores preços de compra e venda.

Negociação:

create_order(exchange, market_id, outcome, side, price, size) - Coloca uma ordem de compra ou venda. Preço é 0-1 (probabilidade). O lado é "buy" ou "sell".
cancel_order(exchange, order_id, market_id?) - Cancela uma ordem específica.
cancel_all_orders(exchange, market_id?) - Cancela todas as ordens abertas.
fetch_order(exchange, order_id, market_id?) - Obtém detalhes da ordem e status de preenchimento.
fetch_open_orders(exchange, market_id?) - Lista todas as ordens abertas.

Conta:

fetch_balance(exchange) - Obtém saldo da conta (USDC).
fetch_positions(exchange, market_id?) - Obtém posições atuais com PnL.
fetch_positions_for_market(exchange, market_id) - Obtém posições para um mercado específico.
calculate_nav(exchange, market_id?) - Calcula o valor patrimonial líquido (saldo + posições).

Gerenciamento de Estratégias:

create_strategy_session(strategy_type, exchange, market_id, ...) - Inicia uma estratégia de market-making em segundo plano.
get_strategy_status(session_id) - Obtém status em tempo real da estratégia (NAV, posições, delta).
get_strategy_metrics(session_id) - Obtém métricas de desempenho (tempo de atividade, preenchimentos).
pause_strategy(session_id) - Pausa uma estratégia em execução.
resume_strategy(session_id) - Retoma uma estratégia pausada.
stop_strategy(session_id, cleanup?) - Para uma estratégia e opcionalmente cancela ordens.
list_strategy_sessions - Lista todas as sessões de estratégia ativas.

Fluxos de Trabalho Comuns

Encontrar e Analisar um Mercado

Use search_markets com uma palavra-chave para encontrar mercados relevantes.
Escolha um mercado nos resultados e anote seu id e metadata.clobTokenIds.
Use get_orderbook com um ID de token para ver as ofertas atuais de compra e venda.
Use get_best_bid_ask para uma verificação rápida do spread.

Realizar uma Negociação

Encontre o mercado usando search_markets ou fetch_markets_by_slug.
Verifique fetch_balance para confirmar fundos disponíveis.
Obtenha o order book com get_orderbook para ver os preços atuais.
Use create_order com o ID do mercado, resultado ("Yes" ou "No"), lado ("buy" ou "sell"), preço (0-1) e tamanho.
Monitore com fetch_order ou fetch_open_orders.

Executar uma Estratégia de Market-Making

Encontre um mercado com search_markets ou find_tradeable_market.
Inicie com create_strategy_session(strategy_type="market_making", exchange, market_id).
Monitore com get_strategy_status e get_strategy_metrics.
Controle com pause_strategy, resume_strategy ou stop_strategy.

Verificar Portfólio

fetch_balance para ver o saldo.
fetch_positions para ver todas as posições abertas com PnL não realizado.
calculate_nav para o valor total do portfólio (saldo + posições).

Conceitos-chave

Preços são probabilidades variando de 0 a 1 (exclusivo). Um preço de 0,65 significa que o mercado implica uma chance de 65%.
Resultados são tipicamente "Sim" e "Não" para mercados binários. Seus preços somam aproximadamente 1.
IDs de token são identificadores específicos de cada exchange para cada resultado de um mercado. Necessários para consultas de order book.
Slugs são identificadores de URL legíveis por humanos (ex.: "trump-2024") usados por Polymarket e Limitless.
Tipos de ordem suportados: GTC (válida até cancelar), FOK (preencher ou cancelar), IOC (imediata ou cancelar).

Executando Exemplos

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 Dados

Market campos: id, question, outcomes, prices, volume, liquidity, close_time, tick_size, description, metadata (contém slug, clobTokenIds).

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

Position campos: market_id, outcome, size, average_price, current_price. Propriedades: cost_basis, current_value, unrealized_pnl.

Orderbook campos: bids (preço, tamanho decrescente), asks (preço, tamanho crescente). Propriedades: best_bid, best_ask, mid_price, spread.

Dr. Manhattan

O que é Dr. Manhattan?

Perguntar na sua IA favorita

Documentação