MarginPad

MarginPad SDK

为机器人提供免费的加密货币期货模拟交易和免费市场数据。一个密钥，无需 KYC，无需存款。 使用实时价格测试策略或 AI Agent，模拟真实的费用安排、资金费率、强平、限价单和止损单、追踪止损、Webhook 和 WebSocket 流，然后将相同的代码用于真实交易所。

• 指南：https://marginpad.io/trading-api/
• 参考文档（OpenAPI，可在线试用）：https://marginpad.io/api-docs/
• 状态：https://marginpad.io/status/ - 更新日志：https://marginpad.io/api/changelog.xml
• 面向 Claude、ChatGPT 和 Cursor 的 MCP 服务：https://marginpad.io/trading-api/#mcp

背后的数据

这些客户端读取的市场数据由 MarginPad 自行测量，并免费以页面和 JSON 形式发布，无需密钥：

• 我们自己的采集器追踪九家交易所的强平数据：https://marginpad.io/liquidations/ · 实时数据流 https://marginpad.io/rekt/ · 按币种查看的图表，例如 https://marginpad.io/btc-liquidation-map/ · 实时热力图 https://marginpad.io/heatmap
• 从链上读取的 Hyperliquid 巨鲸仓位，提供精确的强平价格：https://marginpad.io/hyperliquid-whales/
• 资金费率、未平仓合约和多空比：https://marginpad.io/funding/ · https://marginpad.io/open-interest/ · https://marginpad.io/long-short/
• 一个问题，一个经过测量的答案：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/
• 此 API 背后的引擎也运行着模拟交易终端：https://marginpad.io/paper-trade（无需注册），以及赛季竞赛 https://marginpad.io/trading-competition/

安装

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

账簿、重置、权益、回放（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

使用 book 创建的密钥（在 POST /api/bot/key 上使用 {"act":"create","name":"rsi","book":"rsi"}）会在单独的交易日志中交易：一个策略、一把密钥、一份清晰的结果。回放期间，该密钥的每次交易调用都会根据光标所在的蜡烛图价格作用于回放交易日志；两次调用之间的每根蜡烛图都会检查止损、目标价和强平。

模拟由你设定

提供十八个字段和八种预设，让模拟交易场所符合你实际要交易的场景。默认设置刻意消除了交易摩擦；在你更改设置之前，已构建的任何内容都不会受到影响。

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 });

账簿（start_balance_usd、margin_enforced、leverage_max、max_notional_usd）、成交（slippage、slippage_bps、impact_bps_per_100k、exit_slippage、latency_ms、partial_fills、min_fill_pct、reject_rate_pct）、成本（taker_bps、funding、funding_mult）和强平（margin_venue、margin_tiers、mmr_pct）。

超出范围的值会被拒绝，不会被限制到边界值；而仓位在整个存续期间都会沿用其成交时的模拟设置。margin_enforced 会让余额成为真实的预算：超过预算的下单会返回 402。这是实盘机器人必须处理、而无摩擦模拟器永远不会呈现的失败情况。reject_rate_pct 是值得为其编写重试循环的选项。

查看每个字段及其范围：https://marginpad.io/trading-api/#sim

示例

• examples/agent_loop.py：每分钟运行一次信号循环，以开启、管理和关闭仓位，不会造成轮询风暴。
• examples/webhook_server.js：通过签名验证接收 position.closed / order.filled 事件。
• examples/mcp.md：让 Claude Desktop 或 Cursor 通过 MCP 服务在你的模拟账户上交易。

限制

计划	每分钟请求数	密钥	持仓数	账簿	Webhook
Free $0	120	3	50	1	-
Pro $27	600	10	200	5	3
Max $69	2000	30	500	20	15
Business $139	5000	100	1000	50	50

API 计划是独立产品：MarginPad Premium 订阅不包含这里的任何内容，API 计划也不包含网站上的任何内容。所有市场数据端点均免费且无需密钥，无需账户，也没有试用期。从创建第一个密钥之日起（自 2026-10-13 起），模拟交易引擎、模拟、账簿、回放和 WebSocket 流均可免费使用 7 天；此后需要付费计划，且只有 Webhook 和 AI 读取功能受该计划内的等级限制。试用期间的交易历史保留 30 天，付费计划保留 90 天。

生产环境的测量数据显示：最繁忙的机器人峰值为每分钟 66 次请求，低于 Free 计划每分钟 120 次的上限；任何计划下都没有密钥曾被限制速率。选择计划时应考虑密钥数量和历史记录，而非吞吐量。

每个响应都会包含 X-RateLimit-Limit / Remaining / Reset；收到 429 时，两个客户端都会等待 Retry-After，然后重试一次。超出范围的输入会被拒绝，并返回具名错误（leverage_max 会携带市场的上限），绝不会被静默截断。

诚实说明

这是一个模拟器。手续费、资金费和清算计算均与真实交易所一致，上述每项成交条件都由你设置——但 impact_bps_per_100k 背后没有订单簿，因此市场冲击是建模得出的，而非基于深度测量；止损、目标价或清算会在各自的价位成交，不会承担跨价成本。在这里通过测试的机器人仍需进行小规模实盘测试。仅供教育用途，不构成财务建议。

采用 MIT 许可证。