paradex_vault_summary
Retrieve vault summaries with balance, positions, activity, and performance metrics. Filter results using JMESPath expressions to analyze specific vaults or compare multiple vaults efficiently.
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:154-233 (handler)The primary handler function for the 'paradex_vault_summary' tool. It fetches vault summary data from the Paradex API endpoint 'vaults/summary', validates it using TypeAdapter(list[VaultSummary]), applies optional JMESPath filtering, sorting by address descending, pagination with limit/offset, and returns a structured dictionary including the schema, results, and metadata.
@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 model defining the output data structure for vault summaries, including fields for address, equity, TVL, ROI metrics (total, 24h, 7d, 30d), P&L, drawdowns, volumes, and depositor count. Used for validation and schema generation in the tool response.
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") ]