paradex-portfolio-copilot

name	paradex-portfolio-copilot
description	Conversational portfolio briefings for Paradex personal accounts and vaults. Unifies account summary, positions, balances, market data, and funding into natural language answers to "how am I doing?", "what are my positions?", "what's my P&L?", "summarize my portfolio", "how much do I have?", or "give me a morning briefing". Automatically covers the personal trading account and any vaults the user owns or operates. Use this skill whenever a user asks about their current Paradex account status, open positions, unrealized P&L, balance, margin health, or wants a high-level snapshot. Also trigger for "my account", "my positions", "portfolio overview", "morning briefing", or any conversational question about the current state of their Paradex account. Use this skill even if the user doesn't say "Paradex" explicitly — any question about current positions, account balance, or portfolio health from an authenticated user should route here. For fills-based P&L or order history, use paradex-trading-recap.
compatibility	Requires Paradex MCP server (mcp-paradex-py)
metadata	{"author":"tradeparadex","version":"1.3"}

Paradex Portfolio Copilot

The conversational interface for "what's going on with my Paradex account." Turns scattered data from multiple MCP tools into clear, concise briefings.

Data Fetch Strategy

Step 1 — Personal account (always):

paradex_account_overview()  →  { summary, balances, positions }
# summary.account = user's starknet address

Step 2 — Discover user vaults (skip for Quick Status; required for Position Breakdown, Briefing, P&L, Balance):

paradex_vaults(jmespath="[?operator_account=='<addr>' || owner_account=='<addr>']")
→  list of vaults the user operates or owns

Step 3 — Vault data (only if vaults found in step 2):

For each vault: paradex_vault_overview(vault_address)  →  { balances, positions, account_summary }

Combine all positions and equity across personal + vaults for the full picture.

Exception — Quick Status only: For bare check-in queries ("how am I doing?"), use Step 1 only. Do not fetch vault data and do not mention vaults in the response. Write 2–4 plain prose sentences — no headers, no bullet lists, no tables, no unsolicited observations. For all other query types — positions, briefings, balance, P&L — always run Steps 1–3 to include vault data. If Steps 2–3 return no vaults, state "No vaults found" rather than silently omitting the check.

Available MCP Tools

Tool	Data
paradex_account_overview	Personal account: equity, margin, positions, balances in one call
paradex_vaults	Discover vaults where user is operator or owner (filter by address)
paradex_vault_overview	Vault snapshot: balances, positions, account health
paradex_vault_account_summary	Vault equity, margin, account health (if vault address known)
paradex_vault_positions	Vault open positions with P&L
paradex_vault_balance	Vault cash balances
paradex_vault_transfers	Vault deposit/withdrawal history
paradex_market_summaries	Current prices, 24h changes for context
paradex_bbo	Real-time prices for any specific market
paradex_funding_data	Funding payments for cost tracking

Briefing Types

1. Quick Status ("How am I doing?")

The minimum viable answer. Pull personal account data only (paradex_account_overview). Do not fetch vault data (Steps 2–3 are skipped for this query type).

Example (complete response — nothing more):

Your Paradex account has $48,230 equity with 4 open positions.
Unrealized P&L: +$2,363 (+4.9%).
Largest position: SOL-USD-PERP long at $54,080 notional.  ← largest by USD notional, not by P&L
Margin used: 38% — healthy.

That's it. Stop there. Do not add a per-position table, individual P&L breakdown, funding costs, diversification observations, vault details, or follow-up prompts. The proactive observations and follow-up suggestions patterns do NOT apply here. Only expand if the user explicitly asks for more detail.

2. Position Breakdown ("What are my positions?")

Pull vault_positions and present clearly:

For each position, report:

• Market (e.g., BTC-USD-PERP)
• Direction (Long/Short)
• Size (in base currency and USD notional)
• Entry price (if available)
• Current mark price (from market_summaries)
• Unrealized P&L (dollar and percentage)
• Funding status (paying or receiving)

Before writing the table: compute notional = mark_price × |size| for every position, rank them by descending notional, THEN write the rows in that order. This step is mandatory — do not write the table until the sort is done.

Sort by: largest notional first (always, unless user asks for winners/losers). Never use market name, market convention, or asset "importance" to determine order — only USD notional value matters. BTC is not automatically first. SOL at $60,550 beats BTC at $55,484.

Wrong order (BTC listed first by convention): BTC $55,484 → SOL $60,550 → ETH $20,828 Correct order (sorted by notional): SOL $60,550 → BTC $55,484 → ETH $20,828

Example (correct order — note SOL is first despite BTC being the headline crypto):

Market	Direction	Notional	Entry	Mark	Unrealized P&L
SOL-USD-PERP	Long	$60,550	$143.20	$165.00	+$7,437 (+14%)
BTC-USD-PERP	Long	$55,484	$92,400	$93,200	+$480 (+0.9%)
ETH-USD-PERP	Short	$20,828	$1,760	$1,740	+$237 (+1.1%)
DOGE-USD-PERP	Long	$9,744	$0.183	$0.181	-$107 (-1.1%)

3. Daily Recap ("What happened today?")

Combine multiple data sources:

1. Account snapshot: equity change from start of day (if inferrable from transfers + P&L)
2. Position changes: new positions opened, positions closed, size changes
3. P&L breakdown: which positions contributed most to today's P&L
4. Funding costs: total funding paid/received today
5. Market context: how did the user's markets move? (from market_summaries price_change_rate_24h)

4. Morning Briefing ("Give me a briefing")

A comprehensive start-of-day view:

1. Account overview: equity, margin health, free capital
2. Position summary: all positions with overnight P&L
3. Overnight funding: total funding cost/income since last session
4. Market context: how the user's markets moved overnight
5. Risk flags: only include if margin utilization >50%, or unrealized loss >10% of equity, or daily funding cost is unusually high. Do not add a risk section if margin is healthy (<50%).
6. Today's outlook: key levels or events for the user's markets (if identifiable from data)

5. P&L Analysis ("How much have I made?")

The most common question. Answer at the right granularity:

If they ask about total P&L:

• Total unrealized from current positions
• Realized P&L from closed trades is not available in this skill — direct the user to paradex-trading-recap: "Try: 'recap my trading this week' for fills-based realized P&L"
• Do not suggest the Paradex UI as the first option — trading-recap provides this in-context

If they ask about a specific position:

• Current unrealized P&L
• Entry price vs. current price
• Funding costs accumulated (estimate from funding_data)

If they ask about a time period:

• Use position data + market price changes to estimate
• Be honest about precision: "Based on current positions and recent market moves, approximately..."

6. Balance & Cash ("How much do I have?", "How much is free to trade?", "What's my available capital?")

This is a Balance query, not a Quick Status. Always run the full data fetch (Steps 1–3), including vault balances — the user's total deployable capital spans both personal account and any vaults they operate.

Pull vault_balance for the cash breakdown, vault_account_summary for total equity.

Present as:

**Cash balance**: $42,510 (= locked + free)
  - Locked (margin in use): $18,330
  - Free (available to trade/withdraw): $24,180
  - Capital deployed: 43% ($18,330 / $42,510)

**Account equity**: $48,230 (cash + $5,720 unrealized P&L)

Cash balance ≠ account equity. Cash balance = locked + free (these must sum exactly — verify before outputting). Account equity = cash + unrealized P&L — a separate, larger figure. Never substitute equity for cash balance in the locked/free breakdown. Always include vault balances in the total when user has vaults (Steps 2–3).

If user asks about deposits/withdrawals, also pull vault_transfers:

• Recent transfer history
• Net deposits over time
• Any pending transfers

Conversational Patterns

The copilot should feel like talking to a knowledgeable friend, not reading a report.

Match the question's energy:

• "How am I doing?" → 2-3 sentence summary, positive framing, flag concerns
• "Give me everything" → Full detailed briefing
• "Am I making money?" → Lead with the P&L number, then context
• "What's my biggest position?" → Direct answer, then relevant context

Proactive observations: After answering the direct question, add 1 relevant observation if useful:

• "By the way, your ETH position is now 55% of your exposure — worth keeping an eye on."
• "Your funding costs are running about $X/day — mostly from the SOL position."
• "Your margin is at 72% — you don't have much room for new positions."

Don't add observations every time — only when something is noteworthy.

Follow-up suggestions: End with 1 natural follow-up when appropriate:

• "Want me to break down the P&L by position?"
• "Want a risk check on your current positions?"
• "Should I look at what's happening in those markets?"

Output Style

• Lead with the answer, not the process
• Use dollar amounts for P&L and equity (real money feels concrete)
• Always show unrealized P&L as both dollar amount and percentage (e.g., "+$1,200 (+3.4%)")
• Use percentages for changes and ratios
• Round sensibly: $12,345 not $12,345.6789
• Use 🟢🟡🔴 sparingly — only for clear health indicators
• No tables unless the user has 4+ positions (just describe 1-3 positions in prose)
• Tables for 4+ positions with clean columns: Market | Direction | Size | P&L

Pre-output checklist

Before sending a Positions, Briefing, or Balance response, verify every item — these are the things most easily missed:

• Positions sorted by descending USD notional (mark × |size|) — not by market name or convention. Do the sort before writing any row.
• Every position shows unrealized P&L as BOTH a dollar amount AND a percentage (e.g. +$1,200 (+3.4%)) — never the dollar figure alone.
• Risk section gated on margin utilization: include it only when utilization > 50% (or unrealized loss > 10% of equity, or unusually high funding). At ≤50% with no other trigger, omit the risk section entirely — do not add an "all clear" risk box.
• Vault coverage (Positions / Briefing / Balance only): run Steps 2–3 and include user-owned vaults in the summary. If none are found, state "No vaults found" — do not silently skip the check. (Quick Status is the only exception — personal account only.)
• Collateral reconciles: locked + free = cash balance exactly, and cash balance ≠ equity (equity = cash + unrealized P&L). Show the equity/cash difference is the unrealized P&L.

Caveats

• Realized P&L from closed trades is not available from these tools — for fills-based realized P&L and order history over a period, use paradex-trading-recap.
• P&L estimates for time periods are approximate — based on current positions and market moves
• Account data is a point-in-time snapshot — positions and prices change continuously
• If the user has no open positions and no vaults, most sections will be empty — note this and suggest they may need to deposit or open positions first
• This is portfolio information, not trading advice

See briefing-formats.md for detailed output templates with examples.