marginpad 2.9.1 → 3.0.0

package/README.md

@@ -37,6 +37,31 @@ const { position } = await mp.open({ symbol: 'BTC', side: 'long', margin_usd: 10
 mp.stream(ev => console.log(ev.type, ev.data));             // positions pushed on change, prices each tick
 ```
 
+## The simulation is yours to set
+<!-- sdk-sim: generated, do not hand-edit -->
+
+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.
+
+```python
+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
+```
+
+```js
+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.
@@ -44,13 +69,23 @@ mp.stream(ev => console.log(ev.type, ev.data));             // positions pushed
 - `examples/mcp.md`: let Claude Desktop or Cursor trade on your paper account through the MCP server.
 
 ## Limits
+<!-- sdk-limits: generated from API_PLANS, do not hand-edit -->
+
+| Plan | Requests/min | Keys | Open positions | Books | Webhooks |
+|---|---|---|---|---|---|
+| Free $0 | 120 | 3 | 50 | 1 | - |
+| Pro $39 | 600 | 10 | 200 | 5 | 3 |
+| Max $99 | 2000 | 30 | 500 | 20 | 15 |
+| Business $199 | 5000 | 100 | 1000 | 50 | 50 |
+
+An API plan is its own product: a MarginPad Premium subscription buys nothing here, and an API plan buys nothing on the site. The whole engine, the simulation, several books per key, the replay, the WebSocket stream and every market-data endpoint are free - only webhooks and the AI read are gated. Trade history is 30 days on Free 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.
 
-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.
+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.
+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.

package/index.d.ts

@@ -1,24 +1,61 @@
 export interface Position { id: string; symbol: string; side: 'long' | 'short'; entry_price: number; margin_usd: number; leverage: number; qty: number; liq_price: number; sl: number | null; tp: number | null; status: 'open' | 'closed' | 'liquidated'; opened_ts: number; mark_price?: number; unrealized_pnl_usd?: number; exit_price?: number | null; pnl_usd?: number | null; closed_ts?: number | null; trail_pct?: number; fee_rate_pct?: number; fee_venue?: string | null; }
-export interface OpenParams { symbol: string; side: 'long' | 'short'; margin_usd: number; leverage?: number; sl?: number; tp?: number; trail_pct?: number; type?: 'market' | 'limit' | 'stop'; limit_price?: number; client_order_id?: string; fee_venue?: string | null; dry_run?: boolean; }
+export interface OpenParams { symbol: string; side: 'long' | 'short' | 'buy' | 'sell'; margin_usd: number; leverage?: number; sl?: number; tp?: number; trail_pct?: number; type?: 'market' | 'limit' | 'stop'; limit_price?: number; client_order_id?: string; fee_venue?: string | null; dry_run?: boolean;
+  /** Override the account's simulation profile for THIS fill only. Writes nothing. */
+  slippage?: boolean; slippage_bps?: number; impact_bps_per_100k?: number; margin_tiers?: boolean; mmr_pct?: number; }
+/** What actually filled, on v2 opens. position.margin_usd is already the filled size; this says what you asked for. */
+export interface FillInfo { requested_margin_usd: number; filled_margin_usd: number; fill_pct: number; partial: boolean; slippage_pct: number; exit_slippage: boolean; latency_ms: number; taker_fee_pct: number; maintenance_margin_pct: number; maintenance_margin_from: string; }
+/** The eight ready-made simulations. A preset starts from the defaults, so it is a clean slate plus that configuration. */
+export type SimPreset = 'frictionless' | 'realistic' | 'binance' | 'bybit' | 'okx' | 'hyperliquid' | 'thin_book' | 'brutal';
+/**
+ * The whole paper-trading simulation. Send any subset; out-of-range values are REFUSED, never clamped.
+ * The three nullable fields take null to mean "use the measured table / the venue", not zero.
+ */
+export interface SimProfile {
+  preset?: SimPreset; reset?: boolean;
+  /** the book */
+  start_balance_usd?: number; margin_enforced?: boolean; leverage_max?: number; max_notional_usd?: number;
+  /** the fill */
+  slippage?: boolean; slippage_bps?: number | null; impact_bps_per_100k?: number; exit_slippage?: boolean;
+  latency_ms?: number; partial_fills?: boolean; min_fill_pct?: number; reject_rate_pct?: number;
+  /** the cost */
+  taker_bps?: number | null; funding?: boolean; funding_mult?: number;
+  /** the liquidation */
+  margin_venue?: string; margin_tiers?: boolean; mmr_pct?: number | null;
+}
 export class MarginPadError extends Error { code: string; status: number; body: any; }
 export class MarginPad {
+  static SIM_PRESETS: SimPreset[];
   constructor(key?: string, opts?: { baseUrl?: string; autoRetry?: boolean; timeoutMs?: number });
   price(symbol: string): Promise<{ symbol: string; price: number; change_24h_pct: number | null; ts: number }>;
+  prices(): Promise<any>;
   klines(symbol: string, interval?: string, end?: number): Promise<any[]>;
-  time(): Promise<{ server_time_ms: number; server_time_iso: string }>;
-  open(p: OpenParams): Promise<{ position?: Position; order?: any; dry_run?: boolean }>;
+  // NOTE: the method is serverTime(). This file declared a `time()` that the client has never had - a
+  // declaration for a method that does not exist is worse than no declaration, so it is gone.
+  serverTime(): Promise<{ server_time_ms: number; server_time_iso: string }>;
+  open(p: OpenParams): Promise<{ position?: Position; order?: any; dry_run?: boolean; fill?: FillInfo }>;
+  limitOrder(p: OpenParams): Promise<any>;
+  stopOrder(p: OpenParams & { stop_price?: number }): Promise<any>;
   close(id: string, opts?: { pct?: number; symbol?: string; client_order_id?: string }): Promise<{ position: Position }>;
   closeAll(): Promise<{ closed: number; positions: Position[] }>;
   sltp(id: string, p: { sl?: number | null; tp?: number | null; trail_pct?: number | null }): Promise<{ position: Position }>;
-  positions(): Promise<{ positions: Position[] }>;
+  positions(opts?: { status?: 'open' | 'closed'; since?: number; useEtag?: boolean }): Promise<{ positions: Position[] } | null>;
   orders(): Promise<{ orders: any[] }>;
   cancelOrder(id: string): Promise<{ order_id: string; status: string }>;
   modifyOrder(id: string, p: any): Promise<any>;
-  trades(opts?: { limit?: number; before?: number }): Promise<{ trades: Position[]; next_before: number | null }>;
+  trades(limit?: number, before?: number): Promise<{ trades: Position[]; next_before: number | null }>;
   account(): Promise<any>;
   balance(): Promise<any>;
-  markets(): Promise<any>;
-  fees(): Promise<any>;
+  equity(days?: number, stepMin?: number): Promise<any>;
+  reset(): Promise<any>;
+  accounts(): Promise<any>;
+  markets(assetClass?: string): Promise<any>;
+  /** The fee schedule. fees() reads, fees('binance') sets the account default, fees('') goes back to ours. */
+  fees(venue?: string): Promise<any>;
+  /** Three switches of the simulation, kept for compatibility. sim() is all of it. */
+  realism(o?: { slippage?: boolean; margin_tiers?: boolean; margin_venue?: string }): Promise<any>;
+  /** The whole simulation: read with no argument, set with any subset or a preset. */
+  sim(o?: SimProfile): Promise<any>;
+  /** The trading report. `costs` (fees, funding, gross vs net, kept_pct) is on every plan. */
   report(days?: number): Promise<any>;
   usage(): Promise<any>;
   webhooks(): Promise<any>;

package/index.js

@@ -17,7 +17,7 @@
   else root.MarginPadSDK = factory();
 })(typeof self !== 'undefined' ? self : this, function () {
   'use strict';
-  var VERSION = '2.9.1';
+  var VERSION = '3.0.0';
 
   function MarginPadError(code, message, status, extra) {
     var e = new Error(code + ': ' + (message || code));
@@ -114,6 +114,22 @@
   // Pass the same fields to open() to override the account for one fill only.
   MarginPad.prototype.realism = function (o) { return o === undefined ? this._get('/api/bot/v2/realism') : this._post('/api/bot/v2/realism', o); };
 
+  // ── the whole simulation (3.0) ───────────────────────────────────────────
+  // realism() above is three switches of this; sim() is all eighteen fields. The defaults are deliberately
+  // easy - a market order fills whole at the live price, maintenance margin is a flat 0.5%, the balance never
+  // refuses an open, there is no latency and no size impact - which is right for getting a bot RUNNING and
+  // optimistic for judging its edge.
+  //   await c.sim()                             -> your profile, every field with its range, the presets
+  //   await c.sim({ preset: 'realistic' })      -> the honest middle, in one call
+  //   await c.sim({ preset: 'bybit' })          -> Bybit's published fee and maintenance margin
+  //   await c.sim({ preset: 'brutal' })         -> worse than anything you will meet; if it survives this, it survives
+  //   await c.sim({ start_balance_usd: 2500, margin_enforced: true, slippage_bps: 8, latency_ms: 250 })
+  // Out-of-range values are REFUSED, never clamped, so a strategy is never measured under a setting you did
+  // not choose. A position keeps the simulation it was filled under, for life.
+  MarginPad.prototype.sim = function (o) { return o === undefined ? this._get('/api/bot/v2/sim') : this._post('/api/bot/v2/sim', o); };
+  // The eight presets, so an editor can complete them and a script can loop over them.
+  MarginPad.SIM_PRESETS = ['frictionless', 'realistic', 'binance', 'bybit', 'okx', 'hyperliquid', 'thin_book', 'brutal'];
+
   // ── webhooks (API Pro and up) ───────────────────────────────────────────────────────────────────────────────
   MarginPad.prototype.webhooks = function () { return this._get('/api/bot/v2/webhooks'); };
   MarginPad.prototype.addWebhook = function (url, events) { return this._post('/api/bot/v2/webhooks', { act: 'add', url: url, events: events }); };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "marginpad",
-  "version": "2.9.1",
+  "version": "3.0.0",
   "description": "MarginPad Bot API client: free crypto-futures paper trading for bots (REST + WebSocket + webhooks) and free market data. Zero dependencies.",
   "main": "index.js",
   "types": "index.d.ts",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/marginpad/sdk" },
+  "repository": { "type": "git", "url": "git+https://github.com/Marginpad/sdk.git" },
   "homepage": "https://marginpad.io/trading-api/",
-  "bugs": { "url": "https://github.com/marginpad/sdk/issues" },
+  "bugs": { "url": "https://github.com/Marginpad/sdk/issues" },
   "keywords": ["crypto", "futures", "paper-trading", "trading-bot", "backtest", "liquidations", "bybit", "binance", "api", "mcp", "ai-agent"],
   "engines": { "node": ">=18" },
   "files": ["index.js", "index.d.ts", "README.md"]