Mercados de previsão e surebets na Genesis API: endpoints, filtros e campos
Em resumo
- Seis endpoints: arbitragem de previsão e status das plataformas a partir do plano Start; análise, smart money, grandes operações e ranking de traders no Pro e no Max.
- Os pacotes de arbitragem vêm calculados pelos livros de ofertas, com taxas: tamanho da operação, lucro em $ e %, APR, dias até a liquidação e códigos de risco.
- O modo sport retorna surebets em 13 plataformas, apenas pré-jogo. Quando uma perna é uma aposta com odds, profit_usd é null, porque o limite de aposta dela é desconhecido.
A Genesis API entrega dados de mercados de previsão em seis endpoints GET: pacotes de arbitragem entre Polymarket, Kalshi, Limitless, Predict.fun e Opinion, surebets em 13 plataformas, status das plataformas, análise, smart money, grandes operações e o ranking de traders. São os dados das páginas Arbitragem de previsão, Análise e Smart Money, em JSON. Com eles dá para montar um bot, um painel ou alertas; as operações e apostas você faz nas próprias plataformas.
Endpoints e planos
| Endpoint | O que retorna | Planos de API |
|---|---|---|
/predictions/arbitrage | Pacotes de arbitragem e surebets | Start, Pro, Max; modos llm e sport — Pro, Max |
/predictions/platforms | Status das plataformas | Start, Pro, Max |
/predictions/analytics | KPIs, variações de preço, fluxos de dinheiro | Pro, Max |
/predictions/smart-money | Grandes operações, baleias, padrões de insiders | Pro, Max |
/predictions/trades | Fluxo de operações da Polymarket | Pro, Max |
/predictions/traders | Top 300 traders da Polymarket por PnL | Pro, Max |
No Trial, os seis retornam 403 plan_restricted; no Start, o mesmo vale para requisições com mode=llm e mode=sport. O formato das respostas está no guia de respostas e erros, a cota no guia de limites.
Arbitragem de previsão: modos
O parâmetro mode define quais pacotes /predictions/arbitrage retorna.
mode | O que você recebe | kind | Planos |
|---|---|---|---|
exact | O mesmo evento em duas plataformas, o padrão | cross | Start, Pro, Max |
dutch | Um conjunto de desfechos de um evento em uma plataforma | dutch | Start, Pro, Max |
llm | Pares de eventos verificados por IA | cross | Pro, Max |
sport | Surebets em partidas | sport | Pro, Max |
O lucro já é calculado pelos livros de ofertas das plataformas, com taxas. Requisição de pacotes exact com lucro de pelo menos 1% e liquidação em até 30 dias:
curl -G "https://api.genesisarbitrage.com/v1/predictions/arbitrage" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-d mode=exact -d min_profit_pct=1 -d max_days=30
Filtros
| Parâmetro | Tipo | O que faz |
|---|---|---|
mode | string | exact (padrão), dutch, llm ou sport |
category | string | Categoria, como no campo category |
platform | string | Ao menos uma perna nesta plataforma; várias, separadas por vírgula |
min_profit_pct | number | Lucro mínimo, % |
min_profit_usd | number | Lucro mínimo, $; linhas com profit_usd = null são ignoradas |
min_apr | number | APR mínimo, % |
max_days | number | No máximo este número de dias até a liquidação |
sport, league | string | Esporte e liga, para mode=sport |
Os filtros são opcionais e se combinam. Escreva a plataforma como em legs[].platform: polymarket, kalshi, fonbet. Um mode desconhecido retorna 400 bad_request.
Um pacote e suas pernas
Exemplo ilustrativo: uma linha mode=exact da documentação, resumida.
{
"id": "x:exact:kalshi:KXFRENCHPRES-27-JCAS~polymarket:0x8c1f…",
"kind": "cross",
"match": "exact",
"title": "Will Jean Castex win the 2027 French presidential…",
"category": "Elections",
"ends_at": 1843308000,
"days_left": 562.87,
"size_usd": 107175.08,
"fees_usd": 28.08,
"profit_usd": 153.69,
"profit_pct": 0.14,
"apr_pct": 0.1,
"shares": 107356.85,
"risks": ["rules_differ", "end_mismatch"],
"legs": [
{
"platform": "polymarket",
"side": "yes",
"outcome": "Jean Castex",
"price_avg": 0.0013,
"cost_usd": 140.3,
"fee_usd": 5.6,
"url": "https://polymarket.com/event/next-french-presidential-…"
},
{
"platform": "kalshi",
"side": "no",
"outcome": "No",
"price_avg": 0.997,
"cost_usd": 107034.78,
"fee_usd": 22.48,
"url": "https://kalshi.com/events/KXFRENCHPRES-27"
}
]
}
| Campo | Significado |
|---|---|
id, first_seen, updated_at | Id estável, quando o pacote apareceu e foi atualizado |
kind, match | cross, dutch ou sport; match é exact, llm ou sport |
title, category | Evento ou mercado e sua categoria |
ends_at, days_left, starts_at | Momento da liquidação, dias até a liquidação, início da partida |
size_usd, fees_usd, shares | Tamanho da operação e taxas em $, número de shares |
profit_usd, profit_pct, apr_pct | Lucro em $ e %, APR; apr_pct é null com menos de um dia |
edge_cents, risks | Vantagem de preço em centavos por share, códigos de risco |
legs[].platform, market, outcome | Plataforma, mercado e desfecho da perna |
legs[].side | yes ou no — o que comprar; bet — aposta com odds |
legs[].price_best, price_avg, price_worst | Melhor preço, preço médio e pior preço ao percorrer o livro |
legs[].shares, cost_usd, fee_usd, url | Shares, custo, taxa e link do mercado da perna |
O preço de uma perna é uma fração de dólar: uma share paga US$ 1 se o desfecho vencer, então 0.997 é 99,7¢. Se as duas plataformas liquidam da mesma forma, uma perna vence aconteça o que acontecer, e shares é o valor que você recebe. rules_differ indica que as regras de liquidação das plataformas podem diferir; end_mismatch, que as datas de liquidação são diferentes.
No exemplo, 107.356,85 − 107.175,08 − 28,08 = US$ 153,69 de lucro, ou 153,69 / 107.203,16 = 0,14%. O dinheiro fica preso por 562,87 dias até a liquidação, então a taxa anual é 0,14 × 365 / 562,87 ≈ 0,1%. O filtro max_days elimina esses pacotes.
Modo sport: surebets
Uma linha sport é um mercado de uma partida: 2 ou 3 pernas em plataformas diferentes que, juntas, cobrem todos os desfechos. São 13 plataformas: Polymarket, Kalshi, Predict.fun e 10 plataformas de apostas — Fonbet, Betcity, Olimpbet, Marathon, 5051X, Melbet, Winline, BC.Game, EGB e Dafa Sports. Apenas pré-jogo: quando a partida começa, a surebet sai da lista.
Exemplo ilustrativo: uma linha mode=sport da documentação, com preços recalculados.
{
"id": "s:8812:RT:TOT:2.5:",
"kind": "sport",
"title": "Arsenal — Chelsea",
"sport": "soccer",
"league": "Premier League",
"teams": ["Arsenal", "Chelsea"],
"market_type": "TOT",
"period": "RT",
"line": 2.5,
"starts_at": 1794700800,
"size_usd": 1000,
"profit_usd": null,
"profit_pct": 2.39,
"legs": [
{
"platform": "polymarket",
"side": "yes",
"outcome": "Over 2.5",
"covers": ["O"],
"price_avg": 0.505,
"odds": null,
"stake_unit": 0.505,
"currency": "USD"
},
{
"platform": "fonbet",
"side": "bet",
"outcome": "Under 2.5",
"covers": ["U"],
"odds": 2.12,
"stake_unit": 0.471698,
"currency": "RUB"
}
]
}
| Campo | Significado |
|---|---|
sport, league, teams, flags | Esporte, liga, times, marcadores da partida |
market_type | WIN — resultado, HCP — handicap, TOT — total, BTTS — ambos os times marcam, CS — placar exato |
period, line, score | Período de liquidação, linha de handicap ou total, placar para CS |
legs[].covers | Desfechos que a perna cobre: O — acima, U — abaixo |
legs[].odds | Odds decimais; null para a compra de YES ou NO |
legs[].stake_unit | Fração da aposta: quanto colocar na perna para receber US$ 1 se ela vencer, taxas incluídas |
legs[].currency | A moeda da plataforma |
Para uma aposta com odds, stake_unit = 1 / odds: 1 / 2,12 = 0,471698. As frações de aposta das pernas somam 0,505 + 0,471698 = 0,976698, abaixo de 1, daí o lucro de 1 / 0,976698 − 1 = 2,39%. Para dividir o seu próprio valor, use aposta da perna = valor × stake_unit / Σ stake_unit.
size_usd é o valor de compras nas plataformas de previsão que os livros de ofertas delas conseguem absorver. US$ 1.000 a 0,505 compram 1.000 / 0,505 ≈ 1.980,2 shares YES de «Over 2.5». Para que «Under 2.5» pague o mesmo, a aposta na Fonbet é 1.980,2 × 0,471698 ≈ US$ 934,06.
A Fonbet aceita apostas em rublos (currency = RUB): converta o valor pela sua própria cotação, pois o câmbio não entra em profit_pct. Aqui profit_usd é null porque a plataforma de apostas não publica o limite de aposta.
Status das plataformas
/predictions/platforms mostra o quão recentes são os dados de arbitragem. Não recebe parâmetros; data traz duas listas:
{
"platforms": [
{
"platform": "kalshi",
"mode": "rest",
"quotes_at": 1794675858,
"full_scan_at": 1794675012,
"markets": 26187,
"hot_markets": 188
}
],
"bookmakers": [
{
"bookmaker": "fonbet",
"title": "Fonbet",
"ok": true,
"events": 1840,
"matched_events": 212,
"updated_at": 1794675855,
"currency": "RUB"
}
]
}
platforms[].mode— modo do feed da plataforma de previsão:ws,restoudownquando o feed não está funcionando.quotes_atefull_scan_at— horário das últimas cotações e da última varredura completa dos mercados;marketsehot_markets— mercados no total e mercados ativos.bookmakers[]— plataformas de apostas:ok— se a coleta funciona,eventsematched_events— eventos no total e pareados com outras plataformas,currency— a moeda das apostas.
É melhor pular pacotes com uma plataforma em down ou com ok = false: os preços podem ter mudado.
Análise, smart money, operações e traders
Quatro endpoints do Pro e do Max espelham as telas dos guias de Análise e Smart Money.
| Endpoint | Parâmetros | O que contém |
|---|---|---|
/predictions/analytics | nenhum | KPIs, variações de preço em 1 h e 24 h, fluxos de dinheiro, mercados prestes a liquidar, novos mercados |
/predictions/smart-money | nenhum | KPIs, fluxos de dinheiro, insiders, concentration, smart_vs_price |
/predictions/trades | period, wallet, category, side, min_usd, insider | Operações da Polymarket, as mais recentes primeiro |
/predictions/traders | period: 30d (padrão), 7d, all | Top 300 traders da Polymarket por PnL |
O rótulo insider descreve o padrão de comportamento de uma carteira e não prova nada: um endereço novo de um trader experiente pode operar da mesma forma.
Parâmetros do fluxo de operações; period define o limite:
| Parâmetro | Tipo | O que faz |
|---|---|---|
period | string | live (padrão) — operações a partir de US$ 1.000, a partir de US$ 100 para uma carteira smart; today e 7d — takers a partir de US$ 5.000 |
wallet | string | Operações de uma carteira |
category | string | Categoria do mercado |
side | string | buy ou sell |
min_usd | number | Valor mínimo da operação, $ |
insider | boolean | true — somente operações com rótulo insider |
curl -G "https://api.genesisarbitrage.com/v1/predictions/trades" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX" \
-d period=today -d side=buy -d min_usd=10000
{
"ts": 1794675812,
"wallet": "0x3a1c…f09e",
"tags": ["whale", "smart"],
"title": "Will Bitcoin reach $150k in 2026?",
"outcome": "No",
"side": "buy",
"price": 0.82,
"shares": 30487.8,
"usd": 25000,
"role": "taker",
"insider": false,
"bid_now": 0.81,
"ask_now": 0.83
}
usd = price × shares: 0,82 × 30.487,8 ≈ 25.000. bid_now e ask_now são os preços atuais do desfecho: seguir essa operação agora custa 0,83, 1¢ a mais do que o trader pagou.
/predictions/traders traz o PnL de todo o período, de 30 e de 7 dias (pnl_usd), roi_pct, won de resolved e o minigráfico pnl_series. Coloque um endereço do ranking no wallet do fluxo de operações.
Como usar
Confira seu plano e as plataformas
/account/usagemostra seu plano,/predictions/platforms— o quão recentes são as cotações.Peça pacotes com filtros
min_profit_pctemax_dayscortam o ruído e os pacotes de prazo longo.Verifique riscos e regras
Com
rules_differ, leia as regras de liquidação das duas plataformas.Consulte sem exceder a atualização do seu plano
Use um intervalo de pelo menos
meta.freshness_sece devolva oETagemIf-None-Match: uma resposta304não consome cota.Opere você mesmo
Abra o mercado em
legs[].urle confira o preço no livro de ofertas dele.
A mesma requisição exact em Python:
import os
from datetime import datetime, timezone
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
params = {"mode": "exact", "min_profit_pct": 1, "max_days": 30}
r = requests.get(f"{API}/predictions/arbitrage", headers=HEADERS,
params=params, timeout=10)
if r.status_code == 403:
raise SystemExit("Endpoint or mode is not part of your API plan")
r.raise_for_status()
body = r.json()
ts = datetime.fromtimestamp(body["meta"]["updated_at"], timezone.utc)
print(f"Bundles: {body['meta']['count']}, data as of {ts:%H:%M:%S} UTC")
for b in body["data"]:
print(f"{b['profit_pct']:.2f}% · ${b['profit_usd']:.2f} · "
f"{b['days_left']:.0f} d · {b['title'][:40]}")
for leg in b["legs"]:
print(f" {leg['platform']}: {leg['side']} "
f"{leg['outcome']} at {leg['price_avg']}")
if b["risks"]:
print(" risks:", ", ".join(b["risks"]))
No site, os mesmos pacotes são explicados nos guias Arbitragem de previsão e Modo Sport; as APIs oficiais das plataformas, nos artigos sobre as APIs da Polymarket e da Kalshi e sobre odds de apostas via API.
Perguntas e respostas
Posso comprar contratos ou fazer apostas pela Genesis API?
Não. A Genesis API só lê dados e não envia ordens: você opera e aposta por conta própria nas plataformas.
Por que profit_usd é null em uma surebet?
Pelo menos uma perna é uma aposta com odds, e a plataforma não publica o limite de aposta. A porcentagem de lucro é conhecida; calcule o valor de cada perna a partir de stake_unit.
A API inclui surebets ao vivo?
Não, apenas pré-jogo. Por que o ao vivo é mais arriscado está no artigo sobre pré-jogo e ao vivo.
Qual plano preciso para surebets?
Pro ou Max: no Start, mode=sport retorna 403 plan_restricted. Os preços estão na página Preços da Genesis API.