Paradex Portfolio Copilot

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=='' || owner_account=='']")
→  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 marketsummaries pricechangerate24h)

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%

(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](references/briefing-formats.md) for detailed output templates with examples.

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.