# Paradex Pm Analyzer

> >

- **Type:** Skill
- **Install:** `agentstack add skill-tradeparadex-paradex-skills-pm-analyzer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tradeparadex](https://agentstack.voostack.com/s/tradeparadex)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tradeparadex](https://github.com/tradeparadex)
- **Source:** https://github.com/tradeparadex/paradex-skills/tree/main/skills/pm-analyzer

## Install

```sh
agentstack add skill-tradeparadex-paradex-skills-pm-analyzer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# 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` | asset_kind, delta1_cross_margin_params, option_cross_margin_params, order_size_increment |
| `paradex_system_config` | Live PM config per base asset: 24-scenario table, hedged/unhedged margin factors, mmf_factor, funding_provision_hour, vol_shock_params |
| `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](https://github.com/tradeparadex)
- **Source:** [tradeparadex/paradex-skills](https://github.com/tradeparadex/paradex-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-tradeparadex-paradex-skills-pm-analyzer
- Seller: https://agentstack.voostack.com/s/tradeparadex
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.