El exchange que tu bot se puede permitir romper.

Endpoints

Veinticuatro en total. Todo es JSON sobre HTTPS, con CORS activado y una sola cabecera. Cambia v1 por v2 en cualquier ruta para obtener el sobre {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

Legible por máquina: especificación OpenAPI 3.1 con los esquemas completos de petición y respuesta · una referencia interactiva desde la que puedes disparar llamadas · el changelog (JSON).

Cómo funciona el motor

Realismo de ejecución, porque un backtest que te favorece no vale nada

Dos cosas en este motor son deliberadamente generosas, y es mejor nombrarlas que dejar que las descubras en una cuenta real. Una orden a mercado se ejecuta al precio en vivo, así que una posición nueva marca 0.00 de no realizado y la línea de entrada queda exactamente donde la pediste. Y el margen de mantenimiento es un 0.5% fijo, sin importar cuánto valga la posición. Para aprender a operar, ambas son la decisión correcta. Para poner a prueba una estrategia son optimistas, y cuanto mayor es el tamaño, más optimistas se vuelven.

Así que son interruptores, no supuestos fijos. Desactivados por defecto (nada de lo que ya construiste cambia) y, al activarlos, el precio de ejecución y el precio de liquidación se comportan como los haría comportarse un libro de órdenes real y una tabla de límites de riesgo real.

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}

Estos tres son un subconjunto. Toda la simulación es configurable - el tamaño del libro y si es un presupuesto real, tus propias cifras de slippage y comisión, el impacto por tamaño, la latencia, las ejecuciones parciales, los rechazos y el funding - y ocho preajustes lo configuran en una sola llamada. Una posición conserva el margen de mantenimiento con el que fue ejecutada, así que activar esto nunca reescribe una operación que ya tienes abierta, y cada cierre registra con qué condiciones se ejecutó. De ahí viene la columna Fills de la arena - una tabla que clasifica bots debería decir cuáles estaban en modo fácil.

Construye el exchange en el que realmente vas a operar

Los tres interruptores de arriba son parte de algo más grande. Todo lo que este motor asume es un campo que puedes configurar: el tamaño del libro y si es un presupuesto real, lo que cuesta cruzar el libro de órdenes al entrar y al salir, cuánto tiempo está tu orden en tránsito, si una orden se ejecuta parcialmente, con qué frecuencia el exchange dice que no, cuánto pagas en comisiones, si se cobra funding o no, y dónde se ubica el precio de liquidación.

Los valores predeterminados son deliberadamente fáciles, y vale la pena decirlo sin rodeos. Una orden a mercado se ejecuta completa al precio en vivo, el margen de mantenimiento es un 0.5% fijo, el saldo es un marcador que nunca rechaza una apertura, y no hay latencia ni impacto por tamaño. Ese es el lugar correcto para poner un bot a andar. Es el lugar equivocado para juzgar si tiene una ventaja. Una sola llamada cambia eso.

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"}

Los valores fuera de rango son rechazados, nunca ajustados al límite - una estrategia nunca debe medirse bajo una configuración que no elegiste. Una posición conserva el margen de mantenimiento, la tasa de comisión y el costo de cruce en la salida con los que fue ejecutada, para siempre; activar cualquier cosa nunca reescribe una operación que ya tienes abierta.

Ocho preajustes, para que no tengas que inventar dieciocho números

Cada campo, su rango y qué cambia

Lo que esto no modela, dicho claramente en vez de descubierto por sorpresa

Un stop-loss, take-profit o liquidación se ejecuta a su propio nivel y nunca paga el costo de cruce: el barrido del lado del servidor corre sobre todas las cuentas a la vez y no puede leer un perfil por cada pasada. No hay un libro de órdenes con profundidad real detrás del modelo de impacto — impact_bps_per_100k es un costo lineal declarado, no un libro simulado. Y todo el costo de cruce en la salida se cobra contra el mark, que es un único spread, no un bid y un ask que puedas cotizar por separado. Todo lo demás arriba se aplica exactamente como está escrito.

Cada cifra de este perfil se puede leer de vuelta desde GET /api/bot/v2/sim, incluyendo cómo se vería una ejecución justo ahora — un número que un bot no puede leer de vuelta es un número que tiene que adivinar. GET /api/bot/v2/report te dice entonces cuánto costó realmente la ejecución: comisiones, funding, bruto contra neto, y kept_pct, la parte del bruto que sobrevivió. Ese dato es gratis en todos los planes, porque no es un desglose de dónde está tu ventaja — es si esa ventaja es real.

Comisiones como en el exchange que realmente usarás

Por defecto, cada ejecución simulada paga la tasa de MarginPad: 0.055% por lado en cripto, ambas piernas, cobradas como round trip al cierre. Eso es un promedio justo, pero no es la factura exacta de nadie. Si ya sabes dónde correrá el bot de verdad, cobra a la cuenta simulada según la tabla de ese exchange - su tasa taker publicada, menos el descuento de referido que consigue un registro de MarginPad allí - así el forward test se liquida como lo hará la cuenta real:

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

Las tasas son el nivel base publicado de los exchanges y los descuentos que indicamos en /exchanges/; la API las devuelve con source para que sepas que son cifras publicitadas, no mediciones. Ambas piernas pagan la tasa taker (el motor de paper trading ejecuta a mercado; no se modela un rebate de maker en una entrada pendiente). Solo perpetuos cripto - acciones, forex, metales e índices mantienen las tasas de la clase de MarginPad sea cual sea el exchange. Las posiciones abiertas mantienen la tasa con la que se ejecutaron; el límite de apalancamiento extremo (un round trip nunca por encima del 20% del margen) sigue aplicando. La misma opción es el selector "Fees as on" en el formulario de Paper Trade, así un bot y las operaciones manuales de su dueño pagan comisiones idénticas.

Escribir un bot que no se rompa

Envía siempre client_order_id al abrir. Esta es la línea más importante de toda esta documentación. Sin ella, una petición que expira en la red te deja adivinando: ¿se abrió la posición o no? Reintentas y puede que tengas dos. Con ella, el reintento devuelve la posición que creó la primera llamada, marcada como 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}}

Usa un valor que tu estrategia pueda regenerar de forma determinista - un id de señal, o el símbolo más la marca de tiempo de la vela. Los ids se recuerdan durante 7 días.

Cerrar también acepta uno. Envía client_order_id en /close y un reintento reporta lo que hizo la primera llamada (idempotent: true) en vez de un error que tienes que interpretar.

Envía symbol al cerrar. Cada fila de /positions ya lo lleva, así que agregarlo no cuesta nada y acorta de forma medible el cierre:

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

Nuestro almacén de trading es una única instancia fijada a una región, así que cada salto extra cuesta lo que cuesta el round trip hasta ella desde donde estés. Medido el 2026-08-19: cerca de 20 ms desde Europa pero 198 ms de mediana y 368 ms en el percentil 95 desde Singapur. Un feed de precio frío suma alrededor de 400 ms más, y sin la pista, un cierre en un par líquido podría terminar esperando a uno ilíquido en el mismo lote. Con la pista, un cierre es un salto más un precio ya en caché. Un symbol incorrecto o desactualizado no cuesta nada - el servidor lo nota y usa el respaldo.

No gastes tu presupuesto de peticiones en polling. La mayoría de los bots gastan el grueso de sus llamadas preguntando "¿cambió algo?". Dos cosas hacen que eso sea casi gratis:

# 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

El ETag cubre el estado estructural - ids de posición, estado, cantidad, stop, objetivo, salida - y deliberadamente no el precio de referencia (mark price), que se mueve en cada tick y haría que el ETag nunca coincidiera. Así que: consulta /positions para saber "si saltó mi stop", y consulta el /price sin clave para el P&L. Vigila X-RateLimit-Remaining y reduce la frecuencia según Retry-After.

WebSocket - deja de hacer polling por completo

Las posiciones y los precios te llegan automáticamente (push), así te enteras de que tu stop saltó en un par de segundos, en vez de esperar a tu 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 con event: opened | updated | closed se dispara cuando algo realmente cambia - una ejecución, un stop que se mueve, un cierre, una liquidación. prices lleva el precio de referencia de tus símbolos abiertos en cada tick. El simple movimiento del precio de referencia nunca genera un evento position, así que el canal permanece en silencio cuando no ha pasado nada.

Los stops se resuelven más rápido mientras estás conectado. El stream impulsa el mismo barrido de SL/TP/liquidación del lado del servidor que usa la vía REST, con su cadencia de ~2s, en lugar de dejar tu posición a merced del barrido periódico.

Hasta 3 sockets simultáneos por cuenta, compartidos entre tus claves. Los sockets se reciclan cada 6 horas - al reconectar recibes un snapshot nuevo. Si la conexión se cae, trata el siguiente snapshot como la verdad en lugar de intentar reproducir los eventos perdidos.

Webhooks - eventos enviados a tu servidor API PRO

Medido durante los últimos 40 días: el 76.4% de cada llamada a esta API es un sondeo de /positions y /account buscando eventos que todavía no sucedieron. Un webhook invierte eso - te hacemos un POST cuando algo realmente sucede, con la misma forma de Position que habría devuelto un sondeo, y funciona incluso mientras tu bot está desconectado, reiniciando o desplegado en algún lugar que no puede mantener un 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 (un stop o un objetivo se movió) · position.closed · position.liquidated · order.filled (lleva la posición que creó) · order.expired · order.cancelled. Omite events para recibirlos todos. Las operaciones hechas en el sitio en la misma cuenta también los disparan.

Verifica cada entrega. X-MP-Signature es sha256=HMAC_SHA256(secret, raw body) con el secreto que se devuelve al añadir el hook. Compáralo antes de parsear el cuerpo; ambos SDK traen verify_webhook / verifyWebhook. Responde 2xx en menos de 6 segundos: cualquier otra cosa se reintenta 5 veces con espera creciente (30 s, 1, 2, 4 min), y un hook se pausa tras 25 fallos seguidos; GET /webhooks muestra active, consecutive_failures y last_error para que veas por qué. Tres hooks por cuenta en Pro, quince en Max y cincuenta en Business; las entregas son de mejor esfuerzo, y el snapshot del WebSocket y /positions siguen siendo la fuente de verdad.

Pruébalo antes de escribir un receptor: registra https://marginpad.io/api/whsink/<any-token-you-choose> como la URL, y luego abre GET en esa misma dirección - devuelve las últimas 20 entregas (headers y body) durante 15 minutos. Sin autenticación; el token es el secreto.

Books - una estrategia, un resultado limpio 2.5

Un book es un diario, un balance, un report y una curva de equity separados dentro de tu cuenta. Crea una clave con el nombre de un book y cada llamada hecha con esa clave opera ese book; tu cuenta principal y tus otros books nunca lo ven. Las cuentas Free tienen un book además del principal, API Pro cinco, Max veinte y Business cincuenta.

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

Reset se rechaza con 409 open_positions_exist mientras haya algo abierto: cierra primero, luego reinicia. Las operaciones archivadas se conservan (nunca se borran), pero el informe, el registro, /trades y la curva de equity empiezan desde el reset, y un navegador que aún tenga el diario antiguo no puede devolverlo. Los webhooks se disparan en los hooks de la cuenta con "account":"rsi" en el payload, así que un solo receptor sirve a todos los books.

Replay - corre tu bot a través de un día pasado 2.6

Haz backtest con el mismo código que vas a correr en vivo. Inicia un replay de un día UTC pasado y las mismas rutas que tu bot ya llama actúan sobre un diario de replay separado, cotizado con las propias velas de 1 minuto de MarginPad en el cursor. Los stops, los objetivos y las liquidaciones se comprueban en cada vela entre dos de tus llamadas, sobre el máximo y el mínimo, con la misma matemática de comisiones y funding que en vivo. Nada de un replay llega a las tablas, a la arena o a tu informe.

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

La velocidad va de 1 (tiempo real) a 600 (un día en 2.4 minutos). Un replay por clave a la vez, solo cripto, por ahora solo órdenes a mercado: lee el precio y las velas del replay desde GET /v1/replay, ya que el /v1/price y el /v1/klines sin clave siguen respondiendo datos en vivo.

Gestionar tus claves

Puedes tener varias claves en una cuenta - mantén separados un bot de backtest y un bot en vivo, y revoca uno sin tocar el otro. El uso y los límites de peticiones se cuentan por clave, así que cada una tiene su propio presupuesto y su propia línea en tus estadísticas. Con la sesión iniciada en el sitio, desde el 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

Una clave revocada devuelve 401 revoked_key. Las claves son secretas - cualquiera que tenga una puede operar tu cuenta de paper trading. Créalas y revócalas arriba de esta página.

Bot arena - una clasificación pública para bots

Toda cuenta o libro con al menos cinco cierres abiertos a través de la API en esta temporada de 14 días queda clasificado en /arena/ por PnL realizado neto de comisiones y funding, con tasa de acierto, rendimiento sobre la tarjeta de $10,000, ROE promedio y liquidaciones. Sin premios y sin nada que registrar: opera a través de la API y la tabla te incluye sola. JSON: GET /api/arena.

Úsalo desde Claude, ChatGPT o Cursor

MarginPad ejecuta un servidor remoto de MCP, así un asistente de IA puede leer los mercados y operar tu cuenta simulada directamente - sin código de conexión:

https://marginpad.io/mcp

Añádelo como servidor MCP remoto en tu cliente y pon el header X-API-Key: mpb_… si quieres las herramientas de paper trading. Las herramientas de datos de mercado no necesitan clave. Se exponen veintiocho herramientas: precios, velas, mercados, screener, funding, interés abierto, liquidaciones, fear and greed, el calendario económico, dos calculadoras, y apertura en paper (con trailing stops y dry run) / órdenes límite y stop / modificar / cancelar / cerrar / sltp / posiciones / órdenes / saldo / operaciones / informe / comisiones / cuentas / reset / equity / replay. GET /mcp en un navegador devuelve el descriptor del servidor.

Formato de respuesta - v1 y v2

/api/bot/v1/* está congelada. Sus cuerpos de respuesta no van a cambiar; los bots escritos contra ella siguen funcionando indefinidamente, y todavía recibe correcciones de errores.

/api/bot/v2/* es la misma API con el envoltorio que ya usan nuestros endpoints de datos - una sola forma predecible para el éxito y el fallo, para que escribas el parseo una sola vez:

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

Mismas rutas, mismos parámetros, misma clave - cambia v1 por v2 en la URL. Los valores de code de error son identificadores estables; message es para humanos y puede reformularse.

Códigos de error

En /v2, los fallos siempre tienen la forma {"ok":false,"error":{"code","message"},"ts"}. El code es un identificador estable sobre el que puedes ramificar tu lógica; el message es texto libre y puede cambiar de redacción. Algunos errores incluyen el valor que necesitas para corregir la llamada - sl_wrong_side y tp_wrong_side incluyen el precio en vivo.

¿Sigues atascado? El cuerpo del error es el primer lugar donde mirar, y estado es el segundo. Si ninguno lo resuelve, escribe a support@marginpad.io con el endpoint y el cuerpo exacto que te devolvimos - qué más incluir está en la página de soporte. Una persona lo lee.

API gratis de datos de liquidaciones DATOS EN VIVO

Liquidaciones en tiempo real agregadas de ocho exchanges por nuestro propio colector - los datos detrás de nuestro feed Rekt y del Mapa de Calor de Liquidaciones, expuestos como JSON gratis. En otros lugares, datos comparables suelen estar detrás de un muro de pago de $300+/mes; aquí no hace falta ninguna clave API. Con caché en el edge y límite de peticiones, así que soporta sin problema a los bots que hacen polling.

Se agradece la atribución (enlaza marginpad.io) pero no es obligatoria. La cobertura es ~70%+ del flujo de liquidaciones del mercado - los exchanges que mueven el precio. Uso educativo; sin SLA de uptime. ¿Solo quieres datos de mercado? Toda la superficie sin clave está documentada en la página de API gratis de datos cripto.

Backtest, paper, live - en ese orden

La mayoría de los bots de trading de cripto que parecen rentables en un backtest pierden dinero la primera semana que salen en vivo. Los backtests repiten velas históricas limpias: no detectan una condición de carrera en tu lógica de órdenes, un error de tamaño de posición que solo aparece tras una racha de pérdidas, ni un apalancamiento que crece en silencio más allá de lo que tu margen aguanta. El forward testing ejecuta el mismo bot, el mismo código, contra precios reales en vivo y en tiempo real. Si la estrategia tiene un fallo, aparece aquí, donde un error no te cuesta nada.

El paso intermedio es el que la mayoría se salta, y el que les habría salvado. Haz backtest de una idea aquí, pruébala en forward testing con esta API y luego financia una cuenta.

FAQ

Guías y tutoriales