Paradex Pm Analyzer

Paradex PM Analyzer

Computes margin (IMR/MMR) for a Paradex account and optionally places a delta-neutral hedge order.

Script

A standalone Python script is available at scripts/paradex_pm_analyzer.py. Run it directly when you need a terminal report without going through the full MCP skill flow.

Auth (pick one)

| Method | Credential | Notes | |--------|------------|-------| | Long-lived API key | PARADEX_JWT_TOKEN or PARADEX_API_KEY | Set once; works until revoked | | Short-lived JWT | PARADEX_JWT_TOKEN | Obtained from auth endpoint or via Claude / MCP | | Pre-fetched data | --data FILE — no credentials | Replay a saved --json snapshot |

The script is read-only — it computes the hedge order payload but does not place orders. Pass the printed payload to Claude (paradex_create_order) or place it via the Paradex UI.

Usage

# Margin report (JWT in env)
export PARADEX_JWT_TOKEN=eyJ...
uv run scripts/paradex_pm_analyzer.py

# What-if
uv run scripts/paradex_pm_analyzer.py --what-if BTC-USD-PERP BUY 0.01

# Compute delta hedge and print the order payload
uv run scripts/paradex_pm_analyzer.py --delta-hedge

# Save full snapshot (for offline replay or sharing with Claude)
uv run scripts/paradex_pm_analyzer.py --json > snapshot.json

# Replay offline — no credentials needed
uv run scripts/paradex_pm_analyzer.py --data snapshot.json

# Override PM config
uv run scripts/paradex_pm_analyzer.py --pm-config btc-pm.json

To verify the math without live credentials: python3 scripts/test_pm_math.py (22 unit tests, no auth needed).

Available MCP Tools

| Tool | What it provides | |------|-----------------| | paradex_account_summary | Exchange IMR, MMR, account value, free collateral (ground truth) | | paradex_account_positions | Open positions with market, side, size | | paradex_open_orders | Open limit orders with market, side, size, price | | paradex_account_balance | Token balances (USDC + any spot tokens) | | paradex_market_summaries | Mark prices, IV, funding rate, greeks (delta) per market | | paradex_markets | assetkind, delta1crossmarginparams, optioncrossmarginparams, ordersizeincrement | | paradex_system_config | Live PM config per base asset: 24-scenario table, hedged/unhedged margin factors, mmffactor, fundingprovisionhour, volshockparams | | paradex_pre_trade_check | Collateral check + BBO before placing hedge order | | paradex_create_order | Place the hedge order on confirmation | | paradex_order_status | Verify hedge order accepted post-submit |

Margin Methodology

Portfolio Margin is account-level, not per-instrument. The margin_methodology field from /account/margin determines the pipeline. Fetch it from the server-side cached endpoint (no auth required):

GET /api/account-margin.json
→ { "margin_methodology": "cross_margin"|"portfolio_margin", "configs": [...], "fetched_at_iso": "..." }

If that endpoint is unavailable, default to cross_margin.

margin_methodology == "cross_margin"      → XM formulas for all instruments
margin_methodology == "portfolio_margin"  → 4-step PM pipeline for all instruments

Cross-Margin (XM) Formulas

Delta-1 (Perps / Futures)

Uses delta1_cross_margin_params: imf_base, mmf_factor

notional = |size| × mark_price
IMR      = notional × imf_base
MMR      = IMR × mmf_factor

Long Options

IMR = mark_price × size       # mark premium is the margin
MMR = IMR × 0.5

Short Options

Uses option_cross_margin_params OTM/ITM brackets. See references/xm-formulas.md.

Spot Balance Margin

spotBM = Σ |balance[token]| × price[token]   (for token ≠ USDC)

Total

IMR = Σ IMR_per_position + spotBM
MMR = Σ MMR_per_position + spotBM

Calculated values match exchange within ~$0.02 (fee provision rounding).

Portfolio Margin (PM) Pipeline

Only when margin_methodology == "portfolio_margin".

Before computing PM margin, call paradex_system_config and extract the config for the account's base asset from portfolio_margin:

cfg = paradex_system_config().portfolio_margin[base_asset]
scenarios          = cfg.scenarios            # list of {spot_shock, vol_shock, weight} — the 24-scenario table
HEDGED_MF          = cfg.hedged_margin_factor
UNHEDGED_MF        = cfg.unhedged_margin_factor
MMR_FACTOR         = cfg.mmf_factor
FUNDING_PERIOD_H   = cfg.funding_provision_hour   # hours per funding period (typically 8)
DTE_FLOOR          = cfg.vol_shock_params.dte_floor_days
VEGA_POWER_LT      = cfg.vol_shock_params.vega_power_long_dte
VEGA_POWER_ST      = cfg.vol_shock_params.vega_power_short_dte

See references/pm-pipeline.md for the full 4-step scenario scan and Black-Scholes repricing formulas.

Output Format

1. Summary card — IMR, MMR, account value, free collateral, margin utilisation %, liquidation distance (account_value − MMR)
2. Calc vs exchange — show both; note small diff (~$0.02) is normal
3. Per-position table — market, side, size, mark price, delta, IMR contribution
4. Risk callout — flag if liquidation distance < 20% of account value

Delta Hedge Mode

When asked to compute a delta-neutral hedge (and optionally place it):

1. Compute portfolio delta

portfolioDelta = Σ greeks.delta × signed_size
  signed_size = +size (BUY) or −size (SELL)

greeks.delta comes from paradex_market_summaries.

2. Compute neutralising size

# Default hedge instrument: BTC-USD-PERP (delta ≈ 1.0)
# Choose side that reduces |portfolioDelta|

neutral_size = −portfolioDelta / (side_sign × instrument_delta)
# Round DOWN to order_size_increment from paradex_markets

If neutral_size ≤ 0 for chosen side, flip to the other side.

3. Pre-trade check

Run paradex_pre_trade_check(market, side, neutral_size) to verify collateral and size limits.

4. Show the order payload and confirm before submitting

Always present the computed order and wait for explicit confirmation before calling paradex_create_order:

Delta hedge order
  Market:  BTC-USD-PERP
  Side:    SELL
  Size:    0.00047 BTC
  Type:    MARKET

  Portfolio delta before: +0.000477
  Portfolio delta after:  ~0.000000
  IMR change: $3.25 → $3.64 (+$0.39)

Place this order? [yes/no]

5. Submit and verify

On confirmation: paradex_create_order with client_id: "delta-hedge-{unix_ms}", then paradex_order_status to confirm.

What-If Mode

When asked "what if I add X position":

1. Add hypothetical to current positions/orders
2. Re-run correct margin formula
3. Show: new IMR, new MMR, Δ margin, new liq distance, new portfolio delta

Caveats

• margin_methodology is served via /api/account-margin.json (cached server-side, refreshed periodically). A dedicated MCP tool would make this cleaner but is not yet available.
• Calculated IMR/MMR may differ from exchange by ~$0.01–$0.02 due to fee provision not being directly accessible.
• Delta hedge uses greeks.delta from paradex_market_summaries; for options near expiry or deep ITM/OTM, live delta can shift quickly — re-run before submitting.
• Short option XM margin is not yet empirically verified against exchange values.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tradeparadex
• Source: tradeparadex/paradex-skills
• License: MIT

Install and usage instructions live in the source repository linked above.