Sdk

io.github.Marginpadv2.9.1Updated Oct 8, 2026

Free crypto-futures paper trading and live market data for AI agents. 28 tools; no key for data.

VerifiedStreamable HTTPWeb executableAI & MLFinance

Overview

AI-generated overview

Lets an assistant fetch live crypto-futures market data and run simulated paper trades with fees, funding, liquidations and stops.

What it does
A remote MCP server for crypto-futures paper trading and market data, described as having 28 tools. Market-data tools work without a key; paper-trading tools open and manage simulated positions with leverage, limit and stop orders, trailing stops, and account, equity and replay views. It also covers multiple trading books per account and a replay mode that runs the same calls against a past day of candles.
When to use it
Useful when you want an assistant to test a trading strategy or agent loop against live prices without risking real money, or to pull crypto-futures quotes and account state into a conversation. It is a simulator, so results still need a small live test before real use.
Requirements
A remote endpoint at marginpad.io over streamable HTTP; no local package is required. Market-data tools need no credentials. Paper-trading tools need a MarginPad Bot API key sent in the X-API-Key header. Free tier limits apply: 120 requests per minute per key, 3 keys, 50 open positions.
Before you install
The X-API-Key header carries a MarginPad Bot API key (mpb_...) that authorizes trading actions on the account's paper books, so treat it as a secret. Trading tools open, modify and close positions and can reset a book; these act on simulated funds, not real money. The server is a simulator: fees, funding and liquidations are modelled and slippage is estimated, not measured on real depth.

Installation

In SourceWeft

  1. Open Sdk in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "sdk": {
      "type": "http",
      "url": "https://marginpad.io/mcp"
    }
  }
}

README

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.

Install

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

Python

python
from marginpad import MarginPad
mp = MarginPad("mpb_...")                                   # key from https://marginpad.io/trading-api/print(mp.price("BTC"))                                      # keyless market datapos = 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 positionmp.sltp(pos["id"], trail_pct=1.5)                           # trailing stop, ratcheted server-sideprint(mp.account())

JavaScript

js
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)

python
mp.accounts()                                   # every book of the account with lifetime numbersmp.reset()                                      # this key's book back to $10,000 (archived, never deleted)mp.equity(days=30, step_min=60)                 # equity curve + max drawdownmp.replay_start("BTC", "2026-09-11", speed=120) # run the same code through a past day, 12 minutes per daymp.replay(interval=5, bars=120)                 # cursor, price, candles up to the cursormp.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.

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

Free: 120 requests/minute per key, 3 keys, 50 open positions. Premium: 600/minute, 10 keys, 200 open positions. 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 math mirror real exchanges; there is no order book, so slippage is modelled, not measured on depth. A bot that passes here still needs a small live test. Educational use, not financial advice.

MIT licensed.

Source: README.md at commit fcf5d5f

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v2.9.1LatestOct 8, 2026