A corretora que seu bot pode se dar ao luxo de quebrar.

Endpoints

Vinte e quatro delas. Tudo é JSON sobre HTTPS, com CORS ativado e um único cabeçalho. Troque v1 por v2 em qualquer caminho para receber o envelope {ok,data,ts}.

bars = get(f"/api/bot/v1/klines?symbol=BTC&interval=1")
while len(all_bars) < wanted:
    end_ms = bars[0]["time"] * 1000          # oldest candle in hand
    bars = get(f"/api/bot/v1/klines?symbol=BTC&interval=1&end={end_ms}")
    if not bars: break
    all_bars = bars + all_bars

Legível por máquina: especificação OpenAPI 3.1 com schemas completos de requisição e resposta · uma referência interativa de onde você pode disparar chamadas · o changelog (JSON).

Como o motor funciona

Realismo de execução, porque um backtest que te lisonjeia não vale nada

Duas coisas neste motor são deliberadamente generosas, e é melhor citá-las do que deixar você descobrir numa conta real. Uma ordem a mercado executa ao preço ao vivo, então uma posição nova mostra 0.00 não realizado e a linha de entrada fica exatamente onde você pediu. E a margem de manutenção é fixa em 0.5%, qualquer que seja o valor da posição. Para aprender a operar, as duas são a escolha certa. Para provar uma estratégia, são otimistas, e quanto maior o tamanho, mais otimistas ficam.

Por isso são chaves liga/desliga, não suposições. Desligadas por padrão - nada do que você já construiu muda - e ligadas, o preço de execução e o preço de liquidação se comportam como um book real e uma tabela real de limites de risco os fazem se comportar.

GET  /api/bot/v2/realism                     // your setting, the venue table and the whole tier ladder
POST /api/bot/v2/realism {"slippage": true, "margin_tiers": true, "margin_venue": "binance"}

# or per call, so one strategy can be tested both ways without touching the account
POST /api/bot/v1/open {"symbol":"BTC","side":"long","margin_usd":100,"leverage":10,
                       "slippage": true, "margin_tiers": true, "mmr_pct": 0.4}

Esses três são apenas um subconjunto. A simulação inteira é configurável - o tamanho do book e se ele é um orçamento real, seus próprios números de slippage e taxas, impacto do tamanho, latência, execuções parciais, recusas e funding - e oito presets a configuram em uma chamada. Uma posição mantém a margem de manutenção com que foi executada, então ativar isso nunca reescreve um trade que você já tem, e cada fechamento registra com o que rodou. É daí que vem a coluna Fills da arena - uma tabela que ranqueia bots deveria dizer quais deles estavam no modo fácil.

Monte a plataforma em que você realmente vai operar

As três chaves acima fazem parte de algo maior. Tudo o que este motor assume é um campo que você pode definir: o tamanho do book e se ele é um orçamento real, quanto custa atravessar o livro de ordens na entrada e na saída, quanto tempo sua ordem fica em trânsito, se uma ordem é executada parcialmente, com que frequência a plataforma diz não, quanto você paga de taxas, se o funding é cobrado e onde fica o preço de liquidação.

Os padrões são deliberadamente fáceis, e vale dizer isso com clareza. Uma ordem a mercado é executada inteira ao preço ao vivo, a margem de manutenção é fixa em 0.5%, o saldo é um placar que nunca recusa uma abertura, e não há latência nem impacto do tamanho. É o lugar certo para colocar um bot para rodar. É o lugar errado para julgar se ele tem vantagem. Uma chamada muda isso.

GET  /api/bot/v2/sim                    # your profile, every field with its range, and the presets
POST /api/bot/v2/sim {"preset": "realistic"}

# or exactly your own venue
POST /api/bot/v2/sim {"start_balance_usd": 2500, "margin_enforced": true,
                      "slippage": true, "slippage_bps": 8, "impact_bps_per_100k": 15,
                      "latency_ms": 250, "taker_bps": 5.5, "margin_venue": "bybit"}

Valores fora do intervalo são recusados, nunca ajustados - uma estratégia jamais deve ser medida sob uma configuração que você não escolheu. Uma posição mantém, pelo resto da vida, a margem de manutenção, a taxa e o custo de cruzamento de saída com que foi executada; ligar qualquer coisa nunca reescreve um trade que você já tem.

Oito presets, para você não ter que inventar dezoito números

Cada campo, seu intervalo e o que ele muda

O que isto não modela, declarado em vez de descoberto

Um stop-loss, take-profit ou liquidação executa no próprio nível e nunca paga o custo de cruzamento: a varredura do lado do servidor roda sobre todas as contas de uma vez e não consegue ler um perfil por passada. Não há livro de ordens com profundidade real por trás do modelo de impacto — impact_bps_per_100k é um custo linear declarado, não um livro simulado. E todo o custo de cruzamento da saída é cobrado contra o preço de marcação, que é um spread só, não um bid e um ask que você possa cotar separadamente. Todo o resto acima é aplicado exatamente como escrito.

Cada valor deste perfil pode ser lido de volta em GET /api/bot/v2/sim, incluindo como seria uma execução agora mesmo — um número que o bot não consegue ler de volta é um número que ele precisa adivinhar. GET /api/bot/v2/report então mostra quanto a execução realmente custou: taxas, funding, bruto contra líquido e kept_pct, a parcela do bruto que sobreviveu. Esse é grátis em todos os planos, porque não é um detalhamento de onde está o seu edge — é se o edge é real.

Taxas como na corretora que você realmente vai usar

Por padrão, toda execução paper paga a taxa da MarginPad: 0.055% por lado em cripto, as duas pontas, cobrada como round trip no fechamento. É uma média justa, mas não é a conta exata de ninguém. Se você já sabe onde o bot vai rodar de verdade, cobre a conta paper pela tabela dessa corretora - a taxa taker publicada, menos o desconto de indicação que um cadastro pela MarginPad recebe lá - para que o forward test se liquide como a conta real vai se liquidar:

GET  /api/bot/v2/fees                       // the table below + your current default
POST /api/bot/v2/fees  {"venue":"hyperliquid"}   // account default: every open from now on, site and API
POST /api/bot/v2/open  {"symbol":"BTC","side":"long","margin_usd":100,"leverage":10,"fee_venue":"bybit"}   // just this one
POST /api/bot/v2/open  {..., "dry_run":true}      // -> fee_venue, taker_fee_pct, fee_vs_marginpad_default_usd

As taxas são o nível base publicado das corretoras e os descontos que informamos em /exchanges/; a API as retorna com source para você saber que são números divulgados, não medições. As duas pontas pagam a taxa taker (o motor paper executa a mercado; um rebate maker numa entrada pendente não é modelado). Só perps cripto - ações, forex, metais e índices mantêm as taxas por classe da MarginPad, qualquer que seja a corretora. Posições abertas mantêm a taxa com que foram executadas; o teto de alavancagem extrema (um round trip nunca acima de 20% da margem) continua valendo. A mesma escolha é o seletor "Taxas como na" no formulário do Paper Trade, então um bot e os trades manuais do dono dele pagam taxas idênticas.

Escrevendo um bot que não quebra

Sempre envie client_order_id ao abrir. Esta é a linha mais importante destes docs. Sem ele, uma requisição que expira na rede deixa você no escuro: a posição abriu ou não? Tente de novo e você pode ter duas. Com ele, a nova tentativa devolve a posição que a primeira chamada criou, marcada com idempotent: true:

POST /api/bot/v2/open
{"symbol":"BTC","side":"long","margin_usd":100,"leverage":5,"client_order_id":"sig-2026-08-19-1403"}

// first call            -> {"ok":true,"data":{"position":{"id":"bot...", ...}}}
// same call retried     -> {"ok":true,"data":{"position":{"id":"bot...", ...},"idempotent":true}}

Use um valor que a sua estratégia consiga gerar de forma determinística - um id de sinal, ou símbolo mais timestamp do candle. Os ids são lembrados por 7 dias.

Fechar também aceita uma. Envie client_order_id em /close e uma nova tentativa informa o que a primeira chamada fez (idempotent: true) em vez de um erro que você precisa interpretar.

Envie o symbol ao fechar. Toda linha de /positions já o traz, então é de graça adicionar e isso encurta o fechamento de forma mensurável:

POST /api/bot/v2/close
{"id":"bot...","symbol":"BTC"}    // one price fetch, one round trip
{"id":"bot..."}                   // server must first look up which symbol to price

Nosso trading store é uma única instância fixada em uma região, então cada salto extra custa o que custa a ida e volta até ela de onde você está. Medido em 2026-08-19: cerca de 20 ms a partir da Europa, mas 198 ms de mediana e 368 ms no percentil 95 a partir de Singapura. Um feed de preços frio soma cerca de 400 ms por cima, e sem a dica um fechamento em um par líquido poderia acabar esperando por um ilíquido no mesmo lote. Com a dica, um fechamento é um salto mais um preço já aquecido. Um symbol errado ou desatualizado não custa nada - o servidor percebe e volta ao caminho normal.

Não gaste seu orçamento de requisições com polling. A maioria dos bots gasta a maior parte das chamadas perguntando "algo mudou?". Duas coisas tornam isso quase gratuito:

# 1. state changes: send back the ETag, get 304 and an empty body when nothing moved
curl -H "X-API-Key: $KEY" -H 'If-None-Match: W/"1a2b3c-4"' \
     https://marginpad.io/api/bot/v1/positions

# 2. live prices: /price is KEYLESS, so it costs nothing against your 120/min
curl https://marginpad.io/api/bot/v1/price?symbol=BTC

O ETag cobre o estado estrutural - ids de posição, status, quantidade, stop, alvo, saída - e deliberadamente não o preço de marcação, que muda a cada tick e faria o ETag nunca bater. Então: consulte /positions para saber "meu stop disparou?" e consulte o /price sem chave para o PnL. Fique de olho em X-RateLimit-Remaining e reduza o ritmo conforme Retry-After.

WebSocket - pare de fazer polling de vez

Posições e preços são enviados a você, então você descobre que seu stop disparou em poucos segundos, em vez de na próxima consulta:

wss://marginpad.io/api/bot/v2/stream?api_key=mpb_…

<- {"type":"welcome","data":{"channels":["positions","prices"],"tick_ms":2000},"ts":…}
<- {"type":"snapshot","data":{"positions":[…]},"ts":…}
<- {"type":"position","data":{"event":"closed","position":{…,"pnl_usd":-1.24}},"ts":…}
<- {"type":"prices","data":{"BTC":64770.1},"ts":…}

-> {"op":"subscribe","channels":["positions"]}     // prices off, events only
-> {"op":"ping"}                                    // <- {"type":"pong"}

Eventos: position com event: opened | updated | closed dispara quando algo realmente muda - uma execução, um stop se movendo, um fechamento, uma liquidação. prices traz o preço de marcação dos seus símbolos abertos a cada tick. O movimento do preço de marcação sozinho nunca gera um evento position, então o canal fica quieto quando nada aconteceu.

Os stops são liquidados mais rápido enquanto você está conectado. O stream aciona a mesma varredura de SL/TP/liquidação do lado do servidor que o caminho REST usa, na cadência de ~2s, em vez de deixar sua posição para a varredura periódica.

Até 3 sockets simultâneos por conta, compartilhados entre suas chaves. Os sockets são reciclados após 6 horas - reconecte e você recebe um snapshot novo. Se a conexão cair, trate o próximo snapshot como a verdade em vez de reprocessar eventos perdidos.

Webhooks - eventos enviados ao seu servidor API PRO

Medido nos últimos 40 dias: 76.4% de todas as chamadas a esta API são polling de /positions e /account atrás de eventos que ainda não aconteceram. Um webhook inverte isso - nós fazemos POST para você quando algo realmente acontece, com o mesmo formato Position que um polling teria retornado, e funciona enquanto seu bot está offline, reiniciando ou implantado num lugar que não consegue manter um socket.

POST /api/bot/v2/webhooks
{"act":"add","url":"https://bot.example.com/marginpad","events":["position.closed","position.liquidated","order.filled"]}

-> {"ok":true,"data":{"webhook":{"id":"wh…","secret":"whs_…","events":[…],"active":true}}}

# what arrives at your URL, seconds after the event:
POST https://bot.example.com/marginpad
X-MP-Event: position.closed        X-MP-Delivery: 1841
X-MP-Timestamp: 1789124656008      X-MP-Signature: sha256=3763dc5d…
{"event":"position.closed","ts":1789124656008,"hook_id":"wh…","data":{"id":"bot…","symbol":"BTC","status":"closed","pnl_usd":-0.08,"close_reason":"SL hit",…}}

Eventos: position.opened · position.updated (um stop ou alvo mudou) · position.closed · position.liquidated · order.filled (traz a posição que criou) · order.expired · order.cancelled. Omita events para receber todos. Trades feitos pelo site na mesma conta também os disparam.

Verifique cada entrega. X-MP-Signature é sha256=HMAC_SHA256(secret, raw body) com o secret retornado quando você adicionou o hook. Compare antes de interpretar o body; os dois SDKs trazem verify_webhook / verifyWebhook. Responda 2xx em até 6 segundos - qualquer outra coisa é tentada de novo 5 vezes com backoff (30 s, 1, 2, 4 min), e um hook é pausado após 25 falhas consecutivas; GET /webhooks mostra active, consecutive_failures e last_error para você ver o motivo. Três hooks por conta no Pro, quinze no Max, cinquenta no Business; as entregas são best-effort, o snapshot do WebSocket e /positions continuam sendo a fonte da verdade.

Teste antes de escrever um receptor: registre https://marginpad.io/api/whsink/<any-token-you-choose> como URL e depois abra um GET nesse mesmo endereço - ele devolve as últimas 20 entregas (headers e body) por 15 minutos. Sem autenticação; o token é o segredo.

Books - uma estratégia, um resultado limpo 2.5

Um book é um diário, saldo, relatório e curva de patrimônio separados dentro da sua conta. Crie uma chave com o nome de um book e toda chamada feita com essa chave opera nesse book; sua conta principal e seus outros books nunca o veem. Contas Free recebem um book além da conta principal, API Pro cinco, Max vinte e Business cinquenta.

POST /api/bot/key  {"act":"create","name":"rsi bot","book":"rsi"}   // key bound to the book "rsi"
GET  /api/bot/v1/accounts        // every book with lifetime numbers and its keys
GET  /api/bot/v1/account         // "account":"rsi" on a book key, "main" otherwise
POST /api/bot/v1/reset  {"confirm":true}   // this book back to $10,000: closes archived, orders cancelled
GET  /api/bot/v1/equity?days=30&step_min=60   // equity curve + max_drawdown_pct

O reset é recusado com 409 open_positions_exist enquanto algo estiver aberto: feche primeiro e depois faça o reset. Os trades arquivados são mantidos (nunca apagados), mas o relatório, o ledger, o /trades e a curva de capital começam a partir do reset, e um navegador que ainda guarde o diário antigo não consegue enviá-lo de volta. Os webhooks disparam nos hooks da conta com "account":"rsi" no payload, então um único receptor atende todos os books.

Replay - rode seu bot em um dia passado 2.6

Faça o backtest com o código que você vai rodar ao vivo. Inicie um replay de um dia UTC passado e as mesmas rotas que seu bot já chama passam a atuar em um diário de replay separado, com preços vindos dos próprios candles de 1 minuto da MarginPad no cursor. Stops, alvos e liquidações são verificados em cada candle entre duas das suas chamadas, na máxima e na mínima, com a mesma conta de taxas e funding do ao vivo. Nada de um replay chega aos rankings, à arena ou ao seu relatório.

POST /api/bot/v1/replay  {"symbol":"BTC","day":"2026-09-11","speed":120}   // 120 market seconds per real second: a day in 12 minutes
GET  /api/bot/v1/replay?interval=5&bars=120       // cursor, price, progress, candles up to the cursor
POST /api/bot/v1/open    {...}                        // acts on the replay book at the cursor price while the replay runs
POST /api/bot/v1/replay  {"act":"stop"}               // close at the cursor, get the summary, empty the replay journal

A velocidade vai de 1 (tempo real) a 600 (um dia em 2.4 minutos). Um replay por chave por vez, só cripto, só ordens a mercado por enquanto: leia o preço e os candles do replay em GET /v1/replay, já que /v1/price e /v1/klines, sem chave, continuam respondendo dados ao vivo.

Gerenciando suas chaves

Você pode ter várias chaves numa só conta - mantenha um bot de backtest e um bot ao vivo separados e revogue um sem tocar no outro. O uso e os limites de requisição são contados por chave, então cada uma tem seu próprio orçamento e sua própria linha nas suas estatísticas. Logado no site, pelo navegador:

POST /api/bot/key  {"act":"list"}                          // all your keys
POST /api/bot/key  {"act":"create","name":"backtest-bot"}   // new key
POST /api/bot/key  {"act":"rename","key":"mpb_...","name":"live-bot"}
POST /api/bot/key  {"act":"revoke","key":"mpb_..."}         // usage history is kept

Uma chave revogada retorna 401 revoked_key. Chaves são segredos - quem tiver uma pode operar sua conta paper. Crie e revogue no topo desta página.

Arena de bots - um placar público para bots

Toda conta ou book com pelo menos cinco fechamentos abertos pela API nesta temporada de 14 dias entra no ranking de /arena/ por PnL realizado líquido de taxas e funding, com taxa de acerto, retorno sobre o placar de $10,000, ROE médio e liquidações. Sem prêmios e sem nada para se inscrever: opere pela API e a tabela encontra você. JSON: GET /api/arena.

Use no Claude, ChatGPT ou Cursor

A MarginPad mantém um servidor MCP remoto, então um assistente de IA pode ler os mercados e operar sua conta de paper trading diretamente - sem código de ligação:

https://marginpad.io/mcp

Adicione como servidor MCP remoto no seu cliente e defina o header X-API-Key: mpb_… se quiser as ferramentas de paper trading. As ferramentas de dados de mercado não precisam de chave. Vinte e oito ferramentas estão expostas: preços, candles, mercados, screener, funding, interesse aberto, liquidações, medo e ganância, o calendário econômico, duas calculadoras, e paper open (com trailing stops e dry run) / ordens limite e stop / modify / cancel / close / sltp / positions / orders / balance / trades / report / fees / accounts / reset / equity / replay. GET /mcp no navegador retorna o descritor do servidor.

Formato de resposta - v1 e v2

/api/bot/v1/* está congelada. Os corpos de resposta não vão mudar; bots escritos para ela continuam funcionando indefinidamente, e ela ainda recebe correções de bugs.

/api/bot/v2/* é a mesma API com o envelope que nossos endpoints de dados já usam - um formato previsível para sucesso e falha, para você escrever o parsing uma vez só:

{ "ok": true,  "data": { ... }, "ts": 1787200000000 }
{ "ok": false, "error": { "code": "unknown_symbol", "message": "No price feed for that symbol...", "symbol": "FOO" }, "ts": 1787200000000 }

Mesmos caminhos, mesmos parâmetros, mesma chave - troque v1 por v2 na URL. Os valores de code dos erros são identificadores estáveis; message é para humanos e pode ser reescrita.

Códigos de erro

Na /v2, as falhas são sempre {"ok":false,"error":{"code","message"},"ts"}. O code é um identificador estável em que você pode se basear; a message é texto livre e pode ser reescrita. Alguns erros trazem o valor de que você precisa para corrigir a chamada - sl_wrong_side e tp_wrong_side incluem o preço ao vivo.

Ainda travado? O corpo do erro é o primeiro lugar para olhar, e o status é o segundo. Se nenhum dos dois responder, escreva para support@marginpad.io com o endpoint e o corpo exato que devolvemos - o que mais incluir está na página de suporte. Uma pessoa lê.

API grátis de dados de liquidação DADOS AO VIVO

Liquidações em tempo real agregadas de oito corretoras pelo nosso próprio coletor - os dados por trás do nosso feed Rekt e do mapa de calor de liquidações, expostos como JSON grátis. Dados comparáveis normalmente ficam atrás de paywall a $300+/mês em outros lugares; aqui não precisam de nenhuma chave de API. Com cache na borda e limite de requisições, aguentam bem bots que fazem polling.

Atribuição é bem-vinda (link marginpad.io), mas não obrigatória. A cobertura é de ~70%+ do fluxo de liquidações do mercado - as corretoras que movem o preço. Uso educacional; sem SLA de uptime. Só quer dados de mercado? Toda a superfície sem chave está documentada na página da API grátis de dados cripto.

Backtest, paper, ao vivo - nessa ordem

A maioria dos bots de trading cripto que parecem lucrativos num backtest perde dinheiro na primeira semana em que vai para o ao vivo. Backtests reproduzem candles históricos limpos - eles não pegam uma race condition na lógica das suas ordens, um bug de dimensionamento de posição que só aparece depois de uma sequência de perdas, ou uma alavancagem que cresce em silêncio além do que sua margem aguenta. O forward testing roda o mesmo bot, o mesmo caminho de código, contra preços reais ao vivo em tempo real. Se a estratégia tem uma falha, ela aparece aqui, onde um bug não custa nada.

A etapa do meio é a que a maioria das pessoas pula - e a que as teria salvado. Faça o backtest de uma ideia aqui, teste-a em tempo real nesta API e só depois deposite em uma conta.

FAQ

Guias e tutoriais