MCP Paradex Server

Instructions

Implementation Reference

• src/mcp_paradex/tools/vaults.py:154-233 (handler)

  The main handler function for the 'paradex_vault_summary' tool. It fetches vault summary data from the Paradex API, validates it using VaultSummary model, applies optional JMESPath filtering and pagination, and returns a structured response including schema information.
  @server.tool(name="paradex_vault_summary") async def get_vault_summary( vault_address: Annotated[ str, Field( default=None, description="The address of the vault to get summary for or None to get all vaults.", ), ], jmespath_filter: Annotated[ str, Field(default=None, description="JMESPath expression to filter or transform the result."), ], limit: Annotated[ int, Field( default=10, gt=0, le=100, description="Limit the number of results to the specified number.", ), ], offset: Annotated[ int, Field( default=0, ge=0, description="Offset the results to the specified number.", ), ], ) -> dict: """ Get a comprehensive summary of a specific vault or all vaults if no address is provided. Retrieves a summary of all important information about a vault, including balance, positions, recent activity, and performance metrics. This provides a high-level overview of the vault's current state. Use jmespath_filter to reduce the number of results as much as possible as number of vaults can be large. You can use JMESPath expressions to filter, sort, or transform the results. Examples: - Filter by TVL: "[?to_number(tvl) > `10000`]" - Filter by performance: "[?to_number(total_roi) > `5.0`]" - Sort by TVL (descending): "reverse(sort_by([*], &to_number(tvl)))" - Get top performers: "sort_by([*], &to_number(total_roi))[-3:]" - Filter by recent returns: "[?to_number(roi_24h) > `0.5`]" - Extract specific metrics: "[*].{address: address, tvl: tvl, total_roi: total_roi, volume_24h: volume_24h}" """ try: client = await get_paradex_client() params = {"address": vault_address} if vault_address else None response = await api_call(client, "vaults/summary", params=params) if "error" in response: raise Exception(response["error"]) results = response["results"] summary = vault_summary_adapter.validate_python(results) # Apply JMESPath filter if provided if jmespath_filter: summary = apply_jmespath_filter( data=summary, jmespath_filter=jmespath_filter, type_adapter=vault_summary_adapter, error_logger=logger.error, ) sorted_summary = sorted(summary, key=lambda x: x.address, reverse=True) result_summary = sorted_summary[offset : offset + limit] result = { "description": VaultSummary.__doc__.strip() if VaultSummary.__doc__ else None, "fields": VaultSummary.model_json_schema(), "vaults": result_summary, "total": len(sorted_summary), "limit": limit, "offset": offset, } return result except Exception as e: logger.error(f"Error fetching summary for vault {vault_address}: {e!s}") raise e
• src/mcp_paradex/models.py:273-383 (schema)

  Pydantic BaseModel defining the structure and validation for VaultSummary objects, which represent the output data from the tool. Provides the JSON schema via model_json_schema() used in responses.
  class VaultSummary(BaseModel): """Model representing a summary of a vault's performance and statistics.""" address: Annotated[str, Field(default="", description="Contract address of the vault")] owner_equity: Annotated[ str, Field( default="", description="Vault equity of the owner (% of ownership) in percentage, i.e. 0.1 means 10%", ), ] vtoken_supply: Annotated[ str, Field(default="", description="Total amount of available vault tokens") ] vtoken_price: Annotated[ str, Field(default="", description="Current value of vault token price in USD") ] tvl: Annotated[ str, Field( default="", description="Net deposits of the vault in USDC (deprecated; use net_deposits instead)", ), ] net_deposits: Annotated[str, Field(default="", description="Net deposits of the vault in USDC")] total_roi: Annotated[ str, Field(default="", description="Total ROI of the vault in percentage, i.e. 0.1 means 10%"), ] roi_24h: Annotated[ str, Field( default="", description="Return of the vault in the last 24 hours in percentage, i.e. 0.1 means 10%", ), ] roi_7d: Annotated[ str, Field( default="", description="Return of the vault in the last 7 days in percentage, i.e. 0.1 means 10%", ), ] roi_30d: Annotated[ str, Field( default="", description="Return of the vault in the last 30 days in percentage, i.e. 0.1 means 10%", ), ] last_month_return: Annotated[ str, Field( default="", description="APR return of the vault in the last trailing month in percentage, i.e. 0.1 means 10%", ), ] total_pnl: Annotated[str, Field(default="", description="Total P&L of the vault in USD")] pnl_24h: Annotated[ str, Field(default="", description="P&L of the vault in the last 24 hours in USD") ] pnl_7d: Annotated[ str, Field(default="", description="P&L of the vault in the last 7 days in USD") ] pnl_30d: Annotated[ str, Field(default="", description="P&L of the vault in the last 30 days in USD") ] max_drawdown: Annotated[ str, Field( default="", description="Max all time drawdown realized by the vault in percentage, i.e. 0.1 means 10%", ), ] max_drawdown_24h: Annotated[ str, Field( default="", description="Max drawdown realized by the vault in the last 24 hours in percentage, i.e. 0.1 means 10%", ), ] max_drawdown_7d: Annotated[ str, Field( default="", description="Max drawdown realized by the vault in the last 7 days in percentage, i.e. 0.1 means 10%", ), ] max_drawdown_30d: Annotated[ str, Field( default="", description="Max drawdown realized by the vault in the last 30 days in percentage, i.e. 0.1 means 10%", ), ] volume: Annotated[ str, Field(default="", description="All time volume traded by the vault in USD") ] volume_24h: Annotated[ str, Field(default="", description="Volume traded by the vault in the last 24 hours in USD") ] volume_7d: Annotated[ str, Field(default="", description="Volume traded by the vault in the last 7 days in USD") ] volume_30d: Annotated[ str, Field(default="", description="Volume traded by the vault in the last 30 days in USD") ] num_depositors: Annotated[ int, Field(default=0, description="Number of depositors on the vault") ]
• src/mcp_paradex/tools/market.py:47-54 (registration)

  Part of the get_filters_model tool that provides the output schema (JSON schema) for paradex_vault_summary to help users build precise JMESPath filters.
  tool_descriptions = { "paradex_markets": models.MarketDetails.model_json_schema(), "paradex_market_summaries": models.MarketSummary.model_json_schema(), "paradex_open_orders": models.OrderState.model_json_schema(), "paradex_orders_history": models.OrderState.model_json_schema(), "paradex_vaults": models.Vault.model_json_schema(), "paradex_vault_summary": models.VaultSummary.model_json_schema(), }
• src/mcp_paradex/tools/vaults.py:151-152 (helper)

  TypeAdapter for list[VaultSummary] used for Pydantic validation of API responses in the handler.
  vault_summary_adapter = TypeAdapter(list[VaultSummary])