paradex_vault_summary
Read-only
Retrieve a comprehensive summary of a vault or all vaults, including balance, positions, activity, and performance metrics. Filter results using JMESPath expressions.
Instructions
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}"Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| vault_address | No | The address of the vault to get summary for or None to get all vaults. | |
| jmespath_filter | No | JMESPath expression to filter or transform the result. | |
| limit | No | Limit the number of results to the specified number. | |
| offset | No | Offset the results to the specified number. |
Implementation Reference
- src/mcp_paradex/tools/vaults.py:186-234 (handler)Main handler function for the paradex_vault_summary tool. Calls the 'vaults/summary' API endpoint, validates results via vault_summary_adapter, optionally applies a JMESPath filter, sorts by address, applies pagination (limit/offset), and returns a dict with description, fields schema, vaults list, and pagination metadata.
""" 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/tools/vaults.py:155-185 (registration)Tool registration decorator: @server.tool(name='paradex_vault_summary', annotations=ToolAnnotations(readOnlyHint=True)) on the async function get_vault_summary. Defines parameters: vault_address (optional), jmespath_filter (optional), limit (default 10, max 100), offset (default 0).
@server.tool(name="paradex_vault_summary", annotations=ToolAnnotations(readOnlyHint=True)) 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: - src/mcp_paradex/models.py:273-382 (schema)VaultSummary Pydantic model schema with fields: address, owner_equity, vtoken_supply, vtoken_price, tvl, net_deposits, total_roi, roi_24h/7d/30d, last_month_return, total_pnl, pnl_24h/7d/30d, max_drawdown, max_drawdown_24h/7d/30d, volume, volume_24h/7d/30d, num_depositors.
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") ] - apply_jmespath_filter helper used by the handler to apply JMESPath expressions for filtering/transforming vault summary data. Compiles the expression, converts data to dicts, searches, and validates back via the TypeAdapter.
def apply_jmespath_filter( data: list[T], jmespath_filter: str | None, type_adapter: TypeAdapter, error_logger: Callable[[str], Any] | None = None, strict: bool = False, ) -> list[T]: """ Apply a JMESPath filter to a list of data objects. Validates the JMESPath filter, applies it to the data after converting to dicts, and converts the filtered data back to the original type. Args: data: List of data objects to filter jmespath_filter: JMESPath expression to apply type_adapter: Pydantic TypeAdapter to convert filtered data back to original type error_logger: Optional function to log errors strict: Whether to use strict validation when converting back to original type (default: False) experimental_allow_partial: Whether to allow partial validation when converting back (default: True) Returns: Filtered list of data objects Raises: ValueError: If the JMESPath filter is invalid """ if not jmespath_filter or jmespath_filter == "null": return data try: # Validate the filter expression jmespath.compile(jmespath_filter) # Convert to dict for JMESPath to work properly data_dicts = [item.model_dump() for item in data] filtered_data = jmespath.search(jmespath_filter, data_dicts) # Convert back to original type if filtered_data: return type_adapter.validate_python( filtered_data, strict=strict, experimental_allow_partial="on", ) else: return [] except ParseError as e: error_message = f"Invalid JMESPath filter: {e}" if error_logger: error_logger(error_message) logger.error(error_message) raise ValueError(error_message) except Exception as e: error_message = f"Error applying JMESPath filter: {e}" if error_logger: error_logger(error_message) logger.error(error_message) raise - Tool description helper mapping that includes 'paradex_vault_summary' -> models.VaultSummary.model_json_schema() for use in tool documentation/descriptions.
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(), }