io.github.Marginpad/sdk

MarginPad SDK

Free crypto-futures paper trading for bots and free market data. One key, no KYC, no deposit. Test a strategy or an AI agent against live prices with real fee schedules, funding, liquidations, limit and stop orders, trailing stops, webhooks and a WebSocket stream, then take the same code to a real exchange.

• Guide: https://marginpad.io/trading-api/
• Reference (OpenAPI, try it live): https://marginpad.io/api-docs/
• Status: https://marginpad.io/status/ - Changelog: https://marginpad.io/api/changelog.xml
• MCP server for Claude, ChatGPT and Cursor: https://marginpad.io/trading-api/#mcp

What the data behind it is

The market data these clients read is measured by MarginPad itself and published free, with no key, as pages and JSON:

• Liquidations across nine exchanges, from our own collector: https://marginpad.io/liquidations/ · live feed https://marginpad.io/rekt/ · per-coin maps such as https://marginpad.io/btc-liquidation-map/ · live heatmap https://marginpad.io/heatmap
• Hyperliquid whale positions read from the chain, with exact liquidation prices: https://marginpad.io/hyperliquid-whales/
• Funding, open interest and long/short: https://marginpad.io/funding/ · https://marginpad.io/open-interest/ · https://marginpad.io/long-short/
• One question, one measured answer: https://marginpad.io/how-many-traders-liquidated-today/ · https://marginpad.io/biggest-liquidation-today/ · https://marginpad.io/what-leverage-should-a-beginner-use/ · https://marginpad.io/where-can-i-test-a-trading-bot/
• The practice terminal the engine behind this API also runs: https://marginpad.io/paper-trade (no sign-up) and the season competition https://marginpad.io/trading-competition/

Install

pip install marginpad            # Python 3.8+, no dependencies (pip install "marginpad[stream]" for the WebSocket)
npm install marginpad            # Node 18+, zero dependencies

Python

from marginpad import MarginPad

mp = MarginPad("mpb_...")                                   # key from https://marginpad.io/trading-api/
print(mp.price("BTC"))                                      # keyless market data
pos = mp.open("BTC", "long", margin_usd=100, leverage=10, sl=58000, tp=66000,
              client_order_id="sig-2026-09-12-1403")        # idempotent: a retry returns the same position
mp.sltp(pos["id"], trail_pct=1.5)                           # trailing stop, ratcheted server-side
print(mp.account())

JavaScript

const { MarginPad } = require('marginpad');
const mp = new MarginPad('mpb_...');
const { position } = await mp.open({ symbol: 'BTC', side: 'long', margin_usd: 100, leverage: 10, client_order_id: 'sig-1' });
mp.stream(ev => console.log(ev.type, ev.data));             // positions pushed on change, prices each tick

Books, reset, equity, replay (2.5 / 2.6)

mp.accounts()                                   # every book of the account with lifetime numbers
mp.reset()                                      # this key's book back to $10,000 (archived, never deleted)
mp.equity(days=30, step_min=60)                 # equity curve + max drawdown
mp.replay_start("BTC", "2026-09-11", speed=120) # run the same code through a past day, 12 minutes per day
mp.replay(interval=5, bars=120)                 # cursor, price, candles up to the cursor
mp.replay_stop()                                # summary: closes, win rate, P&L, return, liquidations

A key minted with book ({"act":"create","name":"rsi","book":"rsi"} on POST /api/bot/key) trades a separate journal: one strategy, one key, one clean result. During a replay every trading call of that key acts on a replay journal priced from the candle under the cursor; stops, targets and liquidations are checked on every candle between two calls.

The simulation is yours to set

Eighteen fields and eight presets, so the paper venue can be the one you will actually trade. The defaults are deliberately frictionless, and nothing you have already built moves until you change them.

mp.sim()                                   # your profile, every field with its range, the presets
mp.sim(preset="realistic")                 # the honest middle, in one call
mp.sim(preset="bybit")                     # Bybit's published taker fee and maintenance margin
mp.sim(preset="brutal")                    # refusals, partial fills, a second of latency
mp.sim(start_balance_usd=2500, margin_enforced=True, slippage_bps=8, latency_ms=250)
mp.sim(reset=True)                         # back to the defaults

await mp.sim({ preset: 'realistic' });
await mp.sim({ start_balance_usd: 2500, margin_enforced: true, reject_rate_pct: 2 });

The book (start_balance_usd, margin_enforced, leverage_max, max_notional_usd), the fill (slippage, slippage_bps, impact_bps_per_100k, exit_slippage, latency_ms, partial_fills, min_fill_pct, reject_rate_pct), the cost (taker_bps, funding, funding_mult) and the liquidation (margin_venue, margin_tiers, mmr_pct).

Out-of-range values are refused, never clamped, and a position keeps the simulation it was filled under for life. margin_enforced turns the balance into a real budget: size past it and the open comes back 402, which is the failure a live bot has to handle and a frictionless simulator never shows you. reject_rate_pct is the one a retry loop is worth writing for.

Every field with its range: https://marginpad.io/trading-api/#sim

Examples

• examples/agent_loop.py: a signal loop that opens, manages and closes positions once a minute without polling storms.
• examples/webhook_server.js: receive position.closed / order.filled events with signature verification.
• examples/mcp.md: let Claude Desktop or Cursor trade on your paper account through the MCP server.

Limits

An API plan is its own product: a MarginPad Premium subscription buys nothing here, and an API plan buys nothing on the site. Every market-data endpoint is free and keyless, with no account and no trial. The paper-trading engine, the simulation, books, replay and the WebSocket stream are free for 7 days from the day the first key is minted (since 2026-10-13); after that they need a paid plan, and only webhooks and the AI read are gated by tier within it. Trade history is 30 days on the trial and 90 on a paid plan.

Measured in production: the busiest bot peaks at 66 requests a minute against the Free ceiling of 120, and no key has ever been rate-limited on any plan. Choose on keys and history, not on throughput.

Every response carries X-RateLimit-Limit / Remaining / Reset; on 429 both clients wait Retry-After and retry once. Out-of-range input is refused with a named error (leverage_max carries the market's cap), never silently clamped.

Honesty note

This is a simulator. Fees, funding and liquidation maths mirror real exchanges and every fill condition above is yours to set - but there is no order book behind impact_bps_per_100k, so market impact is modelled rather than measured on depth, and a stop, target or liquidation fills at its own level without paying the crossing cost. A bot that passes here still needs a small live test. Educational use, not financial advice.

MIT licensed.