MarketMaster
Dados somente leitura de mercados preditivos da Kalshi e Polymarket: vantagens de valor esperado, arbitragem entre plataformas, instantâneos de mercado e negociações de grandes investidores.
Documentação
Introdução
A API do MarketMaster oferece acesso programático ao nosso mecanismo de previsão de mercado multiplataforma: edges (mercados com preço incorreto classificados pelo tamanho da vantagem), markets (instantâneos normalizados entre plataformas), consulta de um único market, spreads de arbitragem entre plataformas, o feed de negociações whale e um stream WebSocket em tempo real. Cada endpoint REST é um simples GET que retorna JSON.
A API é somente leitura. Ela nunca realiza negociações, move fundos ou expõe dados de qualquer usuário individual — apenas dados públicos de mercado.
REST · JSON WebSocket streaming Autenticação por chave de API CORS habilitado Servidor MCP v1
Início rápido
1. Gere uma chave no seu dashboard (cartão Developer API). Copie-a — ela é exibida apenas uma vez.
2. Envie-a no cabeçalho x-api-key.
3. Chame um endpoint.
curl
curl "https://api.marketmaster.live/v1/edges?limit=5" \
-H "x-api-key: mmk_live_your_key_here" \
-H "User-Agent: my-app/1.0"
SDKs e MCP
Clientes oficiais com autenticação, novas tentativas, tratamento de limite de taxa e um User-Agent adequado integrado. Ou pule o código completamente e conecte os dados ao Claude ou Cursor via MCP.
JavaScript / TypeScript
npm install @marketmaster/sdk
import { MarketMaster } from "@marketmaster/sdk";
const mm = new MarketMaster({ apiKey: process.env.MM_API_KEY });
const { edges } = await mm.edges({ platform: "kalshi", min_edge: 5 });
Python
pip install marketmaster
from marketmaster import MarketMaster
mm = MarketMaster(api_key="mmk_live_your_key")
edges = mm.edges(platform="kalshi", min_edge=5)["edges"]
MCP — conexão em um clique
Conecte o MarketMaster ao seu assistente de IA em um único passo. O servidor hospedado faz login com sua conta MarketMaster, então não há chave para copiar.
Claude: o botão copia a URL do servidor e abre as configurações de conector do Claude. Escolha Adicionar conector personalizado e cole.
MCP — Claude Desktop / Cursor
Seis ferramentas somente leitura (mm_edges, mm_markets, mm_market, mm_arbitrage, mm_whales, mm_status) via npx — sem instalação. Adicione ao claude_desktop_config.json (ou ~/.cursor/mcp.json):
{
"mcpServers": {
"marketmaster": {
"command": "npx",
"args": ["-y", "@marketmaster/mcp"],
"env": { "MARKETMASTER_API_KEY": "mmk_live_your_key" }
}
}
}
MCP — endpoint hospedado (nada para instalar)
As mesmas seis ferramentas também são servidas a partir de um endpoint MCP Streamable HTTP hospedado, para clientes que se conectam a uma URL em vez de iniciar um processo local. Clientes que suportam OAuth (Claude, Cursor, VS Code) fazem login com sua conta MarketMaster; qualquer outro pode enviar a mesma chave de API como um token bearer.
https://api.marketmaster.live/mcp
{
"mcpServers": {
"marketmaster": {
"url": "https://api.marketmaster.live/mcp",
"headers": { "Authorization": "Bearer mmk_live_your_key" }
}
}
}
Use npx acima se quiser o servidor rodando localmente; use o endpoint hospedado se seu cliente aceitar apenas uma URL, ou se preferir não executar um processo. Ambos expõem ferramentas idênticas e contam contra a mesma cota.
O MarketMaster está listado no Registro MCP oficial como live.marketmaster/mcp e no Smithery. Uma descrição legível por máquina do servidor é publicada em https://api.marketmaster.live/.well-known/mcp/server-card.json.
Cada ferramenta MCP é anotada como readOnlyHint: true. Um agente conectado ao MarketMaster pode ler dados de mercado e nada mais — ele não pode realizar uma negociação, mover fundos ou acessar a conta de outro usuário.
Autenticação
Autentique cada requisição com sua chave de API no cabeçalho x-api-key. As chaves têm o formato mmk_live_… e são gerenciadas a partir do seu dashboard. Uma chave é exibida uma única vez na criação; armazene-a em uma variável de ambiente, nunca a envie para o controle de versão e rotacione-a pelo dashboard se ela for exposta.
Trate sua chave como uma senha. Requisições sem uma chave válida retornam 401.
Sempre envie um cabeçalho User-Agent descritivo. Requisições de agentes de biblioteca padrão (ex.: python-urllib) podem ser rejeitadas pela nossa proteção de bot de borda. Nossos SDKs oficiais definem um automaticamente.
Convenções
URL base
https://api.marketmaster.live
| Formato | Todas as requisições e respostas são JSON. |
|---|---|
| Preços | Probabilidades em 0,0–1,0 (ex.: 0.43 = 43¢ / 43% de chance implícita). |
| Carimbos de data/hora | ISO 8601, UTC (ex.: 2026-06-20T21:25:12Z). |
| Plataformas | kalshi, polymarket. |
| CORS | Habilitado para todas as origens — chame diretamente de um aplicativo de navegador. |
| Paginação | Endpoints de lista aceitam limit e offset; a resposta inclui has_more. |
| Cache | Endpoints de dados enviam Cache-Control: public, max-age=30. |
Preços
Todos os endpoints — incluindo arbitragem, edges, feed de whales e streaming WebSocket — estão disponíveis em todos os planos.
Grátis
$0/mês
60 req/min · 1.000 req/mês
- Todos os 6 endpoints REST
- Edges, arbitragem e feed de whales
- WebSocket: 1 conexão
- 1 chave de API
Mais popular
API Starter
$9,99/mês
120 req/min · 50.000 req/mês
- Tudo do plano Grátis
- 2× limite de taxa
- WebSocket: 3 conexões
- Nenhum aplicativo de consumo necessário
API Pro
$29,99/mês
300 req/min · 1.000.000 req/mês
- Tudo do plano Starter
- 5× limite de taxa
- WebSocket: 10 conexões
- Para pipelines de alta frequência
MarketMaster Pro (assinatura de consumo de $12,99/mês) também inclui acesso à API com 240 req/min · 200 mil req/mês, WebSocket: 5 conexões, além de scanner, alertas e sobreposição.
Por que MarketMaster em vez de alternativas?
| Recurso | MarketMaster | Concorrentes |
|---|---|---|
| Feed de arbitragem | ✅ Todos os planos | Somente Enterprise |
| Classificações de EV / edge | ✅ Todos os planos | Somente Enterprise |
| Feed de negociações whale | ✅ Todos os planos | Somente Enterprise |
| Streaming WebSocket | ✅ Todos os planos | Somente Enterprise |
| Preço de entrada | Grátis para sempre | $49+/mês para começar |
| Kalshi + Polymarket + mais | ✅ Unificado | Plataforma única |
Limites de taxa
Os limites são aplicados por conta em duas janelas: uma taxa por minuto e uma cota mensal. Os limites sobrevivem à rotação de chaves.
| Plano | Taxa | Cota mensal | Conexões WS |
|---|---|---|---|
free | 60 req / min | 1.000 | 1 |
api_starter | 120 req / min | 50.000 | 3 |
pro (consumidor) | 240 req / min | 200.000 | 5 |
api_pro | 300 req / min | 1.000.000 | 10 |
Cabeçalhos de resposta de limite de taxa
X-RateLimit-Limit-Minute | Seu teto por minuto. |
|---|---|
X-RateLimit-Remaining-Minute | Requisições restantes neste minuto. |
X-RateLimit-Limit-Month | Sua cota mensal. |
X-RateLimit-Remaining-Month | Requisições restantes neste mês. |
Exceder a taxa por minuto retorna 429 rate_limited; esgotar a cota mensal retorna 429 quota_exceeded. Ambos incluem um cabeçalho Retry-After em segundos.
Edges
GET/v1/edges
Os mercados com preço mais incorreto agora — o valor justo do nosso modelo vs. o preço ao vivo, classificados pelo tamanho da vantagem. Retorna uma linha por mercado, deduplicada para a leitura mais recente.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
platform | string | Filtrar por plataforma: kalshi, polymarket. |
category | string | Filtrar por categoria, ex.: politics, sports, crypto. |
limit | inteiro | Máximo de linhas. Padrão 50, máximo 200. |
offset | inteiro | Linhas para pular. Padrão 0. |
min_edge | número | Vantagem mínima em pontos percentuais. |
Resposta: edges[]
| Campo | Tipo | Descrição |
|---|---|---|
platform | string | Plataforma. |
market_id | string | Identificador nativo do mercado na plataforma. |
market_title | string | Pergunta do mercado. |
market_category | string | Categoria (ex.: politics). |
outcome | string | YES ou NO. |
price | número | Preço de mercado ao vivo para o lado nomeado por outcome (0–1). Em uma linha NO, este é o preço NO, não o preço YES. |
fair_value | número | Probabilidade justa estimada pelo modelo para o lado nomeado por outcome (0–1). Cada campo de preço em uma linha — price, fair_value, ask — é cotado nesse mesmo lado, então fair_value − price é sempre a vantagem a seu favor. |
edge_pct | número | Vantagem em pontos percentuais. Maior = mais incorretamente precificado. |
confidence | número | Confiança do modelo (0–1). |
match_group_id | inteiro | ID do grupo de correspondência entre plataformas. Mercados que compartilham este ID são o mesmo evento do mundo real em plataformas diferentes. |
expires_at | string | Quando o mercado fecha (ISO 8601). |
computed_at | string | Quando esta vantagem foi calculada (ISO 8601). |
Exemplo
curl
curl "https://api.marketmaster.live/v1/edges?platform=kalshi&limit=2" \
-H "x-api-key: mmk_live_your_key_here"
JavaScript
const res = await fetch(
"https://api.marketmaster.live/v1/edges?platform=kalshi&limit=2",
{ headers: { "x-api-key": process.env.MM_API_KEY } }
);
const { edges } = await res.json();
Python
import requests
r = requests.get(
"https://api.marketmaster.live/v1/edges",
params={"platform": "kalshi", "limit": 2},
headers={"x-api-key": MM_API_KEY},
)
edges = r.json()["edges"]
Resposta
{
"count": 2,
"edges": [{
"platform": "kalshi", "market_id": "PRES-2028-DEM",
"market_title": "Will a Democrat win the 2028 election?",
"outcome": "YES", "price": 0.43, "fair_value": 0.51,
"edge_pct": 8.0, "confidence": 0.62,
"expires_at": "2028-11-07T05:00:00Z", "computed_at": "2026-06-20T21:25:12Z"
}],
"generated_at": "2026-06-20T21:25:34Z"
}
Markets
GET/v1/markets
O instantâneo mais recente de todos os mercados rastreados em ambas as plataformas — título, categoria, preço YES/NO, volume em 24h e horário de fechamento. Ordenado por volume em 24h (mais ativos primeiro).
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
source | string | Filtrar por plataforma (alias: platform). |
category | string | Filtrar por categoria. |
limit | inteiro | Máximo de linhas. Padrão 100, máximo 500. |
offset | inteiro | Linhas para pular. Padrão 0. |
Resposta: markets[]
| Campo | Tipo | Descrição |
|---|---|---|
source | string | Plataforma. |
source_market_id | string | ID nativo do mercado na plataforma. |
title | string | Pergunta do mercado. |
category | string | Categoria. |
yes_price | número | Preço YES atual (0–1). |
no_price | número | Preço NO atual (0–1). |
volume_24h_usd | número | null | Volume negociado em 24h em USD. |
close_time | string | null | Horário de fechamento do mercado (ISO 8601). |
last_trade_at | string | null | Carimbo de data/hora da última negociação (ISO 8601). |
fetched_at | string | Quando capturamos o instantâneo deste mercado pela última vez (ISO 8601). |
curl
curl "https://api.marketmaster.live/v1/markets?category=politics&limit=50" \
-H "x-api-key: mmk_live_your_key_here"
Market
GET/v1/market
O instantâneo mais recente de um único mercado, além de quaisquer vantagens ao vivo calculadas para ele. Identifique por source + id.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
source | string · obrigatório | Plataforma: kalshi, polymarket. |
id | string · obrigatório | ID nativo do mercado na plataforma. |
Retorna market (mesma forma de markets[]) e edges[] (mesma forma de edges[], mais recentes primeiro). ID desconhecido retorna 404 not_found.
curl
curl "https://api.marketmaster.live/v1/market?source=kalshi&id=PRES-2028-DEM" \
-H "x-api-key: mmk_live_your_key_here"
Arbitragem
GET/v1/arbitrage
Spreads de preço entre plataformas para o mesmo resultado em mercados correspondentes, classificados do mais amplo para o mais estreito.
Os spreads são indicativos e brutos de taxas, slippage e profundidade de oferta/demanda — não é arbitragem garantida. Sempre confirme os preços executáveis na plataforma.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
min_spread | número | Spread mínimo em pontos percentuais. |
limit | inteiro | Máximo de linhas. Padrão 50, máximo 200. |
offset | inteiro | Linhas para pular. Padrão 0. |
Resposta: opportunities[]
| Campo | Tipo | Descrição |
|---|---|---|
match_group_id | inteiro | Grupo de correspondência entre plataformas. |
title | string | Pergunta do mercado. |
outcome | string | Resultado sendo comparado (YES / NO). |
spread_pct | número | Preço mais caro menos o mais barato, em pontos percentuais. |
buy_yes | objeto | Plataforma mais barata: { platform, market_id, price }. |
sell_yes | objeto | Plataforma mais cara: { platform, market_id, price }. |
computed_at | string | Quando esses preços foram calculados (ISO 8601). |
curl
curl "https://api.marketmaster.live/v1/arbitrage?min_spread=2&limit=10" \
-H "x-api-key: mmk_live_your_key_here"
Whales
GET/v1/whales
Negociações recentes de grande porte com dinheiro real entre plataformas, das mais recentes para as mais antigas.
Parâmetros de consulta
| Parâmetro | Tipo | Descrição |
|---|---|---|
source | string | Filtrar por plataforma. |
min | inteiro | Tamanho mínimo da negociação em USD. |
limit | inteiro | Máximo de linhas. Padrão 50, máximo 200. |
offset | inteiro | Linhas para pular. Padrão 0. |
Resposta: trades[]
| Campo | Tipo | Descrição |
|---|---|---|
source | string | Local de negociação. |
source_market_id | string | ID de mercado nativo do local de negociação. |
trader_name | string | null | Identificador público do trader, quando disponível. |
side | string | Lado da negociação (buy / sell). |
outcome | string | Resultado negociado. |
size_usd | number | Tamanho nocional em USD. |
price | number | Preço da negociação (0–1). |
title | string | Pergunta do mercado. |
trade_time | string | Quando a negociação foi registrada (ISO 8601). |
tx_hash | string | null | Hash da transação on-chain para locais de negociação on-chain. |
curl
curl "https://api.marketmaster.live/v1/whales?min=10000&limit=20" \
-H "x-api-key: mmk_live_your_key_here"
Status
Retorna o nível da sua chave, limites e uso atual. Use para monitorar a cota restante.
{
"ok": true,
"tier": "free",
"limits": { "minute": 60, "month": 1000 },
"usage": { "minute": 3, "month": 412 }
}
Streaming via WebSocket
Conecte-se uma vez e receba eventos enviados no momento em que estiverem prontos — sem polling. O stream envia lotes de borda e notificações de negociações de baleias do nosso pipeline de ingestão assim que cada lote é produzido.
WSS /v1/stream Tempo real
URL de conexão
wss://api.marketmaster.live/v1/stream
Autenticação
Sua chave de API deve ser enviada no momento da conexão. Duas opções dependendo do ambiente:
| Ambiente | Como autenticar |
|---|---|
| Node.js / Python / servidor | Envie x-api-key: mmk_live_... nos cabeçalhos da solicitação de upgrade do WebSocket. |
| Navegador | Acrescente ?api_key=mmk_live_... como parâmetro de consulta — navegadores não podem definir cabeçalhos personalizados em conexões WebSocket. |
Nunca exponha sua chave de API em código público no lado do cliente. Use um token de curta duração ou um relay no servidor para implantações em navegador.
Canais
edges
Enviado a cada ~10 min
Novo lote de borda calculado. Busque /v1/edges ao receber para obter a lista atualizada.
whales
Enviado a cada ~5 min
Novas negociações de baleias ingeridas. Busque /v1/whales ao receber para obter os últimos preenchimentos.
prices/*
Reservado
Streaming de preços por mercado — em breve.
O stream envia uma notificação leve (contagem + timestamp) em vez do payload completo. Puxe o endpoint REST relevante ao receber para obter os dados — isso mantém os payloads do stream pequenos e permite filtrar antes de buscar.
Mensagens do cliente → servidor (envie como JSON)
| Ação | Payload | Efeito |
|---|---|---|
subscribe | {"action":"subscribe","channel":"edges"} | Comece a receber eventos para este canal. |
unsubscribe | {"action":"unsubscribe","channel":"edges"} | Pare de receber eventos para este canal. |
ping | {"action":"ping"} | O servidor responde com pong. Use para manter a conexão ativa. |
Mensagens do servidor → cliente (receba como JSON)
| Tipo | Exemplo de payload | Quando |
|---|---|---|
welcome | {"type":"welcome","tier":"free","conn_id":"abc"} | Imediatamente ao conectar. |
subscribed | {"type":"subscribed","channel":"edges"} | Após uma inscrição bem-sucedida. |
event | {"type":"event","channel":"edges","data":{"count":34,"ts":1751000000000}} | Novos dados disponíveis para um canal inscrito. |
pong | {"type":"pong"} | Resposta ao seu ping. |
error | {"type":"error","code":"too_many_connections","message":"..."} | Falha de autenticação, limite de conexões excedido ou mensagem inválida. |
Limites de conexão por nível
| Nível | Máx. de conexões simultâneas | Máx. de inscrições de canais / conexão |
|---|---|---|
free | 1 | 5 |
api_starter | 3 | 20 |
pro (consumidor) | 5 | 50 |
api_pro | 10 | 100 |
Exemplo — navegador
JavaScript (navegador)
// Pass key as query param; browsers can't set WebSocket headers
const ws = new WebSocket(
\`wss://api.marketmaster.live/v1/stream?api_key=${MM_API_KEY}\`
);
ws.onopen = () => {
ws.send(JSON.stringify({ action: "subscribe", channel: "edges" }));
ws.send(JSON.stringify({ action: "subscribe", channel: "whales" }));
};
ws.onmessage = async (e) => {
const msg = JSON.parse(e.data);
if (msg.type === "event" && msg.channel === "edges") {
// New edge batch — pull fresh data
const { edges } = await fetch("/v1/edges?limit=20", {
headers: { "x-api-key": MM_API_KEY }
}).then(r => r.json());
renderEdges(edges);
}
};
// Keep-alive ping every 30s
setInterval(() => ws.send(JSON.stringify({ action: "ping" })), 30_000);
Exemplo — Node.js
JavaScript (Node.js / biblioteca ws)
import WebSocket from "ws";
const ws = new WebSocket("wss://api.marketmaster.live/v1/stream", {
headers: { "x-api-key": process.env.MM_API_KEY },
});
ws.on("open", () => {
ws.send(JSON.stringify({ action: "subscribe", channel: "edges" }));
ws.send(JSON.stringify({ action: "subscribe", channel: "whales" }));
});
ws.on("message", (raw) => {
const msg = JSON.parse(raw);
console.log(msg.type, msg.channel ?? "", msg.data ?? "");
});
Exemplo — Python
Python (biblioteca websockets)
import asyncio, json, websockets
async def stream():
uri = "wss://api.marketmaster.live/v1/stream"
async with websockets.connect(uri, extra_headers={"x-api-key": MM_API_KEY}) as ws:
await ws.send(json.dumps({"action": "subscribe", "channel": "edges"}))
await ws.send(json.dumps({"action": "subscribe", "channel": "whales"}))
async for raw in ws:
msg = json.loads(raw)
print(msg["type"], msg.get("channel"), msg.get("data"))
asyncio.run(stream())
Erros
Erros retornam o status HTTP apropriado com um envelope JSON:
{ "error": { "code": "rate_limited", "message": "Per-minute rate limit exceeded." } }
| Status | Código | Significado |
|---|---|---|
401 | missing_api_key | Nenhum cabeçalho x-api-key enviado. |
401 | invalid_api_key | Chave malformada, desconhecida ou revogada. |
400 | invalid_parameter | Parâmetro de consulta inválido ou parâmetro obrigatório ausente. |
404 | not_found | Nenhum recurso correspondente (ex.: ID de mercado desconhecido). |
426 | websocket_required | /v1/stream deve estar conectado via WebSocket. |
429 | rate_limited | Taxa por minuto excedida — verifique o cabeçalho Retry-After. |
429 | quota_exceeded | Cota mensal esgotada — reinicia no início do mês. |
500 | auth_error | Problema temporário ao validar a chave — tente novamente. |
502 | upstream_error | Problema transitório de carregamento de dados — tente novamente. |
503 | streaming_unavailable | Streaming via WebSocket temporariamente indisponível. |
Frames de erro do WebSocket usam o mesmo formato code / message, entregues como uma mensagem JSON antes de o servidor fechar a conexão.
Versionamento e mudanças
A API é versionada no caminho (/v1/). Podemos adicionar novos campos às respostas e novos canais ao stream a qualquer momento — escreva clientes que ignorem campos e tipos de mensagem desconhecidos. Mudanças que quebram compatibilidade seriam lançadas sob um novo caminho de versão. Esta é uma versão inicial; endpoints, limites e canais de stream ainda podem evoluir.
Aviso legal
Valores de borda e valor justo são estimativas de modelo apenas para fins informativos. Não são conselhos de negociação, nem garantia de lucro. Dados fornecidos como estão, sem garantia. Você é responsável por cumprir os termos e leis aplicáveis de qualquer local de negociação em que operar.